devrel-origin 0.2.14__py3-none-any.whl

devrel_origin/project/config.py

@@ -0,0 +1,75 @@
+"""Load .devrel/config.toml into a typed ProjectConfig.
+
+The schema is intentionally narrow: project identity (required), model
+selection (optional with sensible defaults), and budget guardrails
+(optional). Future phases extend this with additional sections; the loader
+is permissive about unknown top-level keys.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+class ConfigError(Exception):
+    """Raised when config.toml is malformed or missing required fields."""
+
+
+@dataclass(frozen=True)
+class ProjectIdentity:
+    name: str
+    url: str = ""
+    github_repo: str | None = None
+
+
+@dataclass(frozen=True)
+class ModelConfig:
+    default: str = "claude-sonnet-4-6"
+    cheap: str = "claude-haiku-4-5-20251001"
+    opus_opt_in: bool = True
+
+
+@dataclass(frozen=True)
+class BudgetConfig:
+    monthly_usd: float = 100.0
+    warn_at_pct: int = 80
+
+
+@dataclass(frozen=True)
+class ProjectConfig:
+    project: ProjectIdentity
+    model: ModelConfig = field(default_factory=ModelConfig)
+    budget: BudgetConfig = field(default_factory=BudgetConfig)
+
+    @classmethod
+    def load(cls, config_file: Path) -> "ProjectConfig":
+        if not config_file.is_file():
+            raise ConfigError(f"config.toml not found at {config_file}")
+        with config_file.open("rb") as f:
+            raw = tomllib.load(f)
+        if "project" not in raw:
+            raise ConfigError("config.toml missing required [project] section")
+        proj = raw["project"]
+        if "name" not in proj or not proj["name"]:
+            raise ConfigError("config.toml missing required project.name")
+        identity = ProjectIdentity(
+            name=str(proj["name"]),
+            url=str(proj.get("url", "")),
+            github_repo=proj.get("github_repo"),
+        )
+        model_raw = raw.get("model") or {}
+        defaults = ModelConfig()
+        model = ModelConfig(
+            default=str(model_raw.get("default", defaults.default)),
+            cheap=str(model_raw.get("cheap", defaults.cheap)),
+            opus_opt_in=bool(model_raw.get("opus_opt_in", defaults.opus_opt_in)),
+        )
+        budget_raw = raw.get("budget") or {}
+        bdefaults = BudgetConfig()
+        budget = BudgetConfig(
+            monthly_usd=float(budget_raw.get("monthly_usd", bdefaults.monthly_usd)),
+            warn_at_pct=int(budget_raw.get("warn_at_pct", bdefaults.warn_at_pct)),
+        )
+        return cls(project=identity, model=model, budget=budget)

devrel_origin/project/cost_sink.py

@@ -0,0 +1,61 @@
+"""Build a cost-sink callable that inserts rows into the project state DB.
+
+Used by Atlas to wire LLMClient cost events into `.devrel/state.db`'s
+`costs` table. The pricing table lives in core/llm.py — we read it
+indirectly via the model names we receive.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from devrel_origin.core.llm import MODEL_COSTS
+
+
+def _compute_cost_usd(model: str, usage: dict[str, Any]) -> float:
+    pricing = MODEL_COSTS.get(model)
+    if pricing is None:
+        return 0.0
+    input_per_1m = pricing["input"]
+    output_per_1m = pricing["output"]
+    input_tokens = usage.get("input_tokens", 0)
+    output_tokens = usage.get("output_tokens", 0)
+    cache_read = usage.get("cache_read_input_tokens", 0)
+    cache_write = usage.get("cache_creation_input_tokens", 0)
+    # Cache pricing: read at 0.1×, write at 1.25× of input rate (Anthropic standard)
+    cost = (
+        (input_tokens / 1_000_000) * input_per_1m
+        + (output_tokens / 1_000_000) * output_per_1m
+        + (cache_read / 1_000_000) * input_per_1m * 0.1
+        + (cache_write / 1_000_000) * input_per_1m * 1.25
+    )
+    return round(cost, 6)
+
+
+def make_sqlite_sink(db_path: Path):
+    """Return an async ``(agent, model, usage) -> None`` callback that inserts
+    a row into the `costs` table at `db_path`."""
+
+    async def _sink(agent: str, model: str, usage: dict[str, Any]) -> None:
+        cost_usd = _compute_cost_usd(model, usage)
+        # SQLite is sync; we accept the brief blocking write inline.
+        with sqlite3.connect(db_path) as conn:
+            conn.execute(
+                "INSERT INTO costs (agent, model, input_tokens, output_tokens, "
+                "cache_read_tokens, cache_write_tokens, cost_usd) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (
+                    agent,
+                    model,
+                    usage.get("input_tokens", 0),
+                    usage.get("output_tokens", 0),
+                    usage.get("cache_read_input_tokens", 0),
+                    usage.get("cache_creation_input_tokens", 0),
+                    cost_usd,
+                ),
+            )
+            conn.commit()
+
+    return _sink

devrel_origin/project/init.py

@@ -0,0 +1,104 @@
+"""Idempotent .devrel/ scaffolder.
+
+`init_project(root, opts)` writes the .devrel/ directory tree, copies the
+template files, substitutes config placeholders, and initializes the state
+DB. Re-running on an existing project preserves user edits to committed
+files (config.toml, voice.md, style.md, slop-blocklist.md, .gitignore) —
+those are listed in `result.skipped`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from importlib.resources import files
+from pathlib import Path
+
+from devrel_origin.project.paths import ProjectPaths
+from devrel_origin.project.state import init_db
+
+_TEMPLATE_PKG = "devrel_origin.project.templates"
+
+# Files that are committed and must NEVER be overwritten on re-init.
+_COMMITTED_FILES = ("config.toml", "voice.md", "style.md", "slop-blocklist.md", ".gitignore")
+
+
+@dataclass(frozen=True)
+class InitOptions:
+    name: str
+    url: str = ""
+    github_repo: str | None = None
+    dry_run: bool = False
+
+
+@dataclass
+class InitResult:
+    created: list[str] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+    would_create: list[str] = field(default_factory=list)
+    dry_run: bool = False
+
+
+def _read_template(name: str) -> str:
+    return (files(_TEMPLATE_PKG) / name).read_text(encoding="utf-8")
+
+
+def _render_config_toml(opts: InitOptions) -> str:
+    body = _read_template("config.toml")
+    body = body.replace("PROJECT_NAME", opts.name)
+    body = body.replace("PROJECT_URL", opts.url)
+    if opts.github_repo:
+        body = body.replace('github_repo = "OWNER/REPO"', f'github_repo = "{opts.github_repo}"')
+    else:
+        body = body.replace(
+            'github_repo = "OWNER/REPO"',
+            "# github_repo =   # set if this product has a public repo",
+        )
+    return body
+
+
+def init_project(root: Path, opts: InitOptions) -> InitResult:
+    """Scaffold .devrel/ under `root`. Idempotent: preserves committed files
+    on re-run."""
+    paths = ProjectPaths.from_root(root)
+    result = InitResult(dry_run=opts.dry_run)
+
+    # The directory and subdirectories.
+    dirs = [paths.devrel_dir, paths.kb_dir, paths.deliverables_dir, paths.context_dir]
+    for d in dirs:
+        if d.is_dir():
+            result.skipped.append(d.name + "/")
+        else:
+            if opts.dry_run:
+                result.would_create.append(d.name + "/")
+            else:
+                d.mkdir(parents=True, exist_ok=True)
+                result.created.append(d.name + "/")
+
+    # File payloads keyed by destination path.
+    payloads: dict[Path, str] = {
+        paths.config_file: _render_config_toml(opts),
+        paths.voice_file: _read_template("voice.md"),
+        paths.style_file: _read_template("style.md"),
+        paths.slop_file: _read_template("slop-blocklist.md"),
+        paths.gitignore: _read_template("devrel.gitignore"),
+    }
+    for dest, body in payloads.items():
+        if dest.is_file():
+            result.skipped.append(dest.name)
+            continue
+        if opts.dry_run:
+            result.would_create.append(dest.name)
+        else:
+            dest.write_text(body, encoding="utf-8")
+            result.created.append(dest.name)
+
+    # State DB: idempotent (init_db preserves rows).
+    if opts.dry_run:
+        if not paths.state_db.is_file():
+            result.would_create.append("state.db")
+    else:
+        already = paths.state_db.is_file()
+        init_db(paths.state_db)
+        (result.skipped if already else result.created).append("state.db")
+
+    return result

devrel_origin/project/paths.py

@@ -0,0 +1,75 @@
+"""Project path discovery and structure.
+
+`find_devrel_root` walks up from a starting directory looking for the nearest
+ancestor containing a `.devrel/config.toml`. `ProjectPaths` is a frozen
+dataclass holding every derived path under `.devrel/`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+DEVREL_DIR_NAME = ".devrel"
+CONFIG_FILE_NAME = "config.toml"
+
+
+class ProjectNotFoundError(Exception):
+    """Raised when no .devrel/config.toml is found in cwd or any ancestor."""
+
+
+@dataclass(frozen=True)
+class ProjectPaths:
+    """All derived paths for a devrel-origin project."""
+
+    root: Path
+    devrel_dir: Path
+    config_file: Path
+    voice_file: Path
+    style_file: Path
+    slop_file: Path
+    kb_dir: Path
+    deliverables_dir: Path
+    context_dir: Path
+    state_db: Path
+    env_file: Path
+    gitignore: Path
+
+    @classmethod
+    def from_root(cls, root: Path) -> "ProjectPaths":
+        d = root / DEVREL_DIR_NAME
+        return cls(
+            root=root,
+            devrel_dir=d,
+            config_file=d / CONFIG_FILE_NAME,
+            voice_file=d / "voice.md",
+            style_file=d / "style.md",
+            slop_file=d / "slop-blocklist.md",
+            kb_dir=d / "kb",
+            deliverables_dir=d / "deliverables",
+            context_dir=d / "context",
+            state_db=d / "state.db",
+            env_file=d / ".env",
+            gitignore=d / ".gitignore",
+        )
+
+
+def find_devrel_root(start: Path | None = None) -> Path:
+    """Walk up from `start` (default: cwd) until a `.devrel/config.toml` is
+    found. Returns the project root (parent of `.devrel/`), resolved to an
+    absolute path.
+
+    Raises ProjectNotFoundError if no `.devrel/config.toml` is found before
+    the filesystem root.
+    """
+    cur = (start if start is not None else Path.cwd()).resolve()
+    while True:
+        candidate = cur / DEVREL_DIR_NAME / CONFIG_FILE_NAME
+        if candidate.is_file():
+            return cur
+        if cur.parent == cur:
+            raise ProjectNotFoundError(
+                "No .devrel/config.toml found in cwd or any ancestor. "
+                "Run `devrel init` from the project root."
+            )
+        cur = cur.parent

devrel_origin/project/state.py

@@ -0,0 +1,241 @@
+"""Project state DB: SQLite at .devrel/state.db.
+
+Stores: jobs (kind, status, started/finished timestamps), costs (per-call
+token + USD ledger consumed by BudgetGate), checkpoints (per-agent context
+snapshots, one per (agent, week_of) pair).
+
+In Phase 2 the DB is initialized empty by `devrel init`. Agents start
+writing to it in Phase 3 (quality pipeline cost recording) and beyond.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+SCHEMA_VERSION = 5
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS schema_meta (
+    version INTEGER PRIMARY KEY,
+    applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS jobs (
+    id TEXT PRIMARY KEY,
+    kind TEXT NOT NULL,
+    status TEXT NOT NULL CHECK (status IN ('queued', 'running', 'completed', 'failed')),
+    started_at TEXT,
+    finished_at TEXT,
+    error TEXT
+);
+
+CREATE TABLE IF NOT EXISTS costs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    job_id TEXT,
+    agent TEXT NOT NULL,
+    model TEXT NOT NULL,
+    input_tokens INTEGER NOT NULL DEFAULT 0,
+    output_tokens INTEGER NOT NULL DEFAULT 0,
+    cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+    cache_write_tokens INTEGER NOT NULL DEFAULT 0,
+    cost_usd REAL NOT NULL,
+    recorded_at TEXT NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY (job_id) REFERENCES jobs(id) ON DELETE SET NULL
+);
+
+CREATE TABLE IF NOT EXISTS checkpoints (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    agent TEXT NOT NULL,
+    week_of TEXT NOT NULL,
+    payload_json TEXT NOT NULL,
+    saved_at TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE (agent, week_of)
+);
+
+CREATE TABLE IF NOT EXISTS analytics_reports (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    period_start TEXT NOT NULL,
+    period_end TEXT NOT NULL,
+    report_json TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_analytics_reports_period
+    ON analytics_reports(period_end);
+
+CREATE TABLE IF NOT EXISTS metric_history (
+    content_id TEXT NOT NULL,
+    period_end TEXT NOT NULL,
+    primary_metric REAL NOT NULL,
+    metric_name TEXT NOT NULL,
+    content_type TEXT NOT NULL,
+    PRIMARY KEY (content_id, period_end)
+);
+
+CREATE INDEX IF NOT EXISTS idx_metric_history_content_period
+    ON metric_history(content_id, period_end DESC);
+
+CREATE TABLE IF NOT EXISTS analytics_recommendations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    report_id INTEGER NOT NULL,
+    period_end TEXT NOT NULL,
+    action TEXT NOT NULL,
+    target TEXT NOT NULL,
+    target_type TEXT NOT NULL,
+    rationale TEXT NOT NULL,
+    confidence REAL NOT NULL,
+    source_ids_json TEXT NOT NULL DEFAULT '[]',
+    evidence_json TEXT NOT NULL DEFAULT '[]',
+    first_seen_period TEXT NOT NULL,
+    applied_at TEXT,
+    FOREIGN KEY (report_id) REFERENCES analytics_reports(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_analytics_recommendations_period
+    ON analytics_recommendations(period_end);
+
+CREATE INDEX IF NOT EXISTS idx_analytics_recommendations_action_open
+    ON analytics_recommendations(action, applied_at);
+
+CREATE TABLE IF NOT EXISTS seo_keyword_metrics (
+    keyword TEXT NOT NULL,
+    page_url TEXT NOT NULL,
+    period_end TEXT NOT NULL,
+    position REAL,
+    ctr REAL,
+    impressions INTEGER,
+    clicks INTEGER,
+    PRIMARY KEY (keyword, page_url, period_end)
+);
+
+CREATE INDEX IF NOT EXISTS idx_seo_keyword_metrics_period
+    ON seo_keyword_metrics(period_end DESC);
+
+CREATE TABLE IF NOT EXISTS seo_page_profiles (
+    page_url TEXT NOT NULL,
+    period_end TEXT NOT NULL,
+    title_len INTEGER,
+    meta_len INTEGER,
+    h1_count INTEGER,
+    word_count INTEGER,
+    has_schema INTEGER,
+    schema_types_json TEXT,
+    internal_links INTEGER,
+    inp_ms INTEGER,
+    lcp_ms INTEGER,
+    redirect_chain_len INTEGER,
+    crawled_at TEXT NOT NULL,
+    PRIMARY KEY (page_url, period_end)
+);
+
+CREATE TABLE IF NOT EXISTS geo_visibility (
+    prompt_id TEXT NOT NULL,
+    engine TEXT NOT NULL,
+    period_end TEXT NOT NULL,
+    is_mentioned INTEGER,
+    mention_type TEXT,
+    position_score INTEGER,
+    citation_share REAL,
+    quality_score INTEGER,
+    response_path TEXT,
+    PRIMARY KEY (prompt_id, engine, period_end)
+);
+
+CREATE INDEX IF NOT EXISTS idx_geo_visibility_engine_period
+    ON geo_visibility(engine, period_end DESC);
+
+CREATE TABLE IF NOT EXISTS cro_funnel_metrics (
+    funnel_id TEXT NOT NULL,
+    step_index INTEGER NOT NULL,
+    period_end TEXT NOT NULL,
+    conversion_rate REAL,
+    sample_size INTEGER,
+    segment_breakdown_json TEXT,
+    PRIMARY KEY (funnel_id, step_index, period_end)
+);
+
+CREATE INDEX IF NOT EXISTS idx_cro_funnel_period
+    ON cro_funnel_metrics(funnel_id, period_end DESC);
+"""
+
+
+def _migrate_to_v5(conn: sqlite3.Connection) -> None:
+    """Add pillar + target_kind columns to analytics_recommendations if absent.
+
+    SQLite's ALTER TABLE ADD COLUMN is non-idempotent: running twice raises
+    OperationalError. We probe PRAGMA table_info first.
+    """
+    cur = conn.execute("PRAGMA table_info(analytics_recommendations)")
+    cols = {row[1] for row in cur.fetchall()}
+    if "pillar" not in cols:
+        conn.execute(
+            "ALTER TABLE analytics_recommendations ADD COLUMN pillar TEXT NOT NULL DEFAULT 'argus'"
+        )
+    if "target_kind" not in cols:
+        conn.execute(
+            "ALTER TABLE analytics_recommendations "
+            "ADD COLUMN target_kind TEXT NOT NULL DEFAULT 'content_id'"
+        )
+    # Backfill any rows that pre-date these columns. DEFAULT covers fresh
+    # inserts but old rows from a partial v4 db benefit from explicit values.
+    conn.execute(
+        "UPDATE analytics_recommendations "
+        "SET pillar = COALESCE(NULLIF(pillar, ''), 'argus'), "
+        "    target_kind = COALESCE(NULLIF(target_kind, ''), 'content_id') "
+        "WHERE pillar IS NULL OR pillar = '' "
+        "   OR target_kind IS NULL OR target_kind = ''"
+    )
+    # Indexes that reference the newly-added columns. Created here (not in
+    # SCHEMA) because SCHEMA's executescript runs before the ALTER TABLEs above.
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_recs_pillar_period "
+        "ON analytics_recommendations(pillar, first_seen_period DESC)"
+    )
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_recs_target "
+        "ON analytics_recommendations(target_kind, target)"
+    )
+
+
+def init_db(db_path: Path) -> None:
+    """Create the DB file and apply the schema. Idempotent: preserves
+    existing data and bumps schema_meta to the current SCHEMA_VERSION."""
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    with sqlite3.connect(db_path) as conn:
+        conn.executescript(SCHEMA)
+        _migrate_to_v5(conn)
+        conn.execute(
+            "INSERT OR REPLACE INTO schema_meta (version, applied_at) VALUES (?, datetime('now'))",
+            (SCHEMA_VERSION,),
+        )
+        conn.commit()
+
+
+def get_schema_version(db_path: Path) -> int | None:
+    """Return the current schema version, or None if the DB is missing /
+    has no schema_meta table."""
+    if not db_path.is_file():
+        return None
+    with sqlite3.connect(db_path) as conn:
+        try:
+            cur = conn.execute("SELECT MAX(version) FROM schema_meta")
+        except sqlite3.OperationalError:
+            return None
+        row = cur.fetchone()
+        return row[0] if row else None
+
+
+@contextmanager
+def open_db(db_path: Path) -> Iterator[sqlite3.Connection]:
+    """Context manager yielding a connection with row_factory set and
+    foreign-key enforcement enabled."""
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    try:
+        yield conn
+    finally:
+        conn.close()

devrel_origin/project/templates/__init__.py

@@ -0,0 +1,4 @@
+"""Static template files copied into .devrel/ on `devrel init`.
+
+Access via `importlib.resources.files("devrel_origin.project.templates")`.
+"""

devrel_origin/project/templates/config.toml

@@ -0,0 +1,24 @@
+# devrel-origin project config. Commit this file — it encodes editorial
+# contract along with voice.md / style.md / slop-blocklist.md.
+
+# Project identity. Replace placeholders with real values; the github_repo
+# is optional (set to a comment-out or null if there isn't one).
+[project]
+name = "PROJECT_NAME"
+url = "PROJECT_URL"
+github_repo = "OWNER/REPO"
+
+# Model selection. Sonnet for primary work; Haiku for cheap quality stages
+# (slop lint, persona scoring, readability scoring); Opus opt-in via
+# `--model opus` on individual commands.
+[model]
+default = "claude-sonnet-4-6"
+cheap = "claude-haiku-4-5-20251001"
+opus_opt_in = true
+
+# Budget guardrails. monthly_usd is the cap; warn_at_pct is the threshold
+# at which `devrel doctor` and `devrel run` print a warning. Set
+# monthly_usd to 0 to disable the cap entirely.
+[budget]
+monthly_usd = 100.0
+warn_at_pct = 80

devrel_origin/project/templates/devrel.gitignore

@@ -0,0 +1,10 @@
+# Auto-managed by `devrel init`. Edit only if you know what you're doing.
+# Generated outputs and runtime state are gitignored; the editorial
+# contract files (config.toml, voice.md, style.md, slop-blocklist.md) are
+# intended to be committed.
+
+kb/
+deliverables/
+context/
+state.db
+.env

devrel_origin/project/templates/slop-blocklist.md

@@ -0,0 +1,45 @@
+# Anti-slop blocklist
+
+Words, phrases, and patterns that mark text as AI-written. The quality pipeline rewrites any content that contains a hit; on second failure it aborts loud with a report listing offenders.
+
+One entry per line. Lines starting with `#` are comments and ignored. Matching is case-insensitive against word boundaries.
+
+## Hedge words and filler
+perhaps
+furthermore
+moreover
+in conclusion
+in today's
+in this fast-paced world
+
+## AI tells
+delve
+delves
+tapestry
+seamless
+seamlessly
+unleash
+unleashing
+revolutionize
+revolutionary
+empower
+empowering
+groundbreaking
+
+## Generic CTAs
+learn more
+discover more
+get started today
+contact us today
+
+## Listicle filler
+in this article we will
+this article will explore
+in this post
+
+## Empty intensifiers
+truly
+incredibly
+extremely
+very
+really

devrel_origin/project/templates/style.md

@@ -0,0 +1,24 @@
+# House style
+
+Structural and per-content-type rules. Short rules; expand only where the rule isn't obvious from the rule itself.
+
+## Structural rules
+
+- Sentence-case headings (not Title Case).
+- One H1 per document (the title).
+- Code blocks always have language tags: ```python, ```bash, etc.
+- No trailing whitespace.
+- Reference-style links only when the same URL repeats.
+- No emojis in headings; sparingly in body.
+
+## Per-content-type targets
+
+| Content type | Flesch-Kincaid | Mean sentence length | Jargon density |
+|---|---|---|---|
+| Tutorial | 50-65 | 12-18 words | medium |
+| Blog post | 55-70 | 12-20 words | low-medium |
+| Landing page | 60-75 | 10-15 words | low |
+| Cold email | 65-80 | 10-14 words | low |
+| Battle card | 45-60 | 12-18 words | medium-high |
+
+Targets are guidance, not pass/fail gates. The readability check in the quality pipeline flags drift greater than ±10 points from the Flesch-Kincaid target.