intpot AGENTS.md

AGENTS.md

Guidance for coding agents working on intpot. If you want intpot's skills for your own project instead, run intpot add skills.

What intpot is

Two halves that meet at one schema:

• Runtime — @app.tool() registers a function; App.serve() builds a live Typer / FastAPI / FastMCP instance, App.eject() returns standalone source.
• Converter — intpot to cli|mcp|api reads an existing Typer / FastMCP / FastAPI app and generates the equivalent in another framework.

Both compile an immutable ApplicationSchema (src/intpot/core/models.py) containing ToolSchema and ParameterSchema records. Inspectors and registrations still create mutable ToolInfo compatibility models at the edges; projection and generation consume the canonical schema directly. When you add a capability, ask which side of that boundary it belongs on.

   @app.tool()                    source .py file
        |                    DETECT -> INSPECT
        +-----> ApplicationSchema <----+
                     ToolSchema[]
              |                  |
     live framework          GENERATE
       instance            (Jinja template)

Layout

Path	What's there
core/models.py	Canonical ApplicationSchema/ToolSchema/ParameterSchema plus compatibility models
core/detector.py	Identifies the framework; imports the source file to do it
core/inspectors/	Framework → ToolInfo
core/generators/ + templates/*.j2	ApplicationSchema (or legacy ToolInfo) → source code
core/transforms.py	Rewrites bodies and return types between frameworks
runtime.py, runtime_builders.py	The App class and live instance builders
commands/	One module per CLI command; cli.py wires them together
templates/skills/	Shipped to users by intpot add skills

Coding guidelines

Rules for changing intpot source — including the ones that each cost a real bug — and the architectural contracts a change has to keep live in src/intpot/AGENTS.md. Agents read the nearest file in the directory tree, so editing source picks them up automatically.