style: replace box diagram with a list, normalize unicode to ASCII, trim comments

README.md

@@ -14,7 +14,7 @@ evaluates its **own** outputs with an LLM-as-judge, stores the results, and
 uses that signal to improve over time. The loop runs end to end:
 
 ```
-retrieve → generate → evaluate → log → improve → repeat
+retrieve -> generate -> evaluate -> log -> improve -> repeat
 ```
 
 Every good output becomes future few-shot fuel and a regression baseline; every
@@ -49,7 +49,7 @@ Most "LLM app" demos are a single prompt with no memory and no notion of
 quality. This project is built around three ideas that make it a genuine
 *self-improving* loop:
 
-1. **It judges itself on multiple axes.** Each output is scored 1–5 on four
+1. **It judges itself on multiple axes.** Each output is scored 1-5 on four
    independent dimensions (hook strength, brand alignment, clarity, conversion
    intent) by a separate judge model. Dimension scores are first-class and
    stored separately; there is no single "vibe" score driving decisions.
@@ -71,17 +71,15 @@ prompt versioning reinforce each other.
 
 ## Architecture
 
-```
-              ┌──────────────────────────── agent/core.py ───────────────────────────┐
-brand brief ─▶│ 1. retrieve top-3 high-scoring past outputs   (agent/memory.py, Chroma)│
-              │ 2. inject as few-shot examples                (agent/prompts.py)        │
-              │ 3. generate headline / body / cta             (agent/tools.py → Groq)   │
-              │ 4. judge each variant on 4 dimensions         (evals/judge.py → Groq)   │
-              │ 5. store run + outputs + scores               (db/store.py → SQLite)    │
-              │ 6. promote winners (≥4.0) → golden + memory   (feedback/loop.py)        │
-              │ 7. flag losers (<2.5) for review              (feedback/loop.py)        │
-              └────────────────────────────────────────────────────────────────────────┘
-```
+A single run flows through `agent/core.py`:
+
+1. Retrieve top-3 high-scoring past outputs (`agent/memory.py`, ChromaDB)
+2. Inject them as few-shot examples (`agent/prompts.py`)
+3. Generate headline / body / cta with Groq (`agent/tools.py`)
+4. Judge each variant on 4 dimensions with Groq (`evals/judge.py`)
+5. Store run + outputs + scores in SQLite (`db/store.py`)
+6. Promote winners (>= 4.0) to golden + memory (`feedback/loop.py`)
+7. Flag losers (< 2.5) for review (`feedback/loop.py`)
 
 | Layer            | File(s)                          | Responsibility                                  |
 |------------------|----------------------------------|-------------------------------------------------|
@@ -175,21 +173,21 @@ flagged).
 
 1. **Retrieve.** The incoming brief is embedded (locally, via
    `all-MiniLM-L6-v2`) and used to query ChromaDB for the **top-3 most similar
-   past outputs that scored ≥ 3.5/5**. Only proven-good copy is ever retrieved.
+   past outputs that scored >= 3.5/5**. Only proven-good copy is ever retrieved.
 
 2. **Generate.** Those examples are injected into the active generation prompt
    under a *"Past high-performing examples"* section, and the model produces a
    headline hook, body copy, and a CTA in one structured JSON response.
 
 3. **Evaluate.** Each of the three variants is immediately scored by the judge
-   model on the four rubric dimensions. Scores are clamped to 1–5 and a weighted
+   model on the four rubric dimensions. Scores are clamped to 1-5 and a weighted
    average is computed for internal ranking only.
 
 4. **Log.** The run, every variant, and every dimension score are written to
    SQLite.
 
 5. **Improve.** The feedback loop:
-   - promotes any output with a weighted average **≥ 4.0** into both the golden
+   - promotes any output with a weighted average **>= 4.0** into both the golden
      dataset and ChromaDB memory (so it can be retrieved next time);
    - flags any output **< 2.5** into the `flagged_outputs` table with the reason
      *"below quality threshold."*
@@ -202,7 +200,7 @@ over run; that is the "self-improving" part.
 ## Evaluation & regression tests
 
 ### The rubric (`evals/rubric.py`)
-Four dimensions, each 1–5:
+Four dimensions, each 1-5:
 
 | Dimension          | Question                                            | Weight |
 |--------------------|-----------------------------------------------------|:------:|
@@ -215,7 +213,7 @@ The weighted average is **internal only**, used for thresholds and ranking.
 All four raw dimensions are always stored separately.
 
 ### Golden dataset (`evals/golden.py`)
-Any output with weighted average **≥ 4.0** is captured (brief, output, all
+Any output with weighted average **>= 4.0** is captured (brief, output, all
 scores, prompt version, timestamp). This is the regression baseline.
 
 ### Regression runner (`evals/runner.py`)
@@ -245,7 +243,7 @@ spuriously) when `GROQ_API_KEY` is unset or the golden dataset is still empty.
 
 All prompt text lives in `agent/prompts.py`; nothing is hardcoded anywhere
 else. Each prompt is a named, versioned constant (`GENERATION_PROMPT_V1`,
-`GENERATION_PROMPT_V2`, …). A single constant selects which is live:
+`GENERATION_PROMPT_V2`, ...). A single constant selects which is live:
 
 ```python
 ACTIVE_PROMPT_VERSION = "GENERATION_PROMPT_V1"
@@ -282,7 +280,7 @@ cleanly with local sentence-transformers embeddings. SQLite alone can't do
 nearest-neighbour search over brief semantics; a hosted vector DB would violate
 the "local only" constraint and add ops overhead for no benefit at this scale.
 
-**Why dimension scoring over a composite score.** A single 1–10 "quality" score
+**Why dimension scoring over a composite score.** A single 1-10 "quality" score
 is unactionable and easy for a judge to anchor on. Scoring four independent
 dimensions tells you *why* copy is weak (great hook, poor clarity) and makes the
 signal far more stable and debuggable. We do compute a weighted average, but
@@ -290,19 +288,19 @@ only for internal thresholds/ranking; the four raw dimensions are always
 stored, so we never lose information by collapsing too early.
 
 **Why SQLite for eval storage.** Eval results are structured, relational, and
-queryable (runs → outputs → scores; golden; flagged). SQLite gives ACID
+queryable (runs -> outputs -> scores; golden; flagged). SQLite gives ACID
 guarantees, trivial setup, a single-file database, and real SQL, ideal for run
 history and a golden dataset. It needs no server and ships with Python. A hosted
 DB would add infrastructure with no upside for a local, single-node harness.
 
-**Why the 4.0 threshold for golden inclusion.** On a 1–5 scale, 4.0 means
+**Why the 4.0 threshold for golden inclusion.** On a 1-5 scale, 4.0 means
 "clearly good on the weighted blend" without demanding perfection. Set it lower
 and the golden set fills with mediocre copy, weakening both the regression
 baseline and the few-shot exemplars. Set it higher (e.g. 4.5) and you rarely
 capture anything, so the system never accumulates a baseline or improves. 4.0 is
 the point where entries are good enough to *defend* against regressions and to
 *teach* future runs. (The retrieval floor is a more permissive 3.5 so memory can
-draw on a slightly wider pool of solid examples, while only the strongest ≥4.0
+draw on a slightly wider pool of solid examples, while only the strongest >=4.0
 outputs become protected golden baselines.)
 
 ---

agent/__init__.py

@@ -11,5 +11,5 @@ try:  # truststore is optional; ignore if unavailable.
     import truststore
 
     truststore.inject_into_ssl()
-except Exception:  # noqa: BLE001 — best-effort; fall back to default certs.
+except Exception:  # noqa: BLE001 - best-effort; fall back to default certs.
     pass

agent/core.py

@@ -1,8 +1,6 @@
 """The main agent loop: retrieve -> generate -> evaluate -> store -> feedback.
 
-This ties memory, generation, the eval judge, persistence, and the feedback
-loop together. It is intentionally synchronous and dependency-injected so it
-can be driven from the API, the CLI, or tests with the same code path.
+Synchronous and dependency-injected so the API, CLI, and tests share one path.
 """
 
 from typing import Any, Optional
@@ -26,7 +24,6 @@ class Agent:
         self.memory = memory or Memory()
         self.temperature = temperature
 
-    # --------------------------------------------------------------- generate
     def generate_variants(self, brief: dict[str, Any], few_shot_block: str, prompt_version: str) -> dict[str, str]:
         """Call the LLM once and parse out the three ad-copy variants."""
         prompt = prompts.render_generation_prompt(brief, few_shot_block, prompt_version)
@@ -38,27 +35,19 @@ class Agent:
             "cta": str(parsed.get("cta", "")).strip(),
         }
 
-    # -------------------------------------------------------------------- run
     def run(self, brief: dict[str, Any]) -> dict[str, Any]:
         """Execute the full loop for one brand brief and return outputs + scores."""
-        # Imported here to keep module import order clean (evals/feedback import
-        # nothing from core, but core depends on them at call time).
+        # imported here to avoid an import cycle (core <-> evals/feedback)
         from evals.judge import judge_output
         from feedback.loop import run_feedback
 
         prompt_version = prompts.ACTIVE_PROMPT_VERSION
 
-        # 1. Retrieve top-3 most relevant high-scoring past outputs.
         retrieved = self.memory.retrieve(brief, k=3)
-
-        # 2. Inject them as few-shot examples.
         few_shot_block = prompts.build_few_shot_block(retrieved)
-
-        # 3. Generate the three variants.
         variants = self.generate_variants(brief, few_shot_block, prompt_version)
 
-        # 4. Evaluate every variant immediately.
-        # 5. Persist the run and each scored output.
+        # judge each variant and persist the run
         run_id = self.store.create_run(brief, prompt_version)
 
         scored_outputs: list[dict[str, Any]] = []
@@ -74,8 +63,7 @@ class Agent:
                 }
             )
 
-        # 6 + 7. Feedback loop: promote good outputs to golden + memory,
-        # flag poor ones for review.
+        # promote winners to golden + memory, flag the weak ones
         feedback_summary = run_feedback(
             store=self.store,
             memory=self.memory,
@@ -90,8 +78,7 @@ class Agent:
             "brief": brief,
             "prompt_version": prompt_version,
             "retrieved_examples": len(retrieved),
-            # Surfaced to the frontend so it can show the loop is self-improving.
-            "retrieved_count": len(retrieved),
+            "retrieved_count": len(retrieved),  # what the frontend reads
             "outputs": scored_outputs,
             "feedback": feedback_summary,
         }

agent/memory.py

@@ -1,12 +1,8 @@
-"""Retrieval and storage logic backed by ChromaDB + sentence-transformers.
+"""Vector memory backed by ChromaDB + sentence-transformers.
 
-Memory holds past generated outputs that scored well, embedded by their brand
-brief. On each new run we retrieve the top-k most similar high-scoring entries
-and feed them back as few-shot examples — this is the substrate of the
-self-improving loop.
-
-Only entries scoring above RETRIEVAL_SCORE_FLOOR (3.5/5) are ever stored or
-returned, so the agent only learns from outputs that actually worked.
+Stores high-scoring outputs embedded by their brief, and retrieves the most
+similar past winners as few-shot examples. Only entries >= RETRIEVAL_SCORE_FLOOR
+(3.5/5) are kept or returned.
 """
 
 import os

agent/prompts.py

@@ -1,30 +1,19 @@
-"""All prompts live here and nowhere else.
+"""All prompts live here, versioned by string key.
 
-Each prompt is versioned with an explicit string key. The single source of
-truth for which generation prompt is live is ACTIVE_PROMPT_VERSION. Swapping
-that constant is the supported way to roll a new prompt forward — and it is
-what the regression check guards (see evals/runner.py).
-
-Nothing in the codebase should hardcode prompt text outside this module.
+ACTIVE_PROMPT_VERSION selects the live generation prompt; swapping it is guarded
+by the regression check (evals/runner.py). Don't hardcode prompt text elsewhere.
 """
 
-# ---------------------------------------------------------------------------
-# Active version selector
-# ---------------------------------------------------------------------------
-# Change this to promote a new generation prompt. The regression runner is
-# expected to pass against the golden dataset before this is used for real.
+# Run the regression suite before promoting a new version.
 ACTIVE_PROMPT_VERSION = "GENERATION_PROMPT_V1"
 
 
-# ---------------------------------------------------------------------------
-# Generation prompts
-# ---------------------------------------------------------------------------
 GENERATION_PROMPT_V1 = """You are a senior direct-to-consumer (DTC) ad copywriter.
 
 You will be given a brand brief. Write three distinct pieces of ad copy:
-1. A HEADLINE hook — one short line that immediately grabs attention.
-2. A BODY copy — 2-3 sentences that build desire and reflect the brand tone.
-3. A CTA — a single short call to action that drives the stated goal.
+1. A HEADLINE hook - one short line that immediately grabs attention.
+2. A BODY copy - 2-3 sentences that build desire and reflect the brand tone.
+3. A CTA - a single short call to action that drives the stated goal.
 
 Rules:
 - Match the brief's tone and speak directly to the described audience.
@@ -52,9 +41,9 @@ GENERATION_PROMPT_V2 = """You are an award-winning DTC performance copywriter wh
 copy that converts cold traffic.
 
 You will be given a brand brief. Produce three pieces of ad copy:
-1. HEADLINE — a scroll-stopping hook of at most 8 words.
-2. BODY — 2-3 sentences leading with the strongest benefit, in the brand's voice.
-3. CTA — an imperative call to action tied directly to the stated goal.
+1. HEADLINE - a scroll-stopping hook of at most 8 words.
+2. BODY - 2-3 sentences leading with the strongest benefit, in the brand's voice.
+3. CTA - an imperative call to action tied directly to the stated goal.
 
 Rules:
 - Lead with benefit, not feature. Speak to the exact audience in the brief.
@@ -82,9 +71,6 @@ PROMPT_REGISTRY = {
 }
 
 
-# ---------------------------------------------------------------------------
-# Few-shot helpers
-# ---------------------------------------------------------------------------
 FEW_SHOT_HEADER = "Past high-performing examples (learn from their style, do not copy verbatim):"
 
 
@@ -127,9 +113,7 @@ def render_generation_prompt(brief: dict, few_shot_block: str, version: str | No
     )
 
 
-# ---------------------------------------------------------------------------
-# Judge prompt (LLM-as-judge). Versioned alongside generation prompts.
-# ---------------------------------------------------------------------------
+# Judge prompt, versioned alongside the generation prompts.
 JUDGE_PROMPT_VERSION = "JUDGE_PROMPT_V1"
 
 JUDGE_PROMPT_V1 = """You are a strict, fair advertising copy evaluator.

agent/tools.py

@@ -1,8 +1,7 @@
-"""Agent tools: the LLM client wrapper and the structured-generation helpers.
+"""Groq client wrapper and JSON parsing helpers.
 
-We deliberately call Groq directly (no LangChain). A single chat-completion
-helper is shared by both the generator and the judge so model/config lives in
-one place.
+One chat() helper is shared by the generator and the judge so model config
+lives in one place. No LangChain.
 """
 
 import json

api/main.py

@@ -5,10 +5,6 @@ Endpoints:
 - GET  /stats   -> live counts (runs, golden, flagged) for the frontend strip
 - POST /run     -> full agent loop (rate limited), returns outputs + scores
 
-CORS is configured for the Vercel frontend, the Groq key is protected by a
-per-IP rate limit, and a fresh deployment is seeded so the first visitor sees
-non-zero stats and working retrieval.
-
 Run locally:  uvicorn api.main:app --reload
 """
 
@@ -30,10 +26,7 @@ from slowapi.util import get_remote_address  # noqa: E402
 from agent.core import Agent  # noqa: E402  (after load_dotenv on purpose)
 from seed.loader import load_seed_if_empty  # noqa: E402
 
-# --------------------------------------------------------------------------- #
-# Shared singletons
-# --------------------------------------------------------------------------- #
-# A single shared agent (and therefore shared Store/Memory) for the process.
+# one shared agent (and Store/Memory) per process
 _agent: Agent | None = None
 
 
@@ -44,9 +37,6 @@ def get_agent() -> Agent:
     return _agent
 
 
-# --------------------------------------------------------------------------- #
-# CORS origins
-# --------------------------------------------------------------------------- #
 def _cors_origins() -> list[str]:
     """Origins from CORS_ORIGINS (comma-separated), always plus localhost:3000.
 
@@ -61,9 +51,7 @@ def _cors_origins() -> list[str]:
     return origins
 
 
-# --------------------------------------------------------------------------- #
-# Lifespan: seed a fresh deployment on startup
-# --------------------------------------------------------------------------- #
+# seed golden + memory on a fresh deployment so the first visitor isn't cold
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     try:
@@ -71,14 +59,11 @@ async def lifespan(app: FastAPI):
         seeded = load_seed_if_empty(agent.store, agent.memory)
         if seeded:
             print(f"[startup] Seeded {seeded} golden/memory example(s).")
-    except Exception as exc:  # noqa: BLE001 — never block startup on seeding.
+    except Exception as exc:  # noqa: BLE001 - never block startup on seeding.
         print(f"[startup] Seed skipped: {exc}")
     yield
 
 
-# --------------------------------------------------------------------------- #
-# App + rate limiter
-# --------------------------------------------------------------------------- #
 limiter = Limiter(key_func=get_remote_address)
 
 app = FastAPI(title="Self-Improving Ad Copy Agent", version="1.0.0", lifespan=lifespan)
@@ -94,9 +79,6 @@ app.add_middleware(
 )
 
 
-# --------------------------------------------------------------------------- #
-# Schemas
-# --------------------------------------------------------------------------- #
 class BrandBrief(BaseModel):
     brand: str = Field(..., examples=["FitFuel"])
     product: str = Field(..., examples=["High-protein meal replacement shake"])
@@ -105,9 +87,6 @@ class BrandBrief(BaseModel):
     goal: str = Field(..., examples=["Drive trial purchases"])
 
 
-# --------------------------------------------------------------------------- #
-# Endpoints
-# --------------------------------------------------------------------------- #
 @app.get("/")
 def root() -> dict[str, str]:
     return {"status": "ok", "endpoint": "POST /run with a brand brief"}
@@ -138,5 +117,5 @@ def run(request: Request, brief: BrandBrief) -> dict[str, Any]:
         return agent.run(brief.model_dump())
     except RuntimeError as exc:  # e.g. missing GROQ_API_KEY
         raise HTTPException(status_code=500, detail=str(exc)) from exc
-    except Exception as exc:  # noqa: BLE001 — surface generation/judge failures
+    except Exception as exc:  # noqa: BLE001 - surface generation/judge failures
         raise HTTPException(status_code=502, detail=f"Agent run failed: {exc}") from exc

db/store.py

@@ -1,8 +1,4 @@
-"""SQLite interface for runs, scores, golden dataset, flagged outputs, and versions.
-
-This is the persistence backbone of the system. Everything else depends on it.
-All access goes through the Store class so the schema lives in exactly one place.
-"""
+"""SQLite store for runs, outputs, the golden dataset, and flagged outputs."""
 
 import json
 import os
@@ -19,11 +15,8 @@ def _utcnow() -> str:
 
 
 class Store:
-    """Thin, explicit wrapper over a local SQLite database.
-
-    A single connection is shared with a lock so the same Store can be used
-    from FastAPI request handlers and CLI scripts without surprises.
-    """
+    """Local SQLite wrapper. One connection guarded by a lock so the API
+    handlers and CLI can share a Store."""
 
     def __init__(self, path: str = DEFAULT_SQLITE_PATH):
         self.path = path
@@ -33,7 +26,6 @@ class Store:
         self._conn.execute("PRAGMA journal_mode=WAL;")
         self._init_schema()
 
-    # ------------------------------------------------------------------ schema
     def _init_schema(self) -> None:
         with self._lock, self._conn:
             self._conn.executescript(
@@ -87,7 +79,6 @@ class Store:
                 """
             )
 
-    # -------------------------------------------------------------------- runs
     def create_run(self, brief: dict[str, Any], prompt_version: str) -> int:
         with self._lock, self._conn:
             cur = self._conn.execute(
@@ -103,7 +94,6 @@ class Store:
             ).fetchone()
         return dict(row) if row else None
 
-    # ----------------------------------------------------------------- outputs
     def add_output(
         self,
         run_id: int,
@@ -144,7 +134,6 @@ class Store:
             ).fetchall()
         return [dict(r) for r in rows]
 
-    # ------------------------------------------------------------------ golden
     def add_golden(
         self,
         brief: dict[str, Any],
@@ -198,7 +187,6 @@ class Store:
             ).fetchone()
         return row is not None
 
-    # ----------------------------------------------------------------- flagged
     def add_flagged(
         self,
         brief: dict[str, Any],
@@ -239,7 +227,6 @@ class Store:
             result.append(d)
         return result
 
-    # ------------------------------------------------------------------ counts
     def count_runs(self) -> int:
         with self._lock:
             row = self._conn.execute("SELECT COUNT(*) AS n FROM runs").fetchone()
@@ -255,7 +242,6 @@ class Store:
             row = self._conn.execute("SELECT COUNT(*) AS n FROM flagged_outputs").fetchone()
         return int(row["n"])
 
-    # ------------------------------------------------------------------- close
     def close(self) -> None:
         with self._lock:
             self._conn.close()

evals/golden.py

@@ -1,9 +1,8 @@
-"""Golden dataset manager.
+"""Golden dataset: the regression baseline.
 
-The golden dataset is the system's regression baseline: outputs that scored
-well enough (weighted average >= GOLDEN_THRESHOLD) are captured with their
-brief, scores, and prompt version. The regression runner later re-scores each
-entry against the active prompt and checks for drift.
+Outputs scoring >= GOLDEN_THRESHOLD are captured with their brief, scores, and
+prompt version. The regression runner later re-scores each entry and checks
+for drift.
 """
 
 from typing import Any

evals/judge.py

@@ -1,9 +1,7 @@
 """LLM-as-judge scorer.
 
-Uses the same Groq model as the generator (llama-3.3-70b-versatile) but with a
-strict, low-temperature judging prompt. Returns the four dimension scores plus
-a derived weighted average and a one-line rationale. It never collapses the
-output into a single composite the way a naive scorer would.
+Same Groq model as the generator, but a strict, temperature-0 prompt. Returns
+the four dimension scores plus a weighted average and a short rationale.
 """
 
 from typing import Any
@@ -23,7 +21,7 @@ def judge_output(brief: dict[str, Any], variant_type: str, output: str) -> dict[
     the valid range and default low.
     """
     if not output.strip():
-        # Nothing to score — treat as the floor.
+        # Nothing to score - treat as the floor.
         scores = rubric.normalize_scores({})
         scores["rationale"] = "Empty output."
         return scores

evals/rubric.py

@@ -1,9 +1,6 @@
-"""Scoring rubric definitions.
-
-The rubric is the contract between the judge and the rest of the system:
-the four dimensions, their 1-5 scale, and the weighting used to derive a
-single internal number. Per the design, dimension scores are first-class and
-stored separately; the weighted average exists only for ranking/thresholds.
+"""Scoring rubric: four 1-5 dimensions and the weights for the internal
+weighted average. Dimension scores are stored separately; the weighted average
+is only used for ranking/thresholds.
 """
 
 # The four scored dimensions, each on a 1-5 integer scale.

evals/runner.py

@@ -1,13 +1,8 @@
-"""Eval runner: runs the golden dataset against any prompt config and checks
-for regressions.
+"""Eval runner: re-scores the golden dataset against a prompt version.
 
-For each golden entry we regenerate copy for the same brief + variant using the
-prompt version under test, re-judge it, and compare the new weighted score to
-the entry's stored baseline. If any entry drops by more than REGRESSION_TOLERANCE
-(0.5), the run is marked failed.
-
-This is what guards a prompt-version swap (see agent/prompts.py) and what the
-pytest regression suite drives.
+For each golden entry, regenerate copy for the same brief + variant, re-judge
+it, and compare to the stored baseline. A drop > REGRESSION_TOLERANCE (0.5)
+fails the run. Guards prompt-version swaps and backs the pytest regression suite.
 """
 
 from dataclasses import dataclass, field
@@ -108,7 +103,7 @@ def format_report(report: EvalReport) -> str:
         "",
     ]
     if report.count == 0:
-        lines.append("No golden entries yet — nothing to check. (PASS)")
+        lines.append("No golden entries yet - nothing to check. (PASS)")
         return "\n".join(lines)
 
     for i, r in enumerate(report.results, 1):
@@ -120,10 +115,10 @@ def format_report(report: EvalReport) -> str:
 
     lines.append("")
     if report.passed:
-        lines.append("RESULT: PASS — no entry regressed beyond tolerance.")
+        lines.append("RESULT: PASS - no entry regressed beyond tolerance.")
     else:
         lines.append(
-            f"RESULT: FAIL — {len(report.regressions)} entry(ies) regressed beyond "
+            f"RESULT: FAIL - {len(report.regressions)} entry(ies) regressed beyond "
             f"{REGRESSION_TOLERANCE}. Do not promote this prompt version."
         )
     return "\n".join(lines)

feedback/loop.py

@@ -1,14 +1,7 @@
-"""Feedback loop: runs after every agent generation.
+"""Runs after each generation: promote winners into the golden dataset and
+ChromaDB memory (>= GOLDEN_THRESHOLD), flag the weak ones (< FLAG_THRESHOLD).
 
-Responsibilities:
-1. Read the scores from the latest run.
-2. Promote high-scoring outputs (weighted avg >= GOLDEN_THRESHOLD) into the
-   golden dataset AND into ChromaDB memory so future runs can retrieve them.
-3. Flag low-scoring outputs (weighted avg < FLAG_THRESHOLD) into the
-   flagged_outputs table with a clear reason.
-
-This is the closing arc of the self-improving loop: good outputs become future
-few-shot fuel and regression baselines; bad ones get surfaced for review.
+This closes the loop - promoted outputs become future few-shot examples.
 """
 
 from datetime import datetime, timezone
@@ -48,7 +41,6 @@ def run_feedback(
         scores = item["scores"]
         weighted = float(scores.get("weighted_average", 0.0))
 
-        # 2. Promote high scorers to golden + memory.
         if weighted >= GOLDEN_THRESHOLD:
             added = golden.maybe_add(brief, variant_type, content, scores, prompt_version)
             memory.add(
@@ -62,7 +54,6 @@ def run_feedback(
             if added:
                 promoted.append(variant_type)
 
-        # 3. Flag low scorers for review.
         elif weighted < FLAG_THRESHOLD:
             store.add_flagged(
                 brief=brief,

scripts/run_eval.py

@@ -49,7 +49,7 @@ def cmd_run(args: argparse.Namespace) -> int:
     brief = _load_brief(args.brief)
     console.print(Panel.fit(json.dumps(brief, indent=2), title="Brand Brief", border_style="cyan"))
 
-    with console.status("[bold green]Running agent loop (retrieve → generate → evaluate → feedback)..."):
+    with console.status("[bold green]Running agent loop (retrieve -> generate -> evaluate -> feedback)..."):
         agent = Agent()
         result = agent.run(brief)
 
@@ -95,7 +95,7 @@ def cmd_regression(args: argparse.Namespace) -> int:
     with console.status("[bold green]Running golden regression eval..."):
         report = run_golden_eval()
 
-    table = Table(title=f"Regression Eval — {report.prompt_version}", show_lines=True)
+    table = Table(title=f"Regression Eval - {report.prompt_version}", show_lines=True)
     table.add_column("#", justify="right")
     table.add_column("Variant", style="cyan")
     table.add_column("Baseline", justify="right")
@@ -115,11 +115,11 @@ def cmd_regression(args: argparse.Namespace) -> int:
         console.print(table)
     console.print()
     if report.passed:
-        console.print(Panel.fit("PASS — no entry regressed beyond tolerance.", border_style="green"))
+        console.print(Panel.fit("PASS - no entry regressed beyond tolerance.", border_style="green"))
     else:
         console.print(
             Panel.fit(
-                f"FAIL — {len(report.regressions)} entry(ies) regressed. "
+                f"FAIL - {len(report.regressions)} entry(ies) regressed. "
                 "Do not promote this prompt version.",
                 border_style="red",
             )

seed/loader.py

@@ -1,12 +1,7 @@
 """Startup seed loader.
 
-A fresh deployment has an empty golden dataset and empty memory, so the very
-first visitor would see zeroed stats and get no few-shot retrieval. To avoid
-that cold-start look, we load a small set of pre-scored example outputs into
-both SQLite (golden) and ChromaDB (memory) the first time the app boots with an
-empty golden table.
-
-Idempotent: if the golden dataset already has entries, this does nothing.
+Loads a few pre-scored examples into golden + memory on first boot so a fresh
+deployment isn't cold (zeroed stats, no retrieval). No-op if golden is non-empty.
 """
 
 import json

web/app/page.tsx

@@ -24,9 +24,9 @@ const ORDER: RunResponse["outputs"][number]["variant_type"][] = [
 ];
 
 const LOADING_PHASES = [
-  "Retrieving examples…",
-  "Generating variants…",
-  "Scoring with the judge…",
+  "Retrieving examples...",
+  "Generating variants...",
+  "Scoring with the judge...",
 ];
 
 export default function Page() {

web/components/BriefForm.tsx

@@ -73,7 +73,7 @@ export function BriefForm({
           disabled={loading}
           className="border border-zinc-300 bg-zinc-100 px-4 py-2 text-sm font-medium text-ink-950 transition-colors hover:bg-white disabled:cursor-not-allowed disabled:border-ink-600 disabled:bg-ink-700 disabled:text-zinc-400"
         >
-          {loading ? "Running…" : "Generate Copy"}
+          {loading ? "Running..." : "Generate Copy"}
         </button>
       </div>
     </form>

web/components/HowItWorks.tsx

@@ -7,12 +7,12 @@ const STEPS = [
   {
     n: "02",
     title: "Judge",
-    body: "A separate LLM-as-judge scores each variant 1–5 on four dimensions: hook strength, brand alignment, clarity, and conversion intent.",
+    body: "A separate LLM-as-judge scores each variant 1-5 on four dimensions: hook strength, brand alignment, clarity, and conversion intent.",
   },
   {
     n: "03",
     title: "Remember",
-    body: "Outputs scoring ≥ 4.0 are promoted into a golden dataset and a vector memory; weak ones (< 2.5) get flagged for review.",
+    body: "Outputs scoring >= 4.0 are promoted into a golden dataset and a vector memory; weak ones (< 2.5) get flagged for review.",
   },
   {
     n: "04",

web/components/StatsStrip.tsx

@@ -5,7 +5,7 @@ export function StatsStrip({ stats }: { stats: Stats | null }) {
     <span className="inline-flex items-baseline gap-1.5">
       <span className="text-zinc-500">{label}</span>
       <span className="font-mono text-zinc-200 tabular-nums">
-        {value === null ? "–" : value}
+        {value === null ? "-" : value}
       </span>
     </span>
   );