Python Factory

A Polylith monorepo built for AI agents. Every brick exposes a full MCP interface; agents interact through MCP, not direct imports.

Architecture

python-factory/
├── components/     # Reusable logic bricks (polymorphic, adapter-based)
├── bases/          # Entry points — pure transport shells (api, worker, mcp_server, blueprint)
├── projects/       # Deployable artifacts (companion_x)
└── BRICKS_INDEX.yaml

Core principles

1. MCP-first — Every brick exposes full MCP primitives (tools, resources, prompts). Cross-brick calls go through the MCP gateway, never direct imports.
2. Polymorphic / agnostic — All bricks use the adapter pattern via runtime/ports.py Protocol interfaces. No hardcoded backends.
3. <200 LOC per file — Files split into mcp/ and runtime/ subdirs as needed.
4. Clean architecture — Business logic in runtime/, MCP surface in mcp/, public API in interface.py.
5. Bases are pure transport — API, worker, MCP server, blueprint depend only on the MCP aggregator, not on individual bricks.
6. Views as data — Bricks declare UI views as dicts in mcp/views.py. Adapters render to HTMX, React, JSON, Flet, or anything else.

Bricks (31 components + 4 bases)

The canonical exemplar is components/workflow/. Every brick has:

• BRICK.yaml — metadata
• runtime/ports.py — Protocol interfaces
• runtime/runtime.py — business logic
• runtime/adapters/ — backend implementations (memory, redis, neo4j, aws, …)
• mcp/ — full MCP primitives (deterministic, operational, authoring tools + resources + prompts + views)
• interface.py — public API: create_server + Runtime

See BRICKS_INDEX.yaml for the full catalog and .agents/steering/brick-anatomy.md for the structural template.

Companion X

projects/companion_x/ is the only sub-project in this distribution — a Next.js dashboard (frontends/next-dashboard/) that drives the MCP gateway over HTTP/SSE. It renders shadcn/ui components from ReactAdapter JSON in an IDE-like workbench (ActivityBar | Canvas | ChatSidebar) with AG-UI streaming.

Local dev runs without containers: bricks use lightweight adapters (ChromaDB for KB and memory, networkx for graph, SQLite for events, in-memory adapters for cache/worker/storage).

Quickstart

# Source env + start API (requires Polylith PYTHONPATH)
set -a; source projects/companion_x/.env; set +a
PYTHONPATH="$(find "$PWD/bases" "$PWD/components" -type d -path '*/src' | paste -sd: -)" \
  uv run python -m factory.api.main

# Start dashboard (separate terminal)
cd frontends/next-dashboard && npm run dev

The API runs on :8001, the dashboard on :3000 (with API_URL=http://localhost:8001 in .env.local).

Verification

uv run pytest                          # tests
uv run python -c "import factory.workflow.interface"  # import smoke

License

Business Source License 1.1. See LICENSE for terms. Converts to Apache 2.0 on the Change Date listed in the license file.

Status

This is a public, source-available release of an experimental research codebase. The internal version remains private and continues to evolve. Some descriptive documentation may reference modules or services that are not part of this distribution.