Blueprint candidate engine (Batch 4)¶

The candidate engine turns a raw idea into three quality-tiered, template-aware blueprint options — deterministically, with no LLM and no network.

Pipeline¶

IdeaRequest
  → idea_parser.parse_idea_request()     deterministic keyword parsing
  → templates.detect_template()          flagship template or generic fallback
  → candidate_generator.generate_candidates()
      → scorer.score_candidate()         fit score + human-readable rationale
  → [starter, standard, production]      BlueprintCandidate contracts

Flagship template families¶

These match the templates showcased in the Matrix Builder UI. Each carries its own page plan, API routes, services, and task definitions with file allowlists.

Template	Detects on	Build type
`github-repo-intelligence-agent`	github, repository, repo, codebase, commit, pull request	agent
`document-qa-agent`	document, pdf, q&a, question, answers, rag, knowledge base	agent
`developer-portfolio-reviewer`	portfolio, resume, cv, review, feedback, career	agent
`generic` (fallback)	anything else	detected from signals

Detection requires at least 2 keyword hits (MIN_KEYWORD_HITS) so a single weak match doesn't over-claim a template. Ties break by declaration order — always stable.

What the parser detects¶

Template family (above).
Build type refinement: an idea shaped like an agent/API refines the default build_type (app); an explicit user choice is never overridden.
Auth intent: "login", "accounts", "sign in" (or constraints.requires_auth) flips the blueprint's stack to auth: session.

Scoring¶

Deterministic 0..1 score per candidate: 50% template fit (keyword hits), 30% requested quality-level match, 20% constraint fit (preferred-stack overlap; forbidden-stack overlap applies a heavy penalty and a visible warning). The rationale string explains the score in plain language and is what the UI shows on candidate cards.

Controlled blueprints from templates¶

generate_controlled_blueprint now uses the detected template's curated plan — pages, API routes, services, and TASK-NNN tasks with file allowlists — for flagship ideas, and falls back to the keyword planner for generic ideas. Both paths produce contracts that validate against matrix-definitions matrix-blueprint.schema.json.

Examples¶

examples/ideas/*.json contains, for each flagship idea: the three canonical candidate projections and the selected blueprint projection, generated by the real engine with a pinned clock (regenerate by re-running the snippet in the file header's batch notes).