Building Your Portfolio

git tag r1-v1.0 r1                    # Day 22's tag, same commit
git tag r2-v1.0 <commit-of-Day-34>    # no earlier tag: use the commit that shipped R2
git tag -l 'r3*'                      # r3-v1.0 exists from Day 62; if not: git tag r3-v1.0 <Day-62-commit>
git tag r4-v1.0 <commit-of-Day-76>
git tag r5-v1.0 <commit-of-Day-90>
git push origin --tags                # tags only reach GitHub when pushed

# Atlas Ask
A RAG chatbot built with LangGraph and pgvector, featuring hybrid search,
reranking and a Gradio UI. Highly accurate and cost-efficient.

# Atlas Ask: cited answers for Orbit maintainers
Ask a question about Orbit's docs and get an answer with links to the exact sections.
**Demo:** [2-minute video](docs/demo.mp4) · [live Space](https://huggingface.co/spaces/you/atlas-ask) (may be asleep)

## Results
| Metric | Vector | Hybrid | Hybrid + rerank | n | Measured | Source |
|---|---|---|---|---|---|---|
| recall@5 | 0.71 | 0.82 | 0.88 | 60 | 2026-11-02 | `reports/r2_retrieval.json` |
| answer pass rate | | | 0.83 | 60 | 2026-11-02 | `reports/r2_answers.json` |
| $/request · p95 | | | $0.0021 · 2.4 s | 60 | 2026-11-02 | `reports/r2_cost.json` |

**Known failures:** questions that need two docs at once (cases `q17`, `q42`); non-English issues.

# script_id: day_099_portfolio/readme_check
# Minimal README section check. Install: none (stdlib). Env: none. Services: none.
# Usage: python readme_check.py [path/to/README.md]   (no path: checks a vague sample)
import re
import sys
from pathlib import Path

REQUIRED = ("What it does", "Demo", "Results", "Architecture",
            "Decisions & trade-offs", "Run it", "Known failures")
SAMPLE = "# Atlas Ask\nA RAG chatbot.\n## Features\n## Installation\n## Results\n"

path = Path(sys.argv[1]) if len(sys.argv) > 1 else None
text = path.read_text(encoding="utf-8") if path else SAMPLE
titles = [t.strip().lower() for t in re.findall(r"^##\s+(.+)$", text, re.M)]
missing = [s for s in REQUIRED if not any(t.startswith(s.lower()) for t in titles)]
print(f"{len(REQUIRED) - len(missing)}/{len(REQUIRED)} sections present")
for s in missing:
    print(f"MISSING: ## {s}")

1/7 sections present
MISSING: ## What it does
MISSING: ## Demo
MISSING: ## Architecture
MISSING: ## Decisions & trade-offs
MISSING: ## Run it
MISSING: ## Known failures

# script_id: day_099_portfolio/metrics_table
"""Render metrics.json rows into a Results table and a tour README; refuse unsourced numbers."""
# Install: none (stdlib). Env: none.
# Usage: python metrics_table.py [metrics.json] [--repo-url URL] [--out TOUR.md]
import argparse
import json
from pathlib import Path

SAMPLE_ROWS = [  # EXAMPLE values only: replace with rows read from your own reports
    {"release": "R1", "metric": "field accuracy (held-out)", "value": "0.91", "n": 40,
     "measured_on": "2026-10-01", "source": "reports/r1_eval.json"},
    {"release": "R2", "metric": "recall@5 (hybrid + rerank)", "value": "0.88", "n": 60,
     "measured_on": "2026-11-02", "source": "reports/r2_retrieval.json"},
    {"release": "R3", "metric": "task pass rate (all criteria)", "value": "0.75", "n": 24,
     "measured_on": "2026-11-03", "source": "reports/r3_agent_evals.json"},
    {"release": "R4", "metric": "label accuracy (triage_gold)", "value": "0.86", "n": 50,
     "measured_on": "2026-11-04", "source": "reports/r4_triage.json"},
    {"release": "R5", "metric": "p95 latency, staging (s)", "value": "2.4", "n": 600,
     "measured_on": "2026-11-05", "source": "reports/r5_load.json"},
]


def render_metrics_table(rows: list[dict]) -> str:
    """Markdown table with provenance; raises ValueError on any unsourced row."""
    bad = [r.get("metric", "?") for r in rows
           if not str(r.get("source") or "").strip() or not r.get("n")]
    if bad:
        raise ValueError(f"{len(bad)} row(s) have no source or n: {bad}")
    out = ["| Release | Metric | Value | n | Measured | Source |",
           "|---|---|---|---|---|---|"]
    out += [f"| {r['release']} | {r['metric']} | {r['value']} | {r['n']} "
            f"| {r['measured_on']} | [`{r['source']}`]({r['source']}) |" for r in rows]
    return "\n".join(out)

# script_id: day_099_portfolio/metrics_table
RELEASES = [  # (release, tag, title, what it adds); use the tags your capstones used
    ("R1", "r1-v1.0", "Extractor", "issues to validated records, with an eval"),
    ("R2", "r2-v1.0", "Ask", "cited RAG answers over Orbit docs, with a UI"),
    ("R3", "r3-v1.0", "Investigator", "a durable agent with approvals and trajectory evals"),
    ("R4", "r4-v1.0", "Triage", "a guarded triage pipeline with a red-team suite"),
    ("R5", "r5-v1.0", "Launch", "served, rate-limited, load-tested and monitored"),
]


def render_tour(rows: list[dict], repo_url: str) -> str:
    lines = ["# Atlas: an AI assistant for Orbit maintainers", "",
             "One system in five releases. Each tag runs on its own.", "",
             "| Release | Tag | What it adds |", "|---|---|---|"]
    lines += [f"| {r} {title} | [`{tag}`]({repo_url}/tree/{tag}) | {adds} |"
              for r, tag, title, adds in RELEASES]
    return "\n".join(lines + ["", "## Results", "", render_metrics_table(rows)])


def main() -> None:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("metrics", nargs="?", help="metrics.json (default: example rows)")
    ap.add_argument("--repo-url", default="https://github.com/you/atlas")
    ap.add_argument("--out", help="write the tour README here instead of stdout")
    args = ap.parse_args()
    rows = json.loads(Path(args.metrics).read_text()) if args.metrics else SAMPLE_ROWS
    tour = render_tour(rows, args.repo_url)
    Path(args.out).write_text(tour + "\n") if args.out else print(tour)
    try:  # the claim that started this section, with nothing behind it
        render_metrics_table([{"release": "R5", "metric": "~40% cheaper", "value": "?"}])
    except ValueError as err:
        print(f"\nREJECTED: {err}")


if __name__ == "__main__":
    main()

# Atlas: an AI assistant for Orbit maintainers

One system in five releases. Each tag runs on its own.

| Release | Tag | What it adds |
|---|---|---|
| R1 Extractor | [`r1-v1.0`](https://github.com/you/atlas/tree/r1-v1.0) | issues to validated records, with an eval |
...
## Results

| Release | Metric | Value | n | Measured | Source |
|---|---|---|---|---|---|
| R1 | field accuracy (held-out) | 0.91 | 40 | 2026-10-01 | [`reports/r1_eval.json`](reports/r1_eval.json) |
...

REJECTED: 1 row(s) have no source or n: ['~40% cheaper']

# script_id: day_099_portfolio/portfolio_check
"""Portfolio hygiene check: README sections and numbers, secrets, cold-clone basics, compose."""
# Install: none (stdlib, Python 3.11+). Needs git on PATH to list tracked files
# (falls back to walking the tree). Env: ORBIT_DATA (optional, for the demo fixture),
# PORTFOLIO_ALLOW (optional, default "FAKE"). Services: none.
# Usage: python portfolio_check.py PATH [--allow FAKE,example]  |  python portfolio_check.py --demo
import argparse
import os
import re
import subprocess
import tempfile
from dataclasses import dataclass
from pathlib import Path

REQUIRED_SECTIONS: tuple[str, ...] = (
    "What it does", "Demo", "Results", "Architecture",
    "Decisions & trade-offs", "Run it", "Known failures",
)


@dataclass
class Finding:
    check: str
    passed: bool
    detail: str = ""  # the fix hint, printed only on FAIL


def sections(text: str) -> dict[str, str]:
    """Map each lower-cased H2 title to the text under it."""
    parts = re.split(r"^##\s+(.+?)\s*$", text, flags=re.M)
    return {t.lower(): body for t, body in zip(parts[1::2], parts[2::2])}


def check_readme(path: Path, required: tuple[str, ...] = REQUIRED_SECTIONS) -> list[Finding]:
    if not path.exists():
        return [Finding("readme sections", False, f"no {path.name} at the repo root")]
    found = sections(path.read_text(encoding="utf-8"))
    missing = [s for s in required if not any(t.startswith(s.lower()) for t in found)]
    return [Finding("readme sections", not missing,
                    "missing " + ", ".join(f'"{m}"' for m in missing))]

# script_id: day_099_portfolio/portfolio_check
SECRET_PATTERNS = {  # common shapes, not exhaustive: GitHub secret scanning knows far more
    "sk- style API key": re.compile(r"\bsk-[A-Za-z0-9_-]{8,}"),
    "AWS access key id": re.compile(r"\bAKIA[0-9A-Z]{16}\b"),
    "GitHub token": re.compile(r"\bgh[pousr]_[A-Za-z0-9]{30,}"),
    "private key block": re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"),
}
SKIP_DIRS = {".git", ".venv", "node_modules", "__pycache__"}


def tracked_files(root: Path) -> list[Path]:
    """Files git tracks (what a reviewer clones); walk the tree if that fails."""
    try:
        out = subprocess.run(["git", "-C", str(root), "ls-files", "-z"],
                             capture_output=True, text=True, check=True).stdout
        files = [root / p for p in out.split("\0") if p]
    except (OSError, subprocess.CalledProcessError):
        files = []  # not a git repo, or git missing
    return files or [p for p in root.rglob("*") if p.is_file()
                     and not SKIP_DIRS & set(p.relative_to(root).parts)]


def scan_secrets(files: list[Path], allow: tuple[str, ...] = ("FAKE",)) -> list[Finding]:
    """Flag secret-shaped strings; `allow` lists markers of known-fake fixtures."""
    hits = []
    for f in files:
        try:
            lines = f.read_text(encoding="utf-8").splitlines()
        except (UnicodeDecodeError, OSError):
            continue  # binary or unreadable file
        for n, line in enumerate(lines, 1):
            for kind, pat in SECRET_PATTERNS.items():
                for m in pat.finditer(line):
                    if not any(a in m.group() for a in allow):
                        hits.append(f"{f.name}:{n} {kind} ({m.group()[:7]}…)")  # never print a key
    return [Finding("no secrets", not hits, "; ".join(hits))]

# script_id: day_099_portfolio/portfolio_check
LOCKFILES = ("uv.lock", "poetry.lock", "package-lock.json")
LICENSES = ("LICENSE", "LICENSE.md", "LICENSE.txt")
FENCE = "`" * 3  # built at runtime so this lesson's own code fences stay balanced


def check_hygiene(root: Path, files: list[Path]) -> list[Finding]:
    rel = {p.relative_to(root).as_posix() for p in files}
    return [
        Finding(".env not committed", ".env" not in rel, "delete it, rotate any key it held"),
        Finding(".env.example", (root / ".env.example").exists(), "add one with empty values"),
        Finding("lockfile", any((root / n).exists() for n in LOCKFILES), "commit uv.lock"),
        Finding("LICENSE", any((root / n).exists() for n in LICENSES), "add a licence file"),
        Finding("tests/", (root / "tests").is_dir(), "add at least one test"),
    ]


def check_compose(root: Path) -> list[Finding]:
    found = [p for p in (root / "compose.yaml", root / "docker-compose.yml") if p.exists()]
    if not found:
        return []  # no compose file, nothing to check
    text = found[0].read_text(encoding="utf-8")
    problems = ["obsolete `version:` key"] if re.search(r"^version\s*:", text, re.M) else []
    for image in re.findall(r"^\s*image:\s*[\"']?([^\s\"']+)", text, re.M):
        if image.endswith(":latest") or ":" not in image.rsplit("/", 1)[-1]:
            problems.append(f"unpinned image {image}")
    return [Finding("compose pinned", not problems, "; ".join(problems))]


def check_readme_content(path: Path) -> list[Finding]:
    if not path.exists():
        return []
    text = path.read_text(encoding="utf-8")
    results = next((b for t, b in sections(text).items() if t.startswith("results")), "")
    has_number = re.search(r"\d+\.\d+|\d+\s*%|\$\s*\d", results) is not None
    placeholder = re.search(r"\b(TODO|TBD)\b|\?\?", results) is not None
    return [Finding("numbers in Results", has_number and not placeholder,
                    "measured values with n, date and source; no TODO"),
            Finding("mermaid diagram", FENCE + "mermaid" in text, "add an architecture diagram")]

# script_id: day_099_portfolio/portfolio_check
def check_repo(root: Path, allow: tuple[str, ...] = ("FAKE",)) -> list[Finding]:
    files, readme = tracked_files(root), root / "README.md"
    return (check_readme(readme) + check_readme_content(readme) + scan_secrets(files, allow)
            + check_hygiene(root, files) + check_compose(root))


def build_demo_fixture() -> Path:
    """A deliberately flawed Atlas repo in a temp dir. Fix it until every check passes."""
    root = Path(tempfile.mkdtemp(prefix="atlas_portfolio_"))
    (root / "tests").mkdir()
    (root / "README.md").write_text(
        "# Atlas Ask\n## What it does\nCited answers over Orbit docs.\n## Demo\n"
        "[2-minute video](demo.mp4)\n## Results\n| metric | value |\n|---|---|\n"
        "| recall@5 | TODO |\n## Architecture\n" + FENCE + "mermaid\nflowchart LR\n"
        "  Q[question] --> A[answer]\n" + FENCE + "\n## Decisions & trade-offs\n"
        "Hybrid search, because exact ORB codes broke vector-only.\n## Run it\n"
        "uv run python app.py\n", encoding="utf-8")
    sec = Path(os.environ.get("ORBIT_DATA", "datasets/orbit")) / "docs" / "security.md"
    lines = sec.read_text(encoding="utf-8").splitlines() if sec.exists() else []
    fixture = next((x for x in lines if "sk-test-FAKE-" in x), 'api_key="sk-test-FAKE-0000"')
    (root / "tests" / "fixture_pii.txt").write_text(fixture.strip() + "\n", encoding="utf-8")
    planted = "sk-" + "proj-" + "a1B2c3D4" * 3  # assembled at runtime: not a real key
    (root / "config.py").write_text(f'API_KEY = "{planted}"\n', encoding="utf-8")
    (root / ".env").write_text("OPENAI_API_KEY=\n", encoding="utf-8")
    (root / ".env.example").write_text("OPENAI_API_KEY=\n", encoding="utf-8")
    (root / "uv.lock").write_text("version = 1\n", encoding="utf-8")
    (root / "compose.yaml").write_text(
        'version: "3.8"\nservices:\n  db:\n    image: pgvector/pgvector:latest\n',
        encoding="utf-8")
    return root

# script_id: day_099_portfolio/portfolio_check
def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("path", nargs="?", help="repo root; omit (or --demo) for the flawed fixture")
    ap.add_argument("--demo", action="store_true", help="check a generated, flawed fixture")
    ap.add_argument("--allow", default=os.environ.get("PORTFOLIO_ALLOW", "FAKE"),
                    help="comma list of substrings that mark known-fake secrets ('' = none)")
    args = ap.parse_args()
    demo = args.demo or not args.path
    root = build_demo_fixture() if demo else Path(args.path).resolve()
    findings = check_repo(root, tuple(a for a in args.allow.split(",") if a))
    for f in findings:
        print(f"{'PASS' if f.passed else 'FAIL'}  {f.check:<19} {'' if f.passed else f.detail}")
    passed = sum(f.passed for f in findings)
    print(f"{passed}/{len(findings)} checks passed  ({root})")
    return 0 if passed == len(findings) or demo else 1  # the demo always exits 0


if __name__ == "__main__":
    raise SystemExit(main())

FAIL  readme sections     missing "Known failures"
FAIL  numbers in Results  measured values with n, date and source; no TODO
PASS  mermaid diagram
FAIL  no secrets          config.py:1 sk- style API key (sk-proj…)
FAIL  .env not committed  delete it, rotate any key it held
PASS  .env.example
PASS  lockfile
FAIL  LICENSE             add a licence file
PASS  tests/
FAIL  compose pinned      obsolete `version:` key; unpinned image pgvector/pgvector:latest
4/10 checks passed  (/tmp/atlas_portfolio_k2j9x1)

# script_id: day_099_portfolio/cold_clone
"""Time a cold clone: clone -> .env -> uv sync -> one smoke command, step by step."""
# Install: none (stdlib). Needs git; uv is optional (the sync step is skipped without it).
# Usage: python cold_clone.py REPO_URL_OR_PATH --run "uv run python -m atlas.demo"
#        python cold_clone.py          (demo: builds and clones a tiny local repo)
import argparse
import shlex
import shutil
import subprocess
import sys
import tempfile
import time
from pathlib import Path

BUDGET_S = 180.0  # the 3-minute bar


def timed(name: str, cmd: list[str], cwd: Path, log: list[tuple]) -> bool:
    t0 = time.perf_counter()
    try:
        r = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)
        ok, tail = r.returncode == 0, (r.stdout + r.stderr).strip().splitlines()[-1:]
    except OSError as err:  # command not found
        ok, tail = False, [str(err)]
    log.append((name, ok, time.perf_counter() - t0, (tail or [""])[0][:60]))
    return ok


def make_demo_repo() -> str:
    src = Path(tempfile.mkdtemp(prefix="atlas_src_"))
    (src / "app.py").write_text('print("Atlas offline demo: 3 answers, 0 API calls")\n')
    (src / ".env.example").write_text("OPENAI_API_KEY=\nATLAS_BACKEND=stub\n")
    commit = ["git", "-c", "user.name=demo", "-c", "user.email=demo@example.com", "commit", "-qm", "init"]
    for cmd in (["git", "init", "-q"], ["git", "add", "."], commit):
        subprocess.run(cmd, cwd=src, check=True, capture_output=True)
    return str(src)

# script_id: day_099_portfolio/cold_clone
def cold_clone(repo: str, run_cmd: list[str]) -> list[tuple]:
    log: list[tuple] = []
    work = Path(tempfile.mkdtemp(prefix="cold_clone_"))
    if not timed("git clone", ["git", "clone", "-q", repo, "repo"], work, log):
        return log
    dest = work / "repo"
    has_example = (dest / ".env.example").exists()
    if has_example:
        shutil.copy(dest / ".env.example", dest / ".env")
    log.append(("cp .env.example .env", has_example, 0.0, "" if has_example else "no .env.example"))
    if shutil.which("uv") and (dest / "pyproject.toml").exists():
        timed("uv sync --locked", ["uv", "sync", "--locked"], dest, log)
    else:
        log.append(("uv sync --locked", True, 0.0, "skipped (no uv or no pyproject.toml)"))
    timed("smoke command", run_cmd, dest, log)
    return log


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("repo", nargs="?", help="git URL or local path; omit for the demo")
    ap.add_argument("--run", help='smoke command, e.g. "uv run python -m atlas.demo"')
    args = ap.parse_args()
    repo = args.repo or make_demo_repo()
    log = cold_clone(repo, shlex.split(args.run) if args.run else [sys.executable, "app.py"])
    for name, ok, secs, tail in log:
        print(f"{'ok  ' if ok else 'FAIL'} {secs:5.1f}s  {name:<22} {tail}")
    total = sum(step[2] for step in log)
    verdict = "PASS" if all(step[1] for step in log) and total <= BUDGET_S else "FAIL"
    print(f"{verdict}: {total:.1f}s total (budget {BUDGET_S:.0f}s)")
    return 0 if verdict == "PASS" else 1


if __name__ == "__main__":
    raise SystemExit(main())

ok     0.2s  git clone
ok     0.0s  cp .env.example .env
ok     0.0s  uv sync --locked       skipped (no uv or no pyproject.toml)
ok     0.1s  smoke command          Atlas offline demo: 3 answers, 0 API calls
PASS: 0.2s total (budget 180s)

1. Problem (15 s): "Orbit's tracker holds 240 issues; finding the right doc takes minutes."
2. Live run (45 s): ask one real question; show the cited answer and click a citation.
3. Numbers (30 s): the Results table: recall@5, answer pass rate, $/request, p95, with n.
4. One failure (20 s): a known failure case and why it happens.
5. Next step (10 s): what you'd fix first and how you'd measure it.

# script_id: day_099_portfolio/standalone_extract
"""Scaffold a standalone repo by COPYING files out of a bigger project (never importing)."""
# Install: none (stdlib). Env: none.
# Usage: python standalone_extract.py SRC DEST --files atlas/workflows.py atlas/schemas.py \
#            --rename atlas=router        (no arguments: runs on a tiny fake Atlas tree)
import argparse
import re
import tempfile
from pathlib import Path

IMPORT = re.compile(r"^(\s*(?:from|import)\s+)(\w+)((?:\.\w+)*)", re.M)
SKELETON = ("What it does", "Demo", "Results", "Architecture",
            "Decisions & trade-offs", "Run it", "Known failures")


def extract(src: Path, dest: Path, files: list[str], old: str, new: str) -> list[str]:
    """Copy files, rename `old` to `new` in import lines, return leftover-import warnings."""
    for rel in files:
        parts = Path(rel).parts
        target = dest.joinpath(new if parts[0] == old else parts[0], *parts[1:])
        target.parent.mkdir(parents=True, exist_ok=True)
        text = IMPORT.sub(lambda m: m[1] + (new if m[2] == old else m[2]) + m[3],
                          (src / rel).read_text(encoding="utf-8"))
        target.write_text(text, encoding="utf-8")
    warnings = []
    for py in sorted(dest.rglob("*.py")):
        for m in IMPORT.finditer(py.read_text(encoding="utf-8")):
            mod = dest.joinpath(m[2], *m[3].lstrip(".").split(".")) if m[3] else None
            if m[2] == new and mod and not (mod.with_suffix(".py").exists() or mod.is_dir()):
                warnings.append(f"{py.relative_to(dest)} imports {m[2]}{m[3]}: not copied")
    return warnings


def scaffold(dest: Path, pkg: str) -> None:
    (dest / pkg).mkdir(parents=True, exist_ok=True)
    (dest / pkg / "__init__.py").touch()
    body = "\n\n".join(f"## {s}\nTODO" for s in SKELETON)
    (dest / "README.md").write_text(f"# {pkg}\n\n{body}\n\nSample data: Orbit (CC0-1.0).\n")
    (dest / ".env.example").write_text("OPENAI_API_KEY=\n")
    (dest / ".gitignore").write_text(".env\n.venv/\n__pycache__/\n")
    (dest / "tests").mkdir(exist_ok=True)
    (dest / "tests" / "test_smoke.py").write_text(f"import {pkg}\n\n\ndef test_import():\n    assert {pkg}\n")

# script_id: day_099_portfolio/standalone_extract
def demo_source() -> Path:
    src = Path(tempfile.mkdtemp(prefix="atlas_tree_"))
    (src / "atlas").mkdir()
    (src / "atlas" / "schemas.py").write_text("from pydantic import BaseModel\n\n\nclass Issue(BaseModel):\n    title: str\n")
    (src / "atlas" / "llm.py").write_text("def complete(prompt: str) -> str: ...\n")
    (src / "atlas" / "workflows.py").write_text(
        "from atlas.schemas import Issue\nfrom atlas.llm import complete\n\n\n"
        "def route_issue(issue: Issue) -> str:\n    return complete(issue.title)\n")
    return src


def main() -> None:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("src", nargs="?")
    ap.add_argument("dest", nargs="?")
    ap.add_argument("--files", nargs="+", default=["atlas/workflows.py", "atlas/schemas.py"])
    ap.add_argument("--rename", default="atlas=router", help="OLD=NEW package name")
    args = ap.parse_args()
    src = Path(args.src) if args.src else demo_source()
    dest = Path(args.dest) if args.dest else Path(tempfile.mkdtemp(prefix="standalone_"))
    old, new = args.rename.split("=")
    scaffold(dest, new)
    for w in extract(src, dest, args.files, old, new):
        print("WARN", w)
    print("created:", ", ".join(sorted(p.relative_to(dest).as_posix()
                                       for p in dest.rglob("*") if p.is_file())))
    print("TODO: add a LICENSE, real Results numbers and an eval, then run portfolio_check")


if __name__ == "__main__":
    main()

WARN router/workflows.py imports router.llm: not copied
created: .env.example, .gitignore, README.md, router/__init__.py, router/schemas.py, router/workflows.py, tests/test_smoke.py
TODO: add a LICENSE, real Results numbers and an eval, then run portfolio_check

1. Hook: the problem or the surprising finding (1 paragraph)
2. Why it matters: who hit it and what it cost (1 paragraph)
3. What I tried first, and how I knew it failed (the number)
4. What worked: one diagram, one code snippet
5. Results: before/after table with n, date, method
6. What I'd do differently
7. TL;DR: 3 bullets, plus a link to the repo and the exact tag

# script_id: day_099_portfolio/writeup_lint
"""Pre-publish checks for a technical write-up in Markdown."""
# Install: none (stdlib). Env: none.
# Usage: python writeup_lint.py post.md [--min 800] [--max 1500] [--repo github.com/you/atlas]
#        (no file: lints a short sample draft)
import argparse
import re
from pathlib import Path

FENCE = "`" * 3  # built at runtime so this lesson's own fences stay balanced
VAGUE = re.compile(r"\b(faster|cheaper|better|improved|significantly|dramatically)\b", re.I)
SAMPLE = ("# Hybrid search fixed my ORB-code queries\n\nVector search missed exact codes. "
          "Hybrid search was much better and significantly cheaper.\n\n" + FENCE +
          "python\nhits = hybrid_search(query, k=5)\n" + FENCE + "\n")


def lint(text: str, lo: int, hi: int, repo: str) -> list[tuple[str, bool, str]]:
    prose = re.sub(FENCE + r".*?" + FENCE, " ", text, flags=re.S)
    words = len(re.findall(r"\b\w+\b", prose))
    numbers = re.findall(r"\d+(?:\.\d+)?\s*%|\$\s*\d+(?:\.\d+)?|\b\d+\.\d+\b", prose)
    vague = [s.strip()[:50] for s in re.split(r"(?<=[.!?])\s+", prose)
             if VAGUE.search(s) and not re.search(r"\d", s)]
    return [
        ("length", lo <= words <= hi, f"{words} words, target {lo}-{hi}"),
        ("before/after numbers", len(numbers) >= 2, f"{len(numbers)} measured values"),
        ("diagram", FENCE + "mermaid" in text or "![" in text, "add a Mermaid block or image"),
        ("code snippet", re.search("^" + FENCE + r"(?!mermaid)\w+", text, re.M) is not None,
         "show the line that mattered"),
        ("links the repo", repo in text, f"link {repo} and the tag"),
        ("what I'd do differently", re.search(r"^#+ .*differently", text, re.I | re.M) is not None,
         "add the section"),
        ("claims have numbers", not vague, " | ".join(vague)),
    ]


if __name__ == "__main__":
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("post", nargs="?")
    ap.add_argument("--min", type=int, default=800)
    ap.add_argument("--max", type=int, default=1500)
    ap.add_argument("--repo", default="github.com/you/atlas")
    a = ap.parse_args()
    results = lint(Path(a.post).read_text(encoding="utf-8") if a.post else SAMPLE, a.min, a.max, a.repo)
    for name, ok, hint in results:
        print(f"{'PASS' if ok else 'FAIL'}  {name:<24} {'' if ok else hint}")
    raise SystemExit(0 if a.post is None or all(ok for _, ok, _ in results) else 1)

FAIL  length                   20 words, target 800-1500
FAIL  before/after numbers     0 measured values
FAIL  diagram                  add a Mermaid block or image
PASS  code snippet
FAIL  links the repo           link github.com/you/atlas and the tag
FAIL  what I'd do differently  add the section
FAIL  claims have numbers      Hybrid search was much better and significantly ch

# script_id: day_099_portfolio/profile_readme
"""Render a GitHub profile README (a public repo named after your username) from one dict."""
# Install: none (stdlib). Usage: python profile_readme.py [profile.json] > README.md
import json
import sys
from pathlib import Path

MAX_PINS = 6  # GitHub: up to six repositories and gists combined
PROFILE = {  # replace every value; every number must come from your own reports
    "name": "Your Name", "headline": "Software engineer building evaluated LLM systems.",
    "demo": "docs/demo.mp4", "post": {"title": "Exact ORB codes broke my vector search", "url": "#"},
    "pinned": [
        {"repo": "atlas", "url": "#", "proof": "one system, 5 tagged releases, eval report per release"},
        {"repo": "ticket-router", "url": "#", "proof": "routes any ticket queue; label accuracy in README"},
    ],
    "now": "Specialising in evals (see Day 100).",
}


def render_profile(p: dict) -> str:
    if len(p["pinned"]) > MAX_PINS:
        raise ValueError(f"GitHub pins at most {MAX_PINS}; you listed {len(p['pinned'])}")
    lines = [f"# Hi, I'm {p['name']}", "", p["headline"], "", "## Start here"]
    lines += [f"- [{x['repo']}]({x['url']}): {x['proof']}" for x in p["pinned"]]
    lines += ["", "## Writing", f"- [{p['post']['title']}]({p['post']['url']})"]
    return "\n".join(lines + ["", "## Currently", p["now"]])


if __name__ == "__main__":
    prof = json.loads(Path(sys.argv[1]).read_text()) if len(sys.argv) > 1 else PROFILE
    print(render_profile(prof))
    featured = [prof["demo"], prof["post"]["url"], prof["pinned"][0]["url"]]
    print("\nLinkedIn Featured order:", " -> ".join(featured), file=sys.stderr)

# Hi, I'm Your Name

Software engineer building evaluated LLM systems.

## Start here
- [atlas](#): one system, 5 tagged releases, eval report per release
- [ticket-router](#): routes any ticket queue; label accuracy in README

## Writing
- [Exact ORB codes broke my vector search](#)

## Currently
Specialising in evals (see Day 100).

LinkedIn Featured order: docs/demo.mp4 -> # -> #