Schema and parameter reference

`App`

App(name: str = "intpot-app") stores registered functions. App.tool(*, name: str | None = None, description: str | None = None) returns a decorator and registers the original function. The name defaults to the function name; the description defaults to its docstring (or the empty string). Names are normalized for generated interfaces while the declared interface name is retained.

Registration rejects variadic positional (*args) and keyword (**kwargs) parameters with ValueError; their shape cannot be consistently represented in CLI, HTTP, and MCP modes. Explicit parameters use evaluated annotations when available, annotation text otherwise, and fall back to str when none is declared. Return annotations are retained; missing annotations remain distinct from -> None.

app.serve(mode, *, host="127.0.0.1", port=8000) supports cli, api, and mcp. It raises RuntimeError when no tools are registered and ValueError for unknown modes. API serving uses Uvicorn and defaults to loopback. app.eject(target) supports cli, api, and mcp, returns source text, and raises ValueError for an unknown target. The generated source depends on its target framework, not on Intpot as a runtime.

CLI operations

intpot serve SOURCE --cli|--api|--mcp [--host HOST] [--port PORT]: exactly one mode is required. HTTP defaults to 127.0.0.1:8000; host and port apply to API mode.
intpot inspect SOURCE [--json] [--verbose]: inspect one source or discover a directory; JSON includes source path, source type, and serialized tools.
intpot eject SOURCE --to cli|api|mcp [--output PATH]: eject an Intpot App to standalone source; without output it writes code to stdout.
intpot to cli|api|mcp SOURCE [--output PATH] [--verbose] [--dry-run]: convert detected framework apps; output may be a file or directory. A same-target source is rejected.
intpot init scaffolds a project; intpot add skills installs supported agent guidance. Run intpot COMMAND --help for the installed version’s exact flags.

`ApplicationSchema`

The frozen schema is the normalized boundary between inspection/registration and generation:

Field	Meaning
`name`	Display/application name
`source_type`	`python`, `cli`, `api`, or `mcp`
`tools`	Immutable tuple of `ToolSchema` records
`source_path`	Resolved input path when compiled from a file
`target_type`	Target kind on a projected schema, otherwise absent

ApplicationSchema.from_tools(...) compiles compatibility ToolInfo instances; .to_tools() returns detached mutable records; .to_dict() yields a JSON-compatible representation. compile_app(source_type, app_instance, source_path=...) compiles a live app. load(path_or_instance) detects a source and returns IntpotApp; its cached .schema, detached .tools, .project(target), .to_cli(), .to_api(), .to_mcp(), and .write(path, target) provide the Python conversion API. Passing the same source target to .project() is rejected.

`ToolSchema` and `ParameterSchema`

A tool includes name, description, parameters, return_type, function_body, is_async, HTTP http_method and route_path, operation ID/summary/description/tags/deprecation, dependency identifiers, source imports, and original interface name. Values may be absent when a framework does not provide them or the inspector cannot recover them.

A parameter includes its name, type annotation, default/required state, description, HTTP parameter source and placement, binding name, interface name, and aliases. In FastAPI, supported route metadata is read from registered routes and carried into API output. Depends and Security dependencies are recorded for diagnostics, not executed or translated: API-to-CLI/MCP conversion rejects them, including nested, router-level, and application-level dependencies.

Schema immutability protects the compiled snapshot: nested parameter/tool collections and supported mutable defaults are detached/frozen. Compatibility objects returned by .tools are detached copies. A default the schema cannot safely preserve (for example, a locally defined Enum or unsupported object) can fail schema compilation rather than becoming misleading generated source.

Runtime and generated behavior

At runtime, App retains the registered callable and metadata. The runtime builders create a Typer command app, FastAPI app, or FastMCP server. Async functions are recognized and routed through async-compatible builders; confirm the target framework’s behavior by executing generated code. Parameter annotations and defaults drive the interface schema, but framework-specific validation and coercion can differ. An output file is inspectable source; generation does not carry arbitrary source framework lifecycle, middleware, dependencies, or configuration.

Dependency extras

Target	Install
Base and CLI	`pip install intpot`
FastAPI and Uvicorn	`pip install 'intpot[api]'`
FastMCP	`pip install 'intpot[mcp]'`
Both optional targets	`pip install 'intpot[all]'`

Intpot requires Python 3.11 or newer. The current declared minimums are Typer 0.9.0, FastAPI 0.100.0, and FastMCP 2.0.0; actual resolved versions come from the package installer and should be tested in your environment.