cadtopo 0.0.1

Every great idea starts at zero.
Start with CodeZero.

The open-source platform for building automations visually.
Powered by AI, running wherever you want.

What is CADTopo?

CADTopo (Cost-Aware Dynamic-Topology) is a framework for orchestrating teams of LLM agents that collaborate to solve a task. Instead of a fixed pipeline, the agents that participate — and how they pass information to each other — are decided fresh every round, and each agent runs on the cheapest model that the current risk justifies.

It is an implementation of the DyTopo protocol, extended with cost-aware model routing. In short:

• Per-round agent selection — only the agents relevant to the current goal are activated (no LLM calls wasted on the rest).
• Dynamic topology — the agents describe what they can offer and what they need, and the router builds the round's communication graph from those descriptors.
• A manager (meta-agent) — reads each round's output, picks the deliverable, scores it, and decides whether to stop or set a new goal.
• Cost-aware routing — every agent and the manager carry a ladder of models (cheap → expensive) and climb it only when the signal (low confidence, low score, running out of rounds) warrants it.

In one sentence: the right agents, wired the right way, on the cheapest model that gets the job done — decided anew each round.

How it works

Each round runs in two phases so information can flow within the round:

                    ┌─────────────────────────────────────────┐
   user task  ──▶   │ 1. COARSE SELECT   which agents run?     │  (embedding match, no LLM)
                    │ 2. DESCRIBE        what do they offer /   │  (cheap LLM pass)
                    │                    need this round?       │
                    │ 3. TOPOLOGY        build the round graph  │  (router, no LLM)
                    │ 4. WORK            run agents in order,    │  (the real work)
                    │                    routing hand-offs      │
                    │ 5. REVIEW          manager scores & picks │  (manager LLM pass)
                    └─────────────────────────────────────────┘
                                     │
                       halt?  ──▶ return best deliverable
                       else   ──▶ next round with a new goal

The manager halts as soon as the deliverable's score Φ crosses the success threshold; otherwise it keeps steering until the round cap is reached. The final answer is the highest-scoring round's deliverable.

Core building blocks

Installation

CADTopo targets Python ≥ 3.10. We recommend uv:

git clone https://github.com/code0-tech/cadtopo.git
cd cadtopo
uv sync            # install dependencies into a local .venv

Or with plain pip:

pip install -e .

Models are called through LiteLLM, so you can use OpenAI, Anthropic, OpenRouter, local models, and more — just by changing the model string.

Quickstart

from cadtopo import Agent, Backbone, Router, Manager, EmbeddingModel, CadTopoAI

# 1. Define your agents (each with a role and a model).
agents = [
    Agent(
        name="Developer",
        skill_definition="Writes the Python implementation.",
        system_prompt="You are a senior Python developer. Return only the function.",
        api_provider="openrouter/meta-llama/llama-3.1-8b-instruct",
        api_key="sk-...",
    ),
    Agent(
        name="Tester",
        skill_definition="Reviews and validates the implementation.",
        system_prompt="You are a QA engineer. Point out any bugs.",
        api_provider="openrouter/meta-llama/llama-3.1-8b-instruct",
        api_key="sk-...",
    ),
]

# 2. Wire the router and manager.
router = Router(agents=agents, embedding_model=EmbeddingModel())
manager = Manager(api_provider="openrouter/meta-llama/llama-3.1-8b-instruct", api_key="sk-...")

# 3. Build the system and run it.
system = CadTopoAI(manager=manager, router=router, max_rounds=5)
answer = system.run("Implement a function that reverses a string.")
print(answer)

Giving an agent a cost-aware model ladder

Pass multiple Backbones instead of a single model, cheapest first. The selector climbs the ladder only when an agent is unsure or the round budget runs low:

Agent(
    name="Developer",
    skill_definition="Writes the Python implementation.",
    backbones=[
        Backbone(model="openrouter/meta-llama/llama-3.1-8b-instruct", cost=0.06, api_key="sk-..."),
        Backbone(model="openrouter/anthropic/claude-3.5-sonnet",      cost=0.20, api_key="sk-..."),
        Backbone(model="openrouter/openai/gpt-5",                     cost=30.0, api_key="sk-..."),
    ],
)

Only the relative order of the cost values matters to the selector.

Example: HumanEval

A complete, runnable example lives in examples/humaneval/. It runs a four-role team (Researcher, Designer, Developer, Tester) over the HumanEval coding benchmark and reports pass@1 plus a per-model cost breakdown.

cd examples/humaneval
cp .env.example .env          # then fill in PROVIDER and AUTH
uv run humaneval.py

The agents' roles and prompts are plain Markdown under agents/<role>/ — edit them to change behaviour, no Python needed. Set BASELINE=1 to bypass CADTopo and get a single-pass reference number on the same tasks.

Project layout

src/cadtopo/
  orchestrator.py   # CadTopoAI — runs the rounds
  router.py         # coarse selection + topology induction
  manager.py        # the meta-agent (scoring, halting, next goal)
  agent.py          # the worker agent
  selection.py      # cost-aware model-ladder selection
  backbone.py       # a single model + its cost
  embedding.py      # skill/goal/query/key matching
  tools.py          # native tool-calling support
  schema/           # pydantic schemas for structured LLM output
examples/humaneval/ # end-to-end benchmark example
tests/              # test suite

Run the tests with:

uv run pytest

License

Licensing varies per component. See the LICENSE file in this repository and in each subproject for details.

Made with ❤️ by the CodeZero community