Project roadmap

Source: ROADMAP.md at f0c3d3702a6cf77529a8ecd307103558484dffee. This is a repository snapshot, not a claim about the latest published release.

Roadmap

Ambition — The leading framework for tool and application conversion

Our ambition is to make intpot the world’s leading Python framework for defining tools and converting applications across CLI, HTTP API, and MCP interfaces. Start with typed functions, grow to realistic multi-module applications, and give people and coding agents one predictable way to build, inspect, adapt, and own those interfaces.

Robustness is how we earn that position, not a ceiling on what we build. We aim to expand conversion coverage substantially while preserving behavior where possible and explaining adaptations or required intervention where frameworks differ. A successful conversion should mean more than syntactically valid output.

Define typed Python tools once, serve them as CLI, API, or MCP interfaces, and generate ordinary framework code that users can inspect and own. Keep the public entry points small: App.tool(), App.serve(), App.eject(), and load(...).to_cli()/to_api()/to_mcp().

What leadership should mean

• Broad practical coverage: real applications with rich types, validation, command hierarchies, multi-module dependencies, and lifecycle-sensitive behavior—not just demos.
• Predictable conversion: inspectable plans and diagnostics distinguish preserved behavior, explicit adaptations, and work requiring user intervention.
• Verified fidelity: runnable real-world examples and behavioral compatibility tests demonstrate what survives conversion across supported frameworks and versions.
• Simple adoption: small public APIs, useful agent skills, actionable errors, and readable generated code without an intpot runtime dependency.
• An extensible ecosystem: once the contracts are stable, documented backend extension points let contributors broaden framework and protocol coverage without duplicating the core.
• Performance at application scale: measure and improve loading, inspection, projection, and generation on representative projects without sacrificing correctness.

The next milestone

Build confidence in the current supported subset as the foundation for wider coverage:

• supported conversions preserve behavior;
• unsupported or lossy cases explain what cannot be preserved;
• live and generated interfaces agree on their shared interface semantics;
• documentation and shipped agent skills describe executable behavior.

The phases below express priority, not promised release dates. Correctness and contract consolidation come before deeper transformations or performance infrastructure.

v0.9 — Current foundation

• One definition, three live interfaces: registered Python functions can run through Typer, FastAPI, or FastMCP, or be ejected as framework source.
• Six conversion directions: existing Typer, FastAPI, and FastMCP applications can be inspected and converted within the documented supported subset.
• Immutable conversion schema: ApplicationSchema, ToolSchema, and ParameterSchema support inspection and generation; ToolInfo compatibility views remain available.
• Target projections: conversion exposes intermediate target projections before rendering. Some effective parameter defaults are still decided by templates.
• Shared interface identity: framework-visible tool names, source Python parameter bindings, target-visible parameter aliases, and FastAPI route metadata remain distinct in the canonical schema and are consumed consistently by live and generated interfaces.
• Strict schema serialization: supported non-JSON defaults use tagged $intpot envelopes; executable default rendering preserves supported value semantics.
• Basic body transforms: supported CLI output and return conventions are translated; FastAPI response annotations account for value, None, and fallthrough outcomes.
• Explicit dependency refusal: inspection records FastAPI dependencies, but conversion to CLI/MCP rejects unsupported dependency semantics rather than silently dropping them.
• Practical tooling: recursive Typer command inspection, direct import extraction, collision-safe directory output, actionable source failures, scaffolding, and agent skills.
• Verification: generated-artifact execution tests, conversion snapshot drift tests, and a Python 3.11–3.14 compatibility matrix.

Live serving currently uses registered callables and compatibility metadata; it does not consume the immutable schema in the same way as generation. Completing shared interface semantics is planned below. Live execution and standalone export also have deliberately different capabilities: a callable may depend on runtime values that cannot be exported.

Phase 1 — Correctness and honest documentation

• Preserve control flow in API/MCP-to-CLI conversion, including early returns, loop returns, and unreachable side effects. Implementation returns are retained and the outer CLI wrapper prints their values (#131).
• Replace substring-based import filtering with structural binding analysis. Remove imports only when their uses have actually been removed or translated (#132).
• Add behavioral live-versus-ejected tests for parameter placement, defaults, response shapes, async behavior, errors, and naming—not only route/schema presence. CLI, FastAPI, and FastMCP now execute the same registered tools through both paths.
• Align the README, architecture illustrations, cookbook, and shipped skills with the implementation. Distinguish App from IntpotApp, including .project() and .tools behavior; keep public-command guidance in parity (#121).
• Execute cookbook and shipped-skill examples, including single-tool CLI applications, so prose and expected output cannot drift independently of tests.
• Keep contributor guidance accurate and agent installation predictable (#123, #122).

Acceptance: the original failure cases have generated-consumer regressions, documented examples execute, and the supported Python/framework matrix remains green. Source-level audit findings must be reproduced before treating their fixes as verified.

Phase 2 — Complete the shared interface contract

• Centralize target parameter placement for CLI, FastAPI, and FastMCP in an immutable schema projection. CLI and FastAPI renderers consume the choice; FastMCP records its single native parameter placement without adding a redundant adapter.
• Preserve framework-visible tool names separately from sanitized Python bindings and make default API routes explicit in the target projection. Live and generated CLI, FastAPI, and FastMCP interfaces consume the shared name policy.
• Preserve valid source callable parameter bindings separately from canonical sanitized names so generated CLI, FastAPI, and FastMCP bodies execute after sanitization and deterministic collision suffixing.
• Preserve FastAPI route identity and documentation metadata — explicit operation IDs, route names, summaries, descriptions, tags, and deprecation state — in the canonical schema and both live and generated FastAPI applications.
• Preserve target-visible parameter aliases separately from canonical and source binding names. FastAPI aliases and exact Typer option declarations, including short and paired boolean flags, survive live and generated interfaces and cross-target conversion.
• Centralize the remaining target decisions for required/default rules, descriptions, and response policy. Canonical schema values remain authoritative, but the focused name and alias slices do not unify those policies.
• Reuse the parameter-placement resolver where live CLI and FastAPI builders choose a location, without requiring live serving to construct an ApplicationSchema; runtime-only opaque defaults remain usable. FastMCP has no competing location choice.
• Transform this focused projection with dataclasses.replace and share unchanged parameters and tools. Mutable ToolInfo remains a compatibility boundary.
• Extend the same shared immutable boundary to the remaining interface and response decisions without changing established response policy in the placement slice.
• Isolate existing default-value freezing, serialization, identity, and source-rendering behavior behind a small private module. Preserve supported values and regression coverage; do not replace these contracts with generic repr() or JSON conversion.
• Expose structured conversion diagnostics: preserved, adapted, unsupported, and requiring manual implementation. Diagnose unresolved symbols and missing bodies instead of letting generated source appear complete without qualification.

Acceptance: shared behavior is defined once, projections explain the emitted interface, and compatibility APIs retain their documented behavior. No generated-code execution is introduced as a prerequisite for live serving.

Phase 3 — Practical conversion coverage

• Carry a bounded dependency closure within one source module: referenced helper functions, constants, classes, models, defaults, annotations, decorators, and base classes. Start with explicitly supported cases; diagnose dynamic or ambiguous cases rather than promise arbitrary Python recovery.
• Preserve parameter descriptions and supported Annotated metadata across targets (#1, #3, #9, #38).
• Preserve repeatable Typer/Click options and collection cardinality in target schemas.
• Support package and sibling imports with explicit loading semantics. Direct file loading currently does not add the source directory to sys.path.
• Support explicit app selection and bounded factory loading without making directory discovery import every Python file.
• Define multi-method FastAPI route semantics instead of reducing them to one method.
• Generate nested command hierarchies (#2). Recursive inspection already works; hierarchy generation remains separate work.
• Add realistic runnable examples demonstrating these capabilities and their refusal paths (#5).

Acceptance: each new capability includes a supported-case example, an unsupported-case policy, and execution through the generated target—not merely a matching source string.

Phase 4 — Profile, then optimize

• Establish reproducible benchmarks separating cold startup, inspection, projection, and rendering for small and larger applications. Record Python and dependency versions.
• Measure the benefit of immutable structural sharing during projection.
• Reuse function analysis and a module/import index within one inspection operation instead of reparsing the same module for each tool.
• Evaluate compiled-template reuse while preserving per-render alias isolation and concurrency safety.

There are no speedup commitments yet. Avoid persistent caches, parallel conversion, native extensions, or new performance dependencies until representative measurements justify them. Low-risk removal of redundant work can accompany earlier correctness changes when tested.

Future goals — Rich applications and deeper transformations

These remain strategic goals, not discarded features. Their scope and implementation need research; delivery should proceed in independently useful increments with explicit semantic contracts and acceptance criteria. We aim for broad real-world coverage, not an impossible promise of universal equivalence between frameworks.

• Dependency injection mapping (#20): preserve applicable dependency ordering, caching, security, exception propagation, and cleanup lifetime. Replacing Depends() with a context manager alone is not equivalence. Keep unsupported conversions rejected until a particular subset is proven.

• Pydantic model parameters (#17): define target-specific representation and validation before choosing flattening. MCP and HTTP can represent structured inputs differently from CLI arguments.

• Cross-module dependency resolution: only after same-module closure is reliable; distinguish project code from external packages and avoid implicit environment provisioning.

• Deeper body/error transforms (#19): add individual supported patterns for HTTP/MCP errors, context objects, streaming, and background work. Reject cases without a meaningful target equivalent.

• Simultaneous serving (#32): defer until interface parity is established; specify transports, startup, shutdown, cancellation, and CLI interaction before adding serve --all.

• Backend ecosystem: stabilize inspector, projection, and generator contracts, then document extension points and a backend conformance suite. Add frameworks and protocols where concrete use cases justify them; new backends must explain their fidelity limits.

• Specification-driven workflows (#22, #43): support useful OpenAPI import/export paths while distinguishing interface descriptions from recoverable implementation behavior.

Current focus and enduring guarantees

Typer, FastAPI, and FastMCP are the current delivery focus, not a permanent ceiling. Backend extensibility follows stable contracts and demonstrated demand; do not build a plugin platform merely to organize the current three implementations.

The guarantees below remain important as coverage grows:

• Keep generated output ordinary Python with no intpot runtime dependency; other application dependencies may still be required.
• Do not add a runtime bridge for adapting arbitrary existing framework applications. Building live interfaces from intpot.App remains a core capability.
• Do not attempt unrestricted Python transpilation or claim that every framework behavior has a lossless equivalent.
• Keep variadic tool signatures unsupported: *args and **kwargs do not have one consistent CLI/API/MCP representation. Prefer explicit named parameters.
• Preserve the trusted-source boundary: detection imports code; inspection and dry-run conversion are not sandboxes.
• Keep the core small as backends expand: share stable semantics rather than adding a second generalized intermediate representation or duplicating conversion policy.

Linked items have existing issue discussions; unlinked items are directional work, not implementation commitments. Check current issues and open work before starting a scoped change. See CONTRIBUTING.md for setup and contribution guidance.