Hugging Face's logo

Spaces:
AMRYBH
/
B2D-agentic-ai
Paused

App Files Community
B2D-agentic-ai / README.md
AMRYB's picture
AMRYB
Upload 91 files
287f3d3 verified
preview code
|
Raw
History Blame Contribute Delete
56.8 kB
metadata 
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
  2. High-Level Architecture
  3. The Full Workflow
  4. Project Lifecycle
  5. The Agent Team
  6. The LLM Layer
  7. The Orchestrator
  8. Data Model (Pydantic Schemas)
  9. Prompts
  10. Generated Artifacts
  11. REST API
  12. Persistence & Run Tracking
  13. Events & Live Streaming
  14. Project Structure
  15. Installation & Setup
  16. Configuration
  17. Running the System
  18. Running Tests
  19. Benchmarking
  20. Extending the System
  21. 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 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) 

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 AgentResults 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 DiscoveryTurns), 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).

# 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 

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) 

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) 

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 

uvicorn agentic_core.api.app:app --host 0.0.0.0 --port 8000

Then drive it from any HTTP client:

# 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 

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:

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.