AIPod

A compositional computation model and governed runtime for AI-built Python software.

AIPod lets AI create software without giving the model control of the runtime. Humans define the architecture and governance rules; AI discovers, creates, selects, and composes components inside those boundaries; AIPod validates and executes the resulting program deterministically.

Component: (State, Input, Dependencies) -> Result(State', Output, Effects)
Pipeline:  Cn ∘ ... ∘ C2 ∘ C1

Software = Components + Dependencies + Composition + State + Effects
AIPod   = Software Model + Governance

AIPod is currently alpha software. Components, dependency injection, sequential composition, contracts, validation, execution traces, CLI workflows, and the desktop Studio are implemented. First-class effects, parallel pipelines, retries, and compensation are on the roadmap.

Why AIPod?

Most AI coding tools generate files. AIPod generates a system that remains inspectable and operable after generation:

• Components provide reusable capabilities and business transformations.
• Contracts describe required inputs, produced outputs, and dependencies.
• Pipelines compose compatible components into executable programs.
• Interfaces expose programs through CLI, web, desktop, API, workers, or schedulers.
• PipelineContext carries input and transient state through a run.
• Dependency injection provides deterministic runtime assembly and singleton reuse.
• Validation and traces make generated systems reviewable and debuggable.

The result is ordinary Python. AIPod does not hide the source or require a proprietary deployment target.

The Four-Layer Model

Capabilities            Business logic          Composition             Delivery
Providers       --->    Services        --->    Pipelines       --->    Interfaces
database, HTTP          use-case logic           execution order         CLI, web, desktop,
Redis, queues           and transformation       and state flow           API, worker, schedule

Provider

A Provider wraps infrastructure or an external capability: a database, filesystem, HTTP client, Redis client, message producer, or model gateway. It is injected into Services and reused by the container.

Service

A Service implements one business transformation. It reads inputs from PipelineContext, uses injected Providers, and returns a dictionary of outputs. Returned values are merged into the context for downstream components.

Pipeline

A Pipeline is an ordered composition of Services. Before a visual pipeline is saved, AIPod checks whether each component's output contract can satisfy the next component's input contract.

Interface

An Interface is an executable boundary around one or more Pipelines. A web server, desktop window, CLI command, API route, message consumer, or scheduled job belongs here—not in the business Pipeline itself.

Quick Start

Python 3.10 or newer is required.

git clone https://github.com/wangzhongren/ai_pod_cli.git
cd ai_pod_cli

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

pip install -e ".[studio]"

Configure an OpenAI-compatible model once. The global configuration is reused by every project:

aipod config set OPENAI_API_KEY sk-your-key
aipod config set OPENAI_BASE_URL https://api.openai.com/v1
aipod config set OPENAI_MODEL your-model-name

Create and build a project:

mkdir expense_app
cd expense_app
aipod init
aipod pod "Build an expense tracker with add, list, summary, and delete operations" --yes

Then inspect or run it:

aipod inspect project
aipod run add_expense --params "{\"amount\": 42.5, \"category\": \"food\"}"
aipod studio .

aipod pod reuses compatible components and routes already registered in the project. Restarting Studio or describing another feature does not automatically recreate the entire Pod.

AIPod Studio

AIPod Studio is a native desktop shell built with pywebview and WebView2 on Windows. It provides a VS Code-inspired workspace while preserving the Python runtime underneath.

pip install -e ".[studio]"
aipod studio .

From Studio you can:

• open or switch project directories and initialize an ordinary folder;
• describe an application and let AI build components, pipelines, and an entry point;
• manually register a complete Provider or Service;
• inspect the graph from Providers to Services, Pipelines, and Interfaces;
• compose a Pipeline by selecting Service nodes in execution order;
• inspect syntax-highlighted source in an editor tab;
• start discovered CLI, web, desktop, API, or Python entry points;
• stream process output in the integrated terminal;
• inspect validation results and recent execution traces.

The graph supports wheel zoom, canvas panning, fixed controls, collapsible navigation sections, and selectable nodes. Built-in runtime helpers are hidden by default so the graph focuses on application architecture.

Build Workflows

Describe the Whole Pod

aipod pod "Collect articles, remove duplicates, summarize them, and expose a CLI report" --yes
aipod pod --file requirements.md --yes

The command plans the architecture, reuses compatible existing beans, creates missing Providers and Services, composes Pipelines, registers routes, and generates an entry point when appropriate.

Build Incrementally

Generate components:

aipod create --category provider --name ArticleRepository --desc "Persist and query articles in SQLite"
aipod create --category service --name SummarizeArticles --desc "Produce a concise report from collected articles"

Register hand-written code:

aipod add --category provider --name RedisStore \
  --class-path modules.providers.redis_store.RedisStore \
  --desc "Redis-backed cache and idempotency store"

Compose and run a route:

aipod compose "Collect articles, deduplicate them, then summarize the result" --name daily_report
aipod run daily_report --params "{\"topic\": \"AI\"}"

Runtime Model

Every run starts with a PipelineContext:

from ai_pod_cli.context import PipelineContext

ctx = PipelineContext(params={"topic": "AI"})
ctx.set("articles", [{"title": "Example"}])
articles = ctx.get("articles", [])

A Service performs one transformation:

from ai_pod_cli.context import PipelineContext


class SummarizeArticles:
    def execute(self, ctx: PipelineContext) -> dict:
        articles = ctx.get("articles", [])
        summary = "\n".join(item["title"] for item in articles)
        return {"summary": summary}

A Pipeline resolves components from the Pod and composes them with |:

from ai_pod_cli.config import load_beans
from ai_pod_cli.container import Pod, build_container
from ai_pod_cli.context import PipelineContext
from modules.services.collect_articles import CollectArticles
from modules.services.summarize_articles import SummarizeArticles


def run(ctx: PipelineContext) -> dict:
    container = build_container(load_beans())
    S = Pod(container)
    return (S(CollectArticles) | S(SummarizeArticles)).execute_all(ctx)

Each component is resolved as a singleton within its container. Each dictionary result is merged into the context, and every step records its component, result preview, and duration.

Structured Results

Components may keep returning dictionaries, or use explicit computation results:

from ai_pod_cli import Effect, Failure, Success


def execute(self, ctx):
    if not ctx.params.get("invoice_id"):
        return Failure(
            "invoice_id is required",
            code="invalid_input",
            retryable=False,
        )

    return Success(
        output={"published": True},
        effects=(
            Effect("message", "invoices", "publish"),
        ),
    )

Success.output is merged into PipelineContext. An explicit Failure stops the remaining sequential Pipeline and produces a failed execution trace. Legacy dictionary returns remain fully compatible.

Execution Policies

Retry and fallback policies are declared where a component is composed:

flow = (
    S(FetchRemoteInvoice)
    .retry(3, delay_seconds=0.2)
    .fallback(ReadCachedInvoice)
    | S(RenderInvoice)
)
result = flow.execute_all(ctx)

Policies are visible in execution steps through attempts, status, last_error, and fallback. Exceptions still propagate normally when no retry or fallback policy handles them.

Contracts and Governance

beans_config.json is the machine-readable component pool. A component entry records identity, import path, category, description, dependencies, and inferred input/output contracts.

{
  "id": "SummarizeArticles",
  "class_path": "modules.services.summarize_articles.SummarizeArticles",
  "category": "service",
  "dependencies": ["ArticleRepository"],
  "inputs": {"articles": "list"},
  "outputs": {"summary": "str"}
}

Current validation covers importability and registration, the required Service boundary, route and Pipeline structure, adjacent contract compatibility, context-based argument flow, rejection of sys.exit() inside Pipelines, and project-level diagnostics in both CLI and Studio.

Contracts currently use inferred lightweight type names. Rich schemas and stricter static composition are planned.

Redis and Message Queues

Redis, Kafka, RabbitMQ, and similar systems fit the same model:

Redis client / Queue producer  -> Provider
Cache or publish use case      -> Service
Ordered business flow          -> Pipeline
Message consumer process       -> Interface

For example, a RabbitMQProvider owns connections and publish/consume primitives, a PublishInvoice Service expresses the business operation, and a worker entry point receives messages and invokes an AIPod route. Long-running listeners remain Interfaces so infrastructure lifecycle does not leak into reusable business components.

Project Structure

expense_app/
├── modules/
│   ├── providers/          # Infrastructure capabilities
│   └── services/           # Business transformations
├── pipelines/              # Composed execution routes
├── beans_config.json       # Component pool and contracts
├── routes.toml             # Route-to-pipeline registry
├── config.toml             # Project configuration
├── requirements.txt        # Generated project dependencies
├── server.py               # Example discovered interface
└── .aipod/
    └── runs/               # Runtime traces (gitignored)

The global model configuration lives at ~/.aipod/config.toml. Project configuration and generated code remain local to each project.

CLI Reference

Run aipod COMMAND --help for complete arguments.

Development

git clone https://github.com/wangzhongren/ai_pod_cli.git
cd ai_pod_cli
python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -e ".[studio]"
python -m unittest discover -s tests -q

The package uses setuptools; the desktop frontend is bundled as a package asset and does not require a separate Node build.

Security

• Keep API keys in global config or environment variables; never commit them.
• Review AI-generated code and dependencies before executing an unfamiliar project.
• Treat Providers as privileged boundaries because they can access files, networks, databases, and external services.
• Use least-privilege credentials and isolate untrusted generated projects.

Roadmap

• Effect approval and denial policies
• Parallel, asynchronous, event, and streaming composition
• Timeout, rollback, and compensation operators
• Rich schema contracts and stronger static Pipeline checking
• Sandboxed execution and approval policies for privileged Providers
• Reusable component packages and a governed capability registry

License

MIT