Spaces:
Paused
Paused
File size: 56,825 Bytes
287f3d3 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 | ---
title: B2D — Business to Development
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
---
# B2D — Business to Development
> An autonomous, multi-agent AI system that turns a vague business idea into a
> complete, validated software engineering blueprint.
**Built for the DevOps Hackathon.** You type one sentence — "I want to build a
platform where users can book football fields" — and a team of AI agents takes
over: it interviews you, drafts requirements, designs the architecture, the
database, the API, and the full DevOps stack (Dockerfile, `docker-compose.yml`,
GitHub Actions CI/CD), then cross-reviews everything for consistency before
shipping a set of human-readable artifacts.
---
## Table of Contents
1. [What It Is](#what-it-is)
2. [High-Level Architecture](#high-level-architecture)
3. [The Full Workflow](#the-full-workflow)
4. [Project Lifecycle](#project-lifecycle)
5. [The Agent Team](#the-agent-team)
6. [The LLM Layer](#the-llm-layer)
7. [The Orchestrator](#the-orchestrator)
8. [Data Model (Pydantic Schemas)](#data-model-pydantic-schemas)
9. [Prompts](#prompts)
10. [Generated Artifacts](#generated-artifacts)
11. [REST API](#rest-api)
12. [Persistence & Run Tracking](#persistence--run-tracking)
13. [Events & Live Streaming](#events--live-streaming)
14. [Project Structure](#project-structure)
15. [Installation & Setup](#installation--setup)
16. [Configuration](#configuration)
17. [Running the System](#running-the-system)
18. [Running Tests](#running-tests)
19. [Benchmarking](#benchmarking)
20. [Extending the System](#extending-the-system)
21. [Security Notes](#security-notes)
---
## What It Is
`B2D` (Backend-to-Deployment / Business-to-DevOps) is a Python package that
implements an **agentic AI core**. Instead of a single monolithic LLM call, it
uses a **team of specialized agents**, each with a single responsibility, wired
together by an **orchestrator** that enforces an order, retries failures
boundedly, and runs a **single, evidence-based consistency review** before
delivering the blueprint.
Key properties:
- **Human-in-the-loop discovery** — the system asks targeted questions until it
genuinely understands the project before generating anything.
- **Structured, validated outputs** — every agent must return JSON matching a
strict Pydantic schema; malformed responses are automatically repaired with a
bounded number of retries.
- **Dependency-ordered engineering** — artifacts are produced in a fixed order:
`requirements → architecture → database → api → devops`. Each agent only sees
the context plus the artifacts it depends on.
- **Bounded, convergent review** — the Reviewer runs at most **once**. If it
finds blocking inconsistencies, only the flagged artifacts are **revised** (a
targeted edit of the existing artifact, max one revision each) and the
workflow completes — it never re-reviews, so it can never loop forever.
- **Provider-agnostic LLM layer** — the entire system depends on a small
`LLMProvider` interface. It ships with a real **Cursor Cloud Agents** provider
and a **Fake provider** for tests/offline demos.
- **Observable** — every agent run is recorded to JSONL (with per-call
telemetry: call id, model, TTFT, duration, tokens) and live progress is
streamed over Server-Sent Events (SSE).
---
## High-Level Architecture
```
┌──────────────────────────────────────────┐
│ Frontend / Client │
│ (CLI, scripted demo, or your own UI) │
└──────────────────┬───────────────────────┘
│ REST + SSE
┌────────▼────────┐
│ FastAPI layer │ agentic_core/api/
│ (thin adapter) │
└────────┬────────┘
│
┌────────▼───────────────┐
│ Orchestrator │ agentic_core/orchestrator/
│ discovery · order · │
│ review · regeneration │
└────────┬───────────────┘
│ emits events
┌────────▼────────┐ ┌──────────────────┐
│ EventBus │──────▶│ SSE streams │
│ + per-project │ │ to subscribers │
│ buffer (500) │ └──────────────────┘
└─────────────────┘
│
┌───────────────────────┼────────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌──────────────────┐ ┌───────────────────┐
│ Agent team │ │ LLMService │ │ Persistence │
│ discovery │───▶│ structured JSON │ │ ProjectStore │
│ requirements │ │ + repair retry │ │ ExecutionTracker │
│ architecture │ └────────┬─────────┘ │ ArtifactStore │
│ database │ │ └───────────────────┘
│ api │ ┌───────▼────────┐
│ devops │ │ LLMProvider │
│ reviewer │ │ (interface) │
└─────────────────┘ ├────────────────┤
│ CursorCloud │ real API
│ Fake │ tests/offline
└────────────────┘
```
**Separation of concerns.** The frontend only talks to the FastAPI adapter. The
adapter talks to the orchestrator. The orchestrator talks to agents. Agents only
talk to `LLMService`. The `LLMService` is the only component that talks to an
LLM provider. Agents never contain workflow logic, never touch a provider SDK,
and never know about the UI.
---
## The Full Workflow
The entire journey of a project can be broken into five phases.
### Phase 1 — Discovery (conversational requirement elicitation)
The **Discovery Agent** is the human-facing intelligence layer.
1. You provide a vague business idea (e.g. *"I want to build a platform where
users can book football fields"*).
2. The agent analyzes the idea, the current understanding, and the full
conversation transcript.
3. It returns a structured `DiscoveryOutput`:
- `status`: `needs_clarification` or `ready`
- `confidence`: 0.0–1.0 (must be high, ≥ 0.9, to reach `ready`)
- `summary`: a 2–3 sentence recap of its understanding
- `known_information`: its best understanding of every canonical field
- `missing_information`: which fields are still missing and how important
(`critical` / `optional` / `not_applicable`)
- `questions`: 1–4 focused questions (at most 4), each with multiple-choice
`options`; asks none if the answers so far are enough (never re-asks what
it already knows)
4. Your answers are appended to the transcript and the loop repeats until the
agent decides it has enough critical information. All answers for a turn are
sent to the agent in a single run so discovery normally converges in 1–2
turns (the system prompt targets at most two question rounds and records
remaining optional unknowns as assumptions instead of asking again).
Rules the agent follows (from its system prompt): ask only high-information
questions (2–4 per turn), prioritise architectural forks before low-impact
details, never re-ask what is already known, stop aggressively once critical
information is known or explicitly constrained, let the latest answer win on
contradiction, record unverifiable things as `assumptions` (never invent
requirements), and classify irrelevant fields as `not_applicable` instead of
asking about them.
When `status == "ready"`, the project transitions to
`ready_for_confirmation`.
### Phase 2 — Confirmation gate
The system prints "YOUR PROJECT UNDERSTANDING" (problem, target users, roles,
goals, features, constraints, integrations, tech preferences) and asks you to
confirm. `Orchestrator.confirm()` is a strict state gate — it raises
`OrchestrationError` if the project is not in `ready_for_confirmation`. On
confirmation the status becomes `confirmed`, which is the only status from
which generation is allowed.
### Phase 3 — Autonomous engineering (dependency-ordered)
Once confirmed, the orchestrator runs the agents in dependency order:
```
requirements → architecture → database → api → devops
```
The orchestrator computes *dependency levels* from the graph
(`DEPENDENCIES` in `orchestrator.py`) and runs every agent within a level
concurrently (`asyncio.gather`):
```
level 1: requirements
level 2: architecture
level 3: database
level 4: api, devops (concurrent)
```
`DEPENDENCIES` must mirror what each agent actually reads. When database, api
and devops shared a level, api and devops built their prompts before the
database agent had committed anything and received a literal `{}` where the
schema should have been — while their own prompts forbid referencing entities
that do not exist. That manufactured the exact contradiction the reviewer's
database/API check exists to catch, and every blocking finding costs a
regeneration round.
**Every inter-agent handoff is a compact deterministic digest.** As soon as an
artifact is generated it is condensed by `agents/digest.py` into a small JSON
digest that keeps only the *contracts* downstream agents must match — entity and
field names, component technologies, endpoint paths, auth model, deployment
decisions — while dropping derived artifacts (SQL, Mermaid, OpenAPI, YAML) and
prose. Downstream agents and the reviewer consume the digests instead of the
full serialized artifacts. This costs **zero LLM calls**; when
`SUMMARIZE_WITH_LLM=true` the orchestrator instead spends one LLM call per
artifact (fastest model) on natural-language summaries.
Each agent receives only the inputs it needs:
| Agent | Inputs |
|----------------|---------------------------------------------------------------|
| requirements | full project context (condensed) |
| architecture | scoped context + requirements digest |
| database | scoped context + requirements + architecture digests |
| api | scoped context + requirements + architecture + database digests |
| devops | scoped context + requirements + architecture + database digests |
The **scoped context** drops the fields the requirements digest already restates
(business idea, target users, business goals, discovery assumptions). The same
block is embedded in every engineering prompt, so carrying the full snapshot
costs its size four times over.
DevOps deliberately does not read the API design: an endpoint list does not
change a Dockerfile, a compose file or a CI workflow, and withholding it lets
DevOps run alongside the API agent instead of queueing behind it.
An agent that fails due to a provider/transport error (network, poll timeout,
auth) is run once more (`_run_with_retry`). A structured-output failure already
consumed its internal repair retries, so it is **not** re-run — a full second
run would only double the token cost. If an agent still fails, the workflow
stops and the project is marked `needs_attention`.
### Phase 4 — Review & bounded regeneration
After the five engineering agents succeed, the **Review Agent** cross-validates
every artifact for internal consistency (see
[The Agent Team](#the-agent-team) for the mandatory checks). The reviewer
receives only compact artifact digests — one copy of each — so its input stays
small and stable (no discovery transcript, no previous review output).
- If `status == "approved"`, the workflow completes as `approved` and artifacts
are rendered.
- If `status == "needs_revision"`, the reviewer returns `issues[]` with
`severity` of `blocking` / `warning` / `suggestion`. **Only blocking issues
trigger regeneration**, and each must cite the exact source and conflicting
decision so the fix can be targeted.
- Blocking targets are expanded through the `DEPENDENTS` map so anything built
**on top of** a regenerated artifact is also regenerated:
```
requirements → requirements, architecture, database, api, devops
architecture → architecture, database, api, devops
database → database, api, devops
api → api
devops → devops
```
- Regeneration is a **revision**, not a redo: each affected agent receives its
existing artifact plus the exact reviewer issues and is told to preserve every
valid decision.
- Bounds (config): the reviewer runs at most `max_review_rounds` (default `1`)
and each artifact is revised at most `max_artifact_revisions` (default `1`).
After the single regeneration pass the workflow completes with `revised`
(all flagged artifacts regenerated) or `needs_attention` (a revision failed,
hit its cap, or produced no change) — it **never re-reviews**.
- A failed regeneration never overwrites the previous successful artifact, and
transient provider failures get at most `max_llm_retries` (default `1`).
### Phase 5 — Artifacts
`render_all()` turns the structured agent outputs into human/ops-readable
files saved under `data/artifacts/<project_id>/`:
| File | Source |
|----------------------|-------------------------------------|
| `overview.md` | project context |
| `requirements.md` | requirements agent |
| `architecture.md` | architecture agent |
| `architecture.mmd` | Mermaid flow diagram |
| `database.md` | database agent (entities, ERD text) |
| `database.sql` | executable SQL schema |
| `erd.mmd` | Mermaid ER diagram |
| `api.md` | API design (endpoints, auth, …) |
| `openapi.yaml` | OpenAPI 3.0 spec |
| `devops.md` | deployment strategy, health, CI/CD |
| `Dockerfile` | complete backend Dockerfile |
| `docker-compose.yml` | local stack (backend + DB + services) |
| `github-actions.yml` | CI/CD workflow |
---
## Project Lifecycle
A project's `status` field moves through a strict state machine:
```
discovery ─▶ ready_for_confirmation ─▶ confirmed ─▶ generating ─▶ approved
▲ │ │
│ │ ┌──────┴──────┐
│ ├──▶ revised ◀──┤ review │
│ │ │ (1 round) │
└────── (stay in discovery until ready) │ └──────┬──────┘
│ needs_attention
└────▶ needs_attention ◀────┘
(failure or revision cap)
```
| Status | Meaning |
|--------------------------|----------------------------------------------------------------|
| `discovery` | Agent still asking clarifying questions |
| `ready_for_confirmation` | Discovery complete; waiting for the user to confirm |
| `confirmed` | User confirmed; generation allowed |
| `generating` | Engineering agents are running |
| `approved` | Blueprint passed the review |
| `revised` | Blocking issues were fixed by one targeted regeneration pass |
| `needs_attention` | An agent failed repeatedly, a revision failed, or the revision cap was hit |
Each project is stored as a row in a SQLite database (`data/b2d.db`). Projects
saved by older versions as `data/projects/*.json` files are imported
automatically on startup.
---
## The Agent Team
All agents extend `BaseAgent` (`agentic_core/agents/base.py`), which provides:
- a tracked `run(context, revision=None)` lifecycle that measures `duration_ms`
and records per-call LLM telemetry (call id, model, TTFT, tokens),
- structured-output execution against a per-agent `output_schema`,
- per-run `_stats["repair_count"]` (number of JSON repair retries),
- optional `ExecutionTracker` recording of every run,
- targeted-revision support: when the orchestrator passes a
`RevisionInstruction` (existing artifact + reviewer issues), the agent revises
only the flagged decisions instead of regenerating from scratch.
### Discovery Agent (`agents/discovery.py`)
The only human-facing agent. Runs an adaptive conversation, updates the
project context via `apply_known_information`, and decides when to stop asking.
Helper functions in the module:
- `known_info_snapshot(context)` — canonical current understanding.
- `apply_known_information(context, known)` — idempotently overwrites context
fields (list vs. string handling, `None` skip).
- `discovery_agent_message(output)` — the human-readable agent turn appended to
the transcript.
- `format_transcript(context)` — last 10 conversation turns, formatted.
Every question carries multiple-choice `options` (3-6 concrete choices). The
user can answer by picking option numbers (e.g. `1,3`) or by typing their own
text — the CLI's `parse_user_answer` handles both. To keep discovery fast, all
answers in a turn are sent to the agent in **one** run, and the agent only
reports `known_information` fields that changed or were newly inferred.
### Requirements Engineer (`agents/requirements.py`)
Produces `functional_requirements`, `non_functional_requirements`,
`user_stories`, `acceptance_criteria`, `constraints`, and `assumptions`. Every
functional requirement must be traceable to the context; never invents
constraints.
### Architecture Agent (`agents/architecture.py`)
Designs `system_components` (name/type/description/technology), communication,
authentication, security, scalability, `technology_stack`, deployment
architecture, and a Mermaid `flowchart`. Must honor tech preferences and pick
exactly one primary database technology.
### Database Design Agent (`agents/database.py`)
Designs entities with typed fields (PK/FK/nullable/unique/indexed), relations,
indexes, and constraints. The executable `sql_schema` and Mermaid `erDiagram`
are **derived locally** from the entity/field metadata (see `render.py`), so the
agent never spends output tokens on them. The database technology **must** match
the architecture's database component.
### API Design Agent (`agents/api.py`)
Designs REST `endpoints` (method, path, summary, auth, request/response
schemas, pagination, filters), authentication, authorization (using the context
user roles), error handling, pagination/filtering strategy. The full OpenAPI 3.0
document is **derived locally** from the endpoints (see `render.py`), so the
agent never spends output tokens on it. No endpoint may reference a nonexistent
entity.
### DevOps Engineer Agent (`agents/devops.py`)
The star of a DevOps hackathon. Produces a `Dockerfile` (correct base image,
non-root user, healthcheck, minimal layers), `docker-compose.yml`, a CI/CD
pipeline description, a complete GitHub Actions workflow, env vars (placeholders
only — never real secrets), deployment strategy, health checks, logging,
monitoring, and secrets management. All technologies must match the
architecture. Artifacts are **for review only** and never executed.
### Review Agent (`agents/reviewer.py`)
Cross-validates everything from compact artifact summaries. Mandatory consistency
checks:
1. Requirements ↔ Architecture
2. Architecture ↔ Database (technology must match — Postgres vs Mongo is a
blocking conflict)
3. Architecture ↔ API
4. Database ↔ API (endpoints must map to real entities/fields)
5. Architecture ↔ DevOps (Dockerfile, compose, CI/CD must use the same stack)
6. Security consistency (coherent auth/authorization across all artifacts)
7. Technology consistency (no artifact may introduce a contradictory tech)
Every issue is structured: `artifact`, `severity` (`blocking` / `warning` /
`suggestion`), `problem`, `expected`, `actual`, `fix`, plus the evidence
(`source_artifact`, `source_decision`, `conflicting_artifact`,
`conflicting_decision`). **Only `blocking` issues trigger regeneration**;
warnings and suggestions never do, and the reviewer must cite concrete evidence
rather than "this could be improved". Responses are kept to 200–500 tokens. The
orchestrator derives the minimal `artifacts_to_regenerate` set from the blocking
issues and expands downstream dependents itself.
### Artifact digests (`agents/digest.py`) and Summarizer (`agents/summarizer.py`)
The **default** handoff mechanism is deterministic: `agents/digest.py` condenses
each engineering artifact into a compact JSON digest that preserves the
cross-artifact contracts (entity/field names, component technologies, endpoint
paths, auth model, deployment decisions) and drops prose and derived artifacts
(SQL, Mermaid, OpenAPI, workflow YAML). This is pure Python — **zero LLM calls**
per workflow and no latency added.
The **Artifact Summarizer** (`agents/summarizer.py`) is the optional LLM-based
version, enabled with `SUMMARIZE_WITH_LLM=true`. When enabled, the orchestrator
spends one call (fastest model, `LLM_FAST_MODEL`) summarizing each artifact
before it is handed downstream. It is best-effort: failures fall back to the
deterministic digests and never block the workflow.
---
## The LLM Layer
### Provider abstraction (`llm/base.py`)
```python
class LLMProvider(ABC):
async def generate(self, system_prompt: str, user_prompt: str, stats: dict | None = None) -> str: ...
```
This is the *only* interface the whole system depends on. Swap in any provider
without touching agent or orchestrator code. Two implementations ship:
- **`FakeLLMProvider`** — in-memory, scripted responses or a callable handler.
Used by the entire test suite and ideal for offline demos.
- **`CursorCloudProvider`** (`llm/cursor_provider.py`) — talks to Cursor's
Cloud Agents API (`https://api.cursor.com/v1`). Creates a short-lived
*no-repo* agent with the combined prompt, polls its run to completion
(every `llm_poll_interval_s` seconds, up to `llm_poll_timeout_s`), returns
the final assistant text, then archives the agent. The default configuration
routes Google's `gemini-3.7-flash` through Cursor. No secrets are logged.
### `LLMService` (`llm/service.py`)
The single entry point agents call: `await llm_service.generate(system, user, schema, stats)`.
Responsibilities:
1. **Schema embedding** — appends the target Pydantic model's JSON Schema to
the user prompt and demands "only a single valid JSON object". Pydantic
`title` boilerplate is stripped and definitions left unreachable by
`llm_exclude_fields` are pruned, but `$defs` itself is **kept**: removing it
left every `$ref` dangling, so the model was asked to conform "exactly" to a
schema that never defined `DBEntity`, `SystemComponent`, `APIEndpoint` or the
`severity`/`importance` enums. The agents whose schemas contain nested models
carried an 11-19% JSON repair rate against ~0% for those without.
2. **Parsing** — `extract_json_object` tolerates prose, fenced code blocks
(` ```json `), and stray braces around the JSON. A first object that never
closes is reported as a cut-off response rather than salvaged: recovering a
balanced *inner* region from a truncated reply returned a fragment that then
validated into an empty artifact and was committed as a successful run.
3. **Validation** — parses with the Pydantic schema; a `ValidationError` or
`StructuredOutputError` triggers a repair.
4. **Bounded repair** — re-invokes the provider with the previous bad response
and the exact validation error, asking for a clean JSON object only.
Retries are capped at `structured_output_max_retries` (default `1`), then
the agent fails and the orchestrator marks the run failed.
Custom exceptions: `LLMProviderError` (network/auth), `LLMGenerationError`
(unusable output), `StructuredOutputError` (unparseable/invalid JSON).
---
## The Orchestrator
`agentic_core/orchestrator/orchestrator.py` owns the workflow and is the only
component that knows about it.
Public API:
- `Orchestrator.discovery_turn(context, user_message)` — one discovery step;
raises `DiscoveryError` if the discovery agent fails.
- `Orchestrator.confirm(context)` — the confirmation gate.
- `Orchestrator.generate(context)` — runs the full engineering pipeline plus a
single bounded review/regeneration pass; returns a dict of `AgentResult`s
keyed by name, plus `call_counts` and `revisions` (per-agent LLM invocation
counts and revision counters).
Internals:
- `ENGINEERING_ORDER` — the fixed agent order.
- `DEPENDENCIES` — upstream dependencies per artifact, used by
`_execution_levels` to group agents into concurrency levels.
- `_run_workflow_levels(context, names, ...)` — runs a set of artifacts in
dependency order, executing each level's agents concurrently and condensing
every successful artifact into a compact digest (or optional LLM summary when
`SUMMARIZE_WITH_LLM=true`) before the next level runs.
- `_execution_levels(artifacts)` — topological levels: agents in the same level
are unrelated and run in parallel. Deterministic (input order), so telemetry
and tests can rely on stable level grouping.
- `DEPENDENTS` — the downstream-dependent expansion map used by
`_regeneration_targets`.
- `_run_with_retry(context, name, revision, ...)` — re-runs an agent at most
`max_llm_retries` times, but only for provider/transport failures
(structured-output failures already exhausted their internal repairs and are
not re-run — cost saving). Regeneration passes a `RevisionInstruction` so the
run is a targeted edit, never a from-scratch redo.
- `_run_reviewer(...)` — the single review round (one run, one bounded retry).
- `_blocking_targets(review)` — only blocking issues become regeneration targets.
- `_artifact_hash(...)` — deterministic artifact fingerprint; if a revision
produces no meaningful change the issue is reported instead of retried.
### Event & tracking support (`orchestrator/events.py`, `orchestrator/tracker.py`)
- **`EventBus`** — an in-process pub/sub bus. Per-project ring buffer (500
events) so late-connecting SSE consumers still see history; `stream()`
yields buffered then live events with 15s heartbeats. Events carry an
`invocation` number so consumers can tell a first run from a regeneration.
- **`ExecutionTracker`** — appends a `RunRecord` (project, agent, status,
input snapshot, output, error, timestamps, duration, retry count, cost
metrics, and per-call LLM telemetry: `call_id`, `model`, `ttft_s`,
`input_tokens`/`output_tokens`) per run to `data/runs/<project_id>.jsonl`.
No secrets are ever written.
---
## Data Model (Pydantic Schemas)
All schemas live in `agentic_core/schemas/`. They serve double duty: the
in-memory/on-disk project state and the JSON schemas enforced on every LLM
response.
### `ProjectContext` (`schemas/context.py`) — the central state
The single object threaded through every phase. Holds:
- **Identity**: `project_id`, `business_idea`.
- **Discovery fields** (all filled by the Discovery Agent):
`problem`, `target_users`, `user_roles`, `business_goals`, `core_features`,
`scope`, `constraints`, `assumptions`, `integrations`,
`security_requirements`, `performance_requirements`,
`deployment_requirements`, `technology_preferences`,
`auth_requirement`, `authorization_requirement`, `payment_requirement`,
`notification_requirement`.
- **Artifacts** (filled by each engineering agent):
`requirements`, `architecture`, `database`, `api`, `devops`, plus `review`.
- **Lifecycle**: `status`, `transcript` (list of `DiscoveryTurn`s), `updated_at`.
Helpers: `add_turn(role, message)` and `touch()` keep `updated_at` current.
### Per-agent output schemas
| Schema | Key fields |
|-------------------------------|-------------------------------------------------------------------------|
| `DiscoveryOutput` | `status`, `confidence`, `summary`, `known_information`, `missing_information`, `questions` |
| `RequirementsOutput` | `functional_requirements`, `non_functional_requirements`, `user_stories`, `acceptance_criteria`, `constraints`, `assumptions` |
| `ArchitectureOutput` | `system_components[]`, `communication`, `authentication`, `security`, `scalability`, `technology_stack`, `deployment_architecture`, `mermaid_diagram` |
| `DatabaseOutput` | `database_technology`, `entities[]`, `relationships`, `indexes`, `constraints` — `sql_schema`/`erd_mermaid` are excluded from the LLM schema and derived locally |
| `APIOutput` | `endpoints[]`, `authentication`, `authorization`, `error_handling`, `pagination`, `filtering` — `openapi_spec` is excluded from the LLM schema and derived locally |
| `DevopsOutput` | `dockerfile`, `docker_compose`, `ci_cd_pipeline`, `github_actions`, `environment_variables`, `deployment_strategy`, `health_checks`, `logging`, `monitoring`, `secrets_management` |
| `ReviewOutput` | `status` (`approved`/`needs_revision`), `score`, `issues[]`, `artifacts_to_regenerate` |
### Output budgets (`schemas/limits.py`)
Model output is the larger half of the token bill and, because generation is
sequential, nearly all of the latency. Ceilings written in prose inside a system
prompt do not bind — measured against a real run, prompts asking for "max 8-12
endpoints" got 71, "max 6-8 entities" got 22, and "4-6 functional requirements"
got 27.
The ceilings are therefore declared on the fields themselves. `max_length`
publishes `maxItems` into the JSON Schema the model is shown, and
`CappedListModel` trims anything that still comes back over budget rather than
rejecting it — an overrun is cosmetic, and failing it would cost a full repair
round-trip.
| Schema | Budget |
|----------------------|------------------------------------------------------------|
| `RequirementsOutput` | 8 FRs, 5 NFRs, 6 user stories, 8 acceptance criteria |
| `ArchitectureOutput` | 6 components, 4 communication, 4 security, 3 scalability |
| `DatabaseOutput` | 8 entities, 10 fields per entity, 8 relationships |
| `APIOutput` | 12 endpoints, 5 filters per endpoint, 4 error conventions |
| `DevopsOutput` | 3 health checks, 2 logging, 2 monitoring; `maxLength` hints on the config files |
| `DiscoveryOutput` | 3 questions, 4 options each, 8 missing-info entries |
| `ReviewOutput` | 8 issues |
Each output schema also **requires** its primary field (`entities`, `endpoints`,
`system_components`, `dockerfile`), so a fragment recovered from a truncated
response can never validate into an empty artifact.
Supporting models: `DiscoveryQuestion`, `MissingInfo`, `DiscoveryTurn`,
`SystemComponent` (typed: frontend/backend/service/database/external/
infrastructure), `DBEntity`/`DBField`, `APIEndpoint` (typed HTTP methods),
`ReviewIssue` (severity blocking/warning/suggestion + evidence fields).
---
## Prompts
`agentic_core/prompts/` holds a registry (`PROMPTS`) of `Prompt(name, system,
user_template)` per agent. User templates use `{__KEY__}` placeholders,
substituted at runtime by `build_user_prompt(name, **values)`.
The `build_user_prompt` machinery replaces `{__KEY__}` (uppercased) with the
provided values, e.g. the Requirements agent fills `{__PROJECT_CONTEXT__}`.
The `LLMService` then appends the JSON schema requirements.
Each system prompt follows the same structure for predictable behavior:
**Role · Objective · Input · Output · Consistency · Failure behaviour**.
---
## Generated Artifacts
`agentic_core/artifacts/render.py` converts validated structured outputs into
text. Notable functions:
- `render_overview(context)` → `overview.md`
- `render_requirements(...)` → `requirements.md`
- `render_architecture(...)` + `render_architecture_mmd(...)` → `architecture.md`, `architecture.mmd`
- `render_database_markdown(...)` + `render_database_sql(...)` + `render_erd(...)` → `database.md`, `database.sql`, `erd.mmd`
- `render_api_markdown(...)` + `render_openapi(...)` (YAML dump) → `api.md`, `openapi.yaml`
- `render_devops_markdown(...)` → `devops.md`
- `render_all(context)` → the complete `dict[filename, content]` of everything above.
`ArtifactStore` (`artifacts/store.py`) persists these on disk under
`data/artifacts/<project_id>/` with path-traversal protection (`_safe_name`).
---
## REST API
`agentic_core/api/app.py` is a thin FastAPI adapter (port **8000**). The
frontend never knows agent implementation details. CORS is open for all
origins (dev setting).
| Method | Endpoint | Description |
|--------|----------------------------------------------------|---------------------------------------------------------|
| POST | `/api/projects` | Create project + run first discovery turn |
| POST | `/api/projects/{id}/discovery/start` | Start/restart discovery with a message |
| POST | `/api/projects/{id}/discovery/message` | Continue discovery with a user answer |
| GET | `/api/projects/{id}/discovery/state` | Current discovery state |
| POST | `/api/projects/{id}/discovery/confirm` | Confirm understanding (409 unless ready_for_confirmation) |
| POST | `/api/projects/{id}/generate` | Kick off engineering in the background (409 if already running) |
| GET | `/api/projects/{id}/generation/status` | **SSE** stream of agent events |
| GET | `/api/projects/{id}` | Full project state |
| GET | `/api/projects/{id}/artifacts` | List rendered artifact filenames |
| GET | `/api/projects/{id}/artifacts/{artifact_type}` | Raw artifact content (plain text) |
Shared services are assembled once in `api/deps.py` (`AppServices`): settings,
event bus, tracker, Cursor provider, LLM service, orchestrator, project store,
artifact store, and a `generation_tasks` registry. `_run_generation` runs the
orchestrator in an `asyncio` task, saves the project, renders all artifacts into
the store, and emits a final `artifacts_ready` event.
### SSE event stream
The `/generation/status` endpoint streams `AgentEvent` JSON payloads with
event types: `workflow_started`, `agent_started`, `agent_completed`,
`agent_retrying`, `agent_failed`, `review_started`, `review_completed`,
`review_failed`, `workflow_completed`, `workflow_failed`, `artifacts_ready`
(plus 15s `heartbeat` keep-alives). The stream terminates with an SSE `done`
event after `workflow_completed` / `workflow_failed`.
---
## Persistence & Run Tracking
| Store | Location | Format | Purpose |
|---------------------|-------------------------------|--------|--------------------------------------------|
| `ProjectStore` | `data/b2d.db` | SQLite | Full project context + artifacts (JSON blobs) |
| `ExecutionTracker` | `data/runs/<id>.jsonl` | JSONL | Append-only per-agent run history |
| `ArtifactStore` | `data/artifacts/<id>/` | files | Rendered markdown/SQL/YAML/Docker artifacts |
---
## Events & Live Streaming
`EventBus` (in `orchestrator/events.py`) is the progress backbone:
- Synchronous `subscribe(listener)` / `unsubscribe(listener)` for CLI/script
progress printing.
- Per-project ring buffer (500 events) replayed to late-connecting consumers.
- `stream(project_id)` async generator used by the SSE endpoint, emitting a
`heartbeat` every 15s of inactivity.
The CLI (`agentic_core/cli.py`) maps event types to symbols for a nice
terminal experience: `▶` workflow start, `→` agent start, `✓` completed,
`↻` retrying, `✗` failed, `◈` review, `⚠` review failed, `✔` completed.
---
## Project Structure
```
B2D/
├── agentic_core/ # The Python package (the "core")
│ ├── __init__.py # package metadata (v0.1.0)
│ ├── config.py # env-based Settings (pydantic-settings)
│ ├── cli.py # interactive CLI demo
│ ├── project_store.py # SQLite persistence for projects
│ ├── agents/ # the agent team
│ │ ├── base.py # BaseAgent + AgentResult + payload helper
│ │ ├── discovery.py
│ │ ├── requirements.py
│ │ ├── architecture.py
│ │ ├── database.py
│ │ ├── api.py
│ │ ├── devops.py
│ │ ├── reviewer.py
│ │ ├── digest.py # deterministic compact handoffs (default)
│ │ ├── summarizer.py # optional LLM handoffs (SUMMARIZE_WITH_LLM)
│ │ └── __init__.py # build_agents() factory
│ ├── llm/ # provider abstraction + service
│ │ ├── base.py # LLMProvider, FakeLLMProvider, errors
│ │ ├── cursor_provider.py # Cursor Cloud Agents provider
│ │ ├── service.py # LLMService (schema + repair)
│ │ └── __init__.py
│ ├── orchestrator/ # workflow engine
│ │ ├── orchestrator.py # Orchestrator, ENGINEERING_ORDER, DEPENDENTS
│ │ ├── events.py # AgentEvent, EventBus
│ │ ├── tracker.py # RunRecord, ExecutionTracker
│ │ └── __init__.py
│ ├── schemas/ # Pydantic data models
│ │ ├── context.py # ProjectContext, DiscoveryTurn, ProjectStatus
│ │ ├── discovery.py
│ │ ├── requirements.py
│ │ ├── architecture.py
│ │ ├── database.py
│ │ ├── api.py
│ │ ├── devops.py
│ │ ├── review.py
│ │ └── __init__.py
│ ├── prompts/ # system prompts + user templates
│ │ ├── __init__.py # PROMPTS registry, build_user_prompt()
│ │ └── discovery.py, requirements.py, architecture.py,
│ │ database.py, api.py, devops.py, reviewer.py
│ ├── artifacts/ # rendering + storage of final outputs
│ │ ├── render.py # render_all() and friends
│ │ ├── store.py # ArtifactStore
│ │ └── __init__.py
│ └── api/ # FastAPI adapter
│ ├── app.py # endpoints + SSE
│ ├── deps.py # AppServices singleton
│ └── __init__.py
├── scripts/
│ ├── demo_football.py # scripted end-to-end live demo
│ └── run_test.py # headless E2E test + per-agent cost table
├── tests/ # pytest suite (hermetic, fake LLM)
│ ├── conftest.py # fixtures (settings, provider, orchestrator…)
│ ├── helpers.py # valid sample outputs + build_handler()
│ ├── test_agents.py # structured-output / failure handling
│ ├── test_cli.py # CLI discovery option-selection helper
│ ├── test_digest.py # digest compactness + contract preservation
│ ├── test_discovery.py # discovery conversation loop
│ ├── test_e2e.py # full workflow end-to-end
│ ├── test_llm_service.py # JSON extraction, repairs, schema embedding
│ ├── test_openrouter_provider.py
│ ├── test_optimization.py # optimization regression locks
│ ├── test_orchestrator.py # order, retries, review loop, limits
│ ├── test_project_store.py # SQLite persistence
│ └── test_render.py # deterministic artifact rendering
├── data/ # runtime data (gitignored in a real repo)
│ ├── b2d.db # SQLite database of projects
│ ├── runs/ # <project_id>.jsonl
│ └── artifacts/ # <project_id>/ rendered files
├── .env.example # documented environment template
├── .env # local secrets (NOT committed)
├── requirements.txt
├── pytest.ini # asyncio_mode = auto, testpaths = tests
└── README.md
```
---
## Installation & Setup
Requires **Python 3.11+** (the compiled artifacts in the tree are `cpython-311`).
```bash
# 1. Create and activate a virtual environment
python -m venv .venv
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# macOS / Linux:
source .venv/bin/activate
# 2. Install dependencies
pip install -r requirements.txt
# 3. Configure credentials
copy .env.example .env # Windows
cp .env.example .env # macOS / Linux
# ... then paste your Cursor API key into CURSOR_API_KEY
```
> Get a Cursor API key at https://cursor.com/dashboard/api
---
## Configuration
All settings are read from environment variables / `.env` (see
`agentic_core/config.py`). Secrets are only ever read from the environment and
are never logged.
| Variable | Default | Meaning |
|------------------------------|---------------------------------|----------------------------------------------|
| `CURSOR_API_KEY` | *(empty)* | Cursor Cloud Agents API key |
| `KIMI_API_KEY` | *(empty)* | Kimi / Moonshot API key (OpenAI-compatible) |
| `OPENROUTER_API_KEY` | *(empty)* | OpenRouter API key (OpenAI-compatible) |
| `LLM_API_KEY` | *(empty)* | Shared fallback key for any provider |
| `LLM_PROVIDER` | `cursor` | Provider: `cursor` / `kimi` / `openrouter` / `groq` / `gemini` |
| `LLM_MODEL` | `gemini-3.7-flash` | Model id routed through Cursor |
| `LLM_FAST_MODEL` | `gemini-3.7-flash` | Optional summarizer model + Cursor default |
| `CURSOR_FAST_MODE` | `true` | Run composer models in fast mode (Cloud API) |
| `SUMMARIZE_WITH_LLM` | `false` | LLM-summarize artifacts (default: Python digests) |
| `LLM_BASE_URL` | `https://api.cursor.com/v1` | Provider base URL (Cursor) |
| `KIMI_BASE_URL` | `https://api.moonshot.cn/v1` | Provider base URL (Kimi) |
| `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` | Provider base URL (OpenRouter) |
| `LLM_REQUEST_TIMEOUT_S` | `120` | HTTP request timeout |
| `LLM_MAX_TOKENS` | `8192` | Max output tokens. Must clear the largest artifact an agent emits, or the response is cut off mid-object |
| `LLM_POLL_INTERVAL_S` | `1.0` | Cursor run poll interval |
| `LLM_POLL_TIMEOUT_S` | `300` | Max time waiting for a run |
| `STRUCTURED_OUTPUT_MAX_RETRIES` | `1` | JSON repair retries per attempt |
| `MAX_REVIEW_ROUNDS` | `1` | Reviewer runs at most once per workflow |
| `MAX_ARTIFACT_REVISIONS` | `1` | Max regenerations per artifact per workflow |
| `MAX_LLM_RETRIES` | `1` | Bounded retries for transient provider errors |
`get_settings()` (cached) also creates `data`, `data/runs`, and
`data/artifacts` on first call and raises `RuntimeError` if no API key is set.
The effective key/provider are chosen by `LLM_PROVIDER`, falling back to the
shared `LLM_API_KEY`.
---
## Running the System
### 1. Interactive CLI demo
```bash
python -m agentic_core.cli
```
Walks the exact demo flow: idea → discovery Q&A → summary → confirm →
autonomous engineering with live progress → rendered artifact list.
### 2. Scripted end-to-end demo (real Cursor API)
```bash
python -m scripts.demo_football
```
Runs a pre-scripted conversation for a **football field booking platform** end
to end against the live provider, prints live progress, and writes artifacts
under `data/artifacts/<project_id>/`. Exits `0` on approval, `1` otherwise.
### 3. Headless end-to-end test (real Cursor API)
```bash
python -m scripts.run_test "YOUR BUSINESS IDEA"
```
Auto-answers discovery questions (no stdin needed), runs the full engineering
workflow against the live provider, renders artifacts, then prints a per-agent
table (duration + TTFT + estimated input/output tokens + embedded schema size +
repairs + invocation count) plus workflow totals: discovery rounds, real provider
calls (runs + internal repairs), engineering and total wall-clock, slowest agent,
largest prompt, largest output, reviewer prompt size, and a token-accounting
section that clearly separates estimated application-visible tokens from
provider-reported usage. Useful for measuring speed/token changes.
> **Token accounting:** the Cursor Cloud Agents API does not expose per-run
> usage, so the script reports only estimated application-visible tokens
> (chars/4). The Cursor dashboard counts framework, tooling and reasoning
> tokens the provider call cannot observe, so the two are not comparable 1:1.
### 4. REST API server
```bash
uvicorn agentic_core.api.app:app --host 0.0.0.0 --port 8000
```
Then drive it from any HTTP client:
```bash
# Create project + first discovery turn
curl -X POST http://localhost:8000/api/projects \
-H "Content-Type: application/json" \
-d '{"business_idea": "I want to build a platform where users can book football fields."}'
# Answer a discovery question
curl -X POST http://localhost:8000/api/projects/<PROJECT_ID>/discovery/message \
-H "Content-Type: application/json" \
-d '{"message": "Players, field owners and admins."}'
# Confirm when status == ready_for_confirmation
curl -X POST http://localhost:8000/api/projects/<PROJECT_ID>/discovery/confirm
# Start generation, then stream progress
curl -X POST http://localhost:8000/api/projects/<PROJECT_ID>/generate
curl -N http://localhost:8000/api/projects/<PROJECT_ID>/generation/status
# Fetch rendered artifacts
curl http://localhost:8000/api/projects/<PROJECT_ID>/artifacts
curl http://localhost:8000/api/projects/<PROJECT_ID>/artifacts/overview.md
```
Interactive API docs are available at `http://localhost:8000/docs` (FastAPI
auto-generated Swagger UI).
---
## Running Tests
```bash
pytest
```
The suite is fully hermetic — it uses `FakeLLMProvider` (`tests/helpers.py` has
valid sample outputs per agent plus a `build_handler()` that routes each call to
the right response). `pytest.ini` sets `asyncio_mode = auto` and
`testpaths = tests`. Notable coverage:
- `test_agents.py` — structured output success, JSON repair recovery, persistent
failure, provider errors, and that each agent receives its dependency inputs.
- `test_discovery.py` — clarify/ready transitions, confirmation gating,
transcript history, last-answer-wins, idempotent field application.
- `test_orchestrator.py` — execution order, dependency feeding, single-review
round + targeted regeneration, revision limits, failed-revision artifact
preservation, blocking-only regeneration, agent-failure stopping, event
emission, run tracking and call-count reporting.
- `test_e2e.py` — a full food-delivery workflow from idea to approved blueprint
with the complete artifact set.
- `test_optimization.py` — regression locks for the optimization work: compact
schema embedding (no titles/whitespace), `schema_chars` telemetry, decision-dense
prompts (anti-overengineering, early discovery stop, two-round target, exact
critical/optional/not_applicable vocabulary), digest-not-raw handoffs, reviewer
context hygiene, deterministic execution levels, and the opt-in LLM summarizer
path.
---
## Benchmarking
The benchmark uses the **exact same idea every time** so runs are comparable:
```bash
python -m scripts.run_test "coffee shop in hawaii"
```
`run_test.py` auto-answers discovery questions, runs the full workflow against the
real provider, renders artifacts, then prints a per-agent table (duration, TTFT,
estimated input/output/schema tokens, repairs, invocation count, model) plus
workflow totals: discovery rounds, engineering + review runs, **real provider
calls (runs + internal JSON repairs)**, engineering and total wall-clock, slowest
agent, largest prompt, largest output, and the reviewer prompt size. A token-accounting
section separates estimated application-visible tokens from provider usage.
### Recorded runs (real Cursor Cloud Agents API, `composer-2.5`, fast mode)
| Metric | Baseline (as-shipped, LLM summaries) | Optimized (run A) | Optimized (run B) |
|---|---|---|---|
| Discovery runs | 2 | 2 | 3 |
| Engineering + review runs | 6 | 6 | 10 |
| Hidden LLM summarizer calls | 5 | **0** | **0** |
| Real provider calls (all runs + repairs, incl. discovery) | ~13 | ~11 | ~18 |
| Structured-output repairs | 0 | 3 | 5 |
| Estimated app-visible tokens | ~28.8K | ~31.3K | ~89.7K |
| Reviewer prompt input | ~9.9K tok | ~2.7K tok | ~8.8K tok |
| Engineering wall-clock | ~544s | ~521s | ~840s |
| Total wall-clock (incl. discovery) | ~668s | ~727s | ~1163s |
> **Read these honestly.** Runs A and B used the **identical optimized code** —
> the differences are model/scope/provider variance, not a code change. In run A
> discovery converged in 2 rounds on a simple informational site; in run B the
> auto-answered discovery chose a broader e-commerce scope (ordering, payments,
> loyalty, staff dashboard), which inflated every downstream digest and produced
> one legitimate blocking issue (an order-status enum mismatch) that the
> reviewer caught and the orchestrator fixed via one dependency-expanded
> regeneration pass. Cursor also has a large per-call latency floor (~60–130s)
> that dominates wall-clock. The wins that held across both optimized runs:
> **no summarizer calls** (11 → 6/10 real engineering calls), deterministic
> digests, and a compact reviewer base prompt (~2–4K tokens before repair
> resends). Verify with your own runs before claiming a trend.
### Token accounting
The Cursor Cloud Agents API does **not** expose per-run usage, so the only
application-visible metric is `visible_prompt_chars / 4` (input prompt incl.
embedded JSON schema, plus the raw model output). The Cursor dashboard's much
larger number counts framework, tooling and reasoning tokens that the provider
call cannot observe — the two are **not comparable 1:1** and must never be
presented as a before/after of the same unit. Concretely: *"Application-visible
prompt/output estimate decreased to ~31K tokens; Cursor's dashboard reports
additional provider-side framework/tool/reasoning usage that is not exposed
through the API."*
---
## Extending the System
### Add a new agent
1. Create the prompt in `prompts/<name>.py` and register it in the `PROMPTS`
dict in `prompts/__init__.py`.
2. Create the output schema in `schemas/<name>.py` and export it from
`schemas/__init__.py`.
3. Create `agents/<name>.py` with a class extending `BaseAgent` (set `name`,
`system_prompt`, `output_schema`, implement `_execute`), and add it to
`agents/__init__.py` `build_agents()`.
4. Add it to `ENGINEERING_ORDER` and `DEPENDENTS` in the orchestrator if it is
part of the linear pipeline, and feed it its dependencies in `_execute`.
5. Add sample output + a marker to `tests/helpers.py` and a test file.
### Swap the LLM provider
Implement `LLMProvider.generate()` and pass it to `LLMService`. No other code
changes — the whole system already depends only on the interface. (The
`config.py` `effective_api_key()` design already anticipates a second provider
key.)
### Add a rendered artifact
Add a `render_*` function in `artifacts/render.py`, call it from
`render_all()`, and it will automatically be persisted by the API generation
task and listed under artifacts.
---
## Security Notes
- **Secrets** live only in `.env` / environment variables. `.env.example` is
the template; never commit your real `.env`.
- The `LLMProvider` and tracker never log API keys or secrets.
- DevOps artifacts are generated for review only and are **never executed**
automatically (stated explicitly in the DevOps prompt).
- `ArtifactStore._safe_name` strips path separators to prevent path-traversal
on artifact names.
- The FastAPI CORS middleware currently allows all origins — appropriate for a
hackathon demo, but restrict it before production use.
|