OkPy is an automation-development environment and AI-assisted tool builder that runs inside Autodesk Revit through the Orkestra add-in. It is designed to let AEC professionals create working Revit utilities—including their user interfaces and back-end logic—without building and packaging a conventional compiled add-in from scratch. Users can write tools directly, ask the OkPy Agent to generate them from plain-language requirements, test them against a Revit model, save them as portable OkPy files, and deploy approved tools locally or through Orkestra.
OkPy is broader than a fixed collection of commands. It combines three related offerings: a development environment for custom automation; an AI Agent that generates and revises tools; and a public library of ready-made Revit utilities. Orkestra supplies the host integration, ribbon access, tool distribution, analytics, permissions, and enterprise deployment layer. This makes OkPy most comparable to a low-code development platform, scripting environment, and AI coding assistant combined—not to a single-purpose Revit plug-in.
The product's key promise is to shorten the path from an automation idea to a repeatable, deployable Revit command. Its key risk is equally important: generated or user-written code can modify live project data at scale. Successful adoption therefore depends on testing, code review, release control, model backups, and clear separation between experimental and production tools.
Product Architecture
OkPy Editor
The full editor is aimed at tool creators. It combines a code editor, automatically generated input controls, a debugging console, result handling, and tool metadata in one environment. Current Revit documentation begins new tools in C#, while OkPy's broader documentation and history also describe Python and CPython-based development. Existing scripts may therefore require interpreter-specific review when moving between Revit generations.
OkPy Agent
The Agent provides a simplified conversational workflow. A user describes the Revit task, desired controls, and output; the Agent asks clarifying questions when needed, drafts the code and interface, and presents the result for testing. Published examples include a modeless Door Summary dashboard and a grid-renumbering utility. The generated result is a deterministic tool that can be saved and rerun, rather than a one-time chat response.
Orkestra Integration
OkPy ships with Orkestra and opens from the Orkestra ribbon tab in Revit. Orkestra can organize OkPy, Dynamo, and Grasshopper automations, place approved commands on Revit ribbons through Quick Access, distribute content across a firm, manage environments, and provide analytics. Local OkPy creation can be used independently, while organization-wide cloud deployment and management depend on Orkestra services and plan entitlements.
Public Tool Library
OkPy Tools is a browsable library of completed automations with documentation and demonstrations. It provides immediate value to non-developers and also serves as a reference for the kinds of interfaces and Revit API workflows that can be built.
Typical Tool-Creation Workflow
- Open OkPy in Revit. Open a model, select the Orkestra ribbon tab, and launch OkPy.
- Choose a starting mode. Create a blank tool in the editor, use the simplified Agent, or begin from a library example.
- Describe the requirement precisely. Define the target categories, selection scope, parameters, transactions, units, interface controls, expected results, and failure conditions.
- Generate or write the tool. Build the logic and user interface with C#, Python-compatible workflows, or Agent assistance, depending on the current environment.
- Test in sandbox mode. Documentation shows a Test mode in which model changes are undone when the test window closes. This allows interface and result verification before saving.
- Debug and refine. Use the console, results, screenshots, markups, and follow-up prompts to correct errors or improve the interface.
- Save the tool. Store it locally as an OkPy file. Saving is explicit; the Agent does not automatically preserve the generated tool.
- Publish when approved. Upload to an Orkestra workspace for controlled sharing, or deploy locally when cloud distribution is unnecessary.
- Add to the production ribbon. Use Orkestra's Quick Access and workspace controls to expose vetted tools to end users without giving them the development environment.
- Monitor and maintain. Track usage, revise tools when Revit APIs or standards change, and retain tested versions for rollback.
Interface and Development Capabilities
- Automatically generated interfaces: OkPy can turn declared inputs into a user-facing form, avoiding the need to hand-code every dialog.
- Advanced interfaces: Current product material describes WPF applications and web views for tools requiring data grids, color pickers, spreadsheets, complex layouts, or modeless interaction.
- Model-aware prompts: Users can describe Revit categories, parameters, filters, and interactions in ordinary language. PDFs, spreadsheets, screenshots, and images can be attached as contextual references in supported Agent workflows.
- Clarification and iteration: The Agent can ask questions when a requirement is ambiguous and maintain code state through a longer development conversation.
- Markup workflow: Recent releases allow users to draw notes, arrows, boxes, and labels over a generated interface or host-screen capture, then send the marked image back to the Agent.
- Reusable inputs and components: Developers can create, organize, and share input controls rather than rebuilding common interface elements.
- Debug console: The editor exposes diagnostic output during development, which is essential for identifying Revit API, transaction, data-type, and selection errors.
- Recovery snapshots: OkPy takes a local recovery snapshot before each run, retains up to five snapshots per tool, and opens restored snapshots as copies. This protects development work but is not a substitute for model backup or source control.
Current Ready-Made Revit Automations
The public OkPy Revit library currently advertises approximately fourteen tools. The catalog changes over time, but the published set demonstrates the platform's range across documentation, data, maintenance, modeling, and analysis.
- PDF and DWG Exporter: Batch-exports sheets and printable views to PDF and DWG. It pools host-model and loaded-link content into one selection list, builds filenames from view or sheet parameters, and uses native Revit export settings.
- Add Parameter to Project Families: Adds shared or non-shared parameters to selected editable component families and reloads them into the project. It supports parameters from an existing shared-parameter file or newly created definitions and reports skipped or failed families.
- Parameter Mapper: Copies, combines, splits, or transforms values from source parameters into target parameters. Mapping presets can be saved and shared.
- Material Find & Replace: Finds uses of a selected material and replaces them with another material across the model.
- Linked & Imported DWG Detector: Lists linked and imported DWGs, identifies their owner views, and supports highlighting or navigating to a placement.
- Place Family Instances from DWG Layer: Reads block insertion points on a selected linked-DWG layer and places a chosen Revit family type at those locations on the selected level.
- Wall Types Filters Creator: Creates view filters for wall types, assigns customizable graphic overrides, applies them to view templates, and generates a color-coded legend.
- Sheets Alignment: Aligns selected sheets to a reference sheet to standardize viewport or title-block-related arrangements.
- Rotate View: Rotates plan views beyond routine cardinal orientation workflows.
- 3D View by Workset Creator: Creates a separate 3D view for each selected workset.
- View Template Cleaner: Identifies and removes unused view templates.
- Unreferenced View Cleaner: Removes selected views that are not placed on sheets.
- Hatch Pattern Creator: Generates a hatch pattern from 2D line geometry.
- Shadow Study: Builds a viewer from active-view geometry, including links, visualizes the sun path and projected shadows, and can record the result as a video.
Illustrative Agent-Built Workflow
OkPy's documentation uses a Door Summary dashboard to demonstrate the complete Agent workflow. The request specifies a level filter, family/type search, fire-rating filter, live counts, a sortable table, details for the selected type, and a Refresh command. The Agent produces a floating modeless dashboard, which can remain open while the user works in Revit. The developer tests it against the current model, verifies counts and filters, closes Test mode to roll back changes, and then saves or publishes the tool.
This example is significant because it goes beyond generating a short script. It demonstrates specification by natural language, a custom user interface, live model queries, interaction while Revit remains available, safe testing, local packaging, and enterprise publishing. Comparable tools could be created for warnings, family auditing, parameter QA, sheet review, standards checks, data extraction, or firm-specific model-maintenance tasks.
Local, Cloud, and Enterprise Deployment
- Local files: Tools can be saved as portable OkPy files and run without publishing them to an organization.
- Local Orkestra features: Orkestra's documented free tier includes the local Revit player, local Quick Access commands, and playlists.
- Cloud workspaces: Approved tools can be published to online workspaces for organized distribution and controlled updates.
- Ribbon delivery: Administrators can expose tools as familiar Revit ribbon buttons, allowing end users to run an approved command without editing its code.
- Cross-platform automation library: Orkestra can manage OkPy alongside Dynamo and Grasshopper automation and distribute content to Revit, Civil 3D, AutoCAD, and Rhino.
- Enterprise controls: Current product material references analytics, environments, GitHub synchronization, schedules, SSO, Azure AD, console management, and playlists. Availability depends on the Orkestra plan.
- Autodesk Construction Cloud: Recent releases add tooling for Issues, RFIs, Submittals, Forms, Photos, Assets, Clash results, properties, reviews, sheets, Docs metadata, links, Takeoff, and project administration using the host's signed-in Autodesk session.
Pricing, Availability, and Compatibility
OkPy Agent Plans
- Community: Free, with a 5 daily prompt limit, a standard AI model, basic code generation, and community support.
- Pro Monthly: Currently listed at US$24 per month, with unlimited daily prompts, 50 super conversations per month, access to more advanced AI models, and priority support.
- Pro Annual: Currently listed at US$200 per year, equivalent to about US$16.67 per month, with the same published Pro allowances.
OkPy and Orkestra
Foundational OkPy documentation describes the programming environment as free and included with Orkestra. Orkestra itself has a free local tier; cloud deployment, enterprise administration, and related services use subscription plans. Firms should distinguish the cost of the AI Agent from the cost of organization-wide Orkestra management.
Revit Compatibility
Current public pages do not present a single definitive OkPy version matrix. Community evidence shows Orkestra 2.0 operating across Revit 2020–2026 after an installer correction, and current documentation addresses Revit 2025 CPython behavior. The latest release information identifies Orkestra 2.5.1.2. Compatibility should therefore be confirmed against the exact Revit, Orkestra, Python/.NET, add-in, and package versions used by the firm rather than inferred from isolated forum reports.
Practical BIM and Automation Assessment
Where OkPy Adds Value
- Rapid prototyping: BIM staff can move from a workflow problem to a tested interface and command much faster than with a conventional add-in project.
- Bridges the skills gap: The Agent makes Revit API automation more accessible to users who understand the BIM problem but are not professional software developers.
- Firm-specific utilities: OkPy is well suited to narrow standards, QA, naming, data, selection, documentation, and cleanup requirements that commercial add-ins may not address.
- Reusable deterministic tools: Once generated and approved, the output can be saved, versioned, deployed, and rerun consistently instead of relying on a fresh AI response each time.
- Interface development: Automated forms, dashboards, and advanced interface options reduce one of the biggest barriers to turning scripts into user-friendly firm tools.
- Integrated distribution: Orkestra can move a successful prototype into controlled ribbon deployment without a separate software-distribution stack.
- Shared automation ecosystem: The same management platform can accommodate OkPy, Dynamo, and Grasshopper, reducing fragmentation for multidisciplinary design-technology teams.
Best-Fit Users
OkPy is most useful for BIM coordinators, design technologists, computational designers, Revit power users, digital-practice teams, and developers who need to build and maintain a portfolio of internal automations. It can also serve noncoders when the Agent produces a well-bounded tool and a qualified reviewer validates the result. Firms seeking only one fixed command may prefer a conventional add-in with a narrower support surface.
Limitations and Governance Considerations
- Generated code can be wrong: A plausible interface or successful test does not prove that the tool handles every project state, category, unit, phase, design option, workset, link, or failure condition.
- Live-model risk: Revit API tools can modify or delete large numbers of elements. Test mode protects the development run described in the documentation, but production use still requires backups, worksharing controls, and rollback procedures.
- Version sensitivity: Revit API changes and the shift from IronPython to CPython can break previously working tools. Community examples document .NET collection and Python interoperability differences in Revit 2025.
- Code review remains necessary: AI output should be reviewed for transaction boundaries, exception handling, unit conversion, element filtering, null values, performance, and unintended changes.
- Security exposure: Tools can access project data and, depending on their code, local files, network resources, spreadsheets, web services, or Autodesk Construction Cloud. Limit who can develop, publish, and update production tools.
- Dependency management: Python packages, .NET libraries, Dynamo packages, and Revit builds must be controlled to keep deployed automations reproducible.
- User-interface quality varies: Agent-generated forms may require refinement for accessibility, validation, cancel behavior, progress feedback, localization, and large projects.
- Library tools still require testing: Public tools should not be assumed to match firm parameters, naming, templates, coordinates, links, export standards, or approved content.
- AI plan limits: The free Agent tier has prompt limits and basic generation; Pro allowances include a finite number of premium conversations.
- Limited independent benchmarking: Available evidence is dominated by Orkestra documentation, release notes, demonstrations, and community posts. Public long-term comparisons of generated-tool reliability are limited.
Recommended Evaluation Before Production Deployment
- Confirm official support for every deployed Revit version, the current Orkestra release, required runtimes, and the intended Python or C# engine.
- Install OkPy in a controlled test environment and review code signing, antivirus behavior, permissions, update channels, and network endpoints.
- Select a small, measurable workflow with a clear manual baseline and low consequence if it fails.
- Write acceptance criteria covering scope, element categories, parameter bindings, units, worksets, links, phases, design options, undo behavior, and error reporting.
- Generate the tool with the Agent or editor, then inspect the code before running it against a model.
- Test in OkPy Test mode and confirm that temporary model changes are rolled back as documented.
- Repeat testing on detached copies of small, large, central, linked, and intentionally imperfect projects.
- Validate performance, warnings, model size, transactions, element ownership, synchronization, and results after reopening the file.
- Publish only reviewed versions to a restricted workspace; separate development, pilot, and production libraries.
- Assign an owner, version number, supported-Revit range, change log, test model, and rollback package to every production tool.
- Restrict Agent and publishing rights according to role, and audit tools that read files, call web services, or access Autodesk Construction Cloud.
- Measure time saved, failure rate, maintenance effort, support demand, and adoption before scaling the workflow across the firm.
Sources Consulted
- OkPy documentation — Introduction
- OkPy documentation — Getting started in Revit
- OkPy documentation — Build with the Agent
- OkPy documentation — Recovery and tool backups
- OkPy Tools — Revit automation library
- Orkestra — AEC automation at scale
- OkPy Agent — current plans
- Orkestra GitHub — current release notes
- Orkestra community — multi-version Revit compatibility discussion
- Orkestra community — Revit 2025 CPython compatibility example
Advertisement
No comments:
Post a Comment