apsimo 1.3.0__py3-none-any.whl

apsimo/feeds/example-feed.yaml

@@ -0,0 +1,77 @@
+# Example feed spec — everything a feed instance needs, in one file.
+# Create with:  colony feeds create example-feed.yaml
+# Only name/topic/destination/cadence + one source adapter are required.
+
+name: rust-embedded
+title: Rust Embedded Feed
+topic: >-
+  Rust on microcontrollers and embedded targets: new HAL crates, RTIC and
+  Embassy releases, async-on-bare-metal techniques, and real hardware
+  benchmarks. The goal is catching tools and techniques worth adopting.
+
+audience: personal            # personal | group (group adds community-input handling)
+
+destination:
+  kind: deliver               # deliver | command | file
+  deliver: origin             # harness delivery target: origin, platform:chat_id, ...
+  # kind: command             # pipe the brief to a shell command instead:
+  # send_command: "python3 ~/.hermes/scripts/my-group-send.py 42"
+  # read_back: 'read_chat chat="My Group" limit=100'   # group community input
+  # owner_deliver: origin     # where discovery proposals go (defaults to deliver)
+
+# llm:                        # optional but recommended: pin so global provider
+#   provider: my-provider     # changes can never drift-skip these jobs
+#   model: my/model
+
+cadence:
+  collect: "every 240m"
+  distill: "every 120m"
+  # digest: "0 8 * * *"       # optional daily rollup
+  # alerts: "every 60m"       # optional between-brief P0 pushes
+  # discovery: "every 480m"   # optional new-source research agent
+
+sources:
+  x_searches:
+    - '(embassy OR RTIC OR "embedded-hal") rust'
+  key_accounts: [rustembedded]
+  github_search: "embedded rust hal OR rtic OR embassy"
+  github_keywords: [embedded, hal, rtic, embassy, no_std]
+  hf_keywords: []             # empty = adapter disabled
+  forum_urls: []              # Discourse forums (fetched as <url>.json)
+  forum_title_keywords: []
+  arxiv:
+    categories: [cs.SE]
+    query_terms: [embedded, "real-time"]
+    keywords: [embedded, microcontroller]
+  rss:
+    - {name: rust-blog, url: "https://blog.rust-lang.org/feed.xml"}
+
+registry:                     # tiered source registry used by promotion rules
+  - name: rust-embedded-wg
+    handle: "@rustembedded"
+    category: working_group
+    weight: P0
+    reason: Official embedded WG — every announcement matters.
+    platforms: [x]
+
+scoring:
+  keyword_categories:         # generic keyword->points buckets
+    - {keywords: [rtic, embassy, embedded-hal, no_std], points: 15}
+    - {keywords: [benchmark, latency, interrupt], points: 10}
+  thresholds: {p0: 40, p1: 25, p2: 15}
+
+brief:
+  framing: "What changes for embedded Rust projects because of this?"
+  standard_cap: 5
+  # context_files:            # extra files the distill agent reads if present
+  #   - {path: ~/.hermes/data/my-extra-context.json, label: crate download stats}
+  # extra_instructions: ""    # freeform text appended to the distill prompt
+
+privacy:
+  forbidden:
+    - "private infrastructure details (hardware counts, cluster topology, hostnames, addresses)"
+    - "names of the operator, their contacts, or internal agent/system codenames"
+  # aliases: [DGX Spark]      # allowed public product names
+  # note: ""                  # extra privacy instruction
+
+learning_loop: true           # log unknown-source promotions for registry evolution

apsimo/feeds/hermes_cron.py

@@ -0,0 +1,126 @@
+"""Harness (Hermes) cron integration for feed instances.
+
+All scheduling goes through the ``hermes cron`` CLI; the one thing the CLI
+cannot do — pinning a job to an explicit provider/model so global inference
+config drift can never silently skip a feed job — is done by editing the
+scheduler's jobs.json directly (with a timestamped backup first).
+
+Paths/binaries are overridable via env for non-standard installs:
+  COLONY_HERMES_BIN   hermes CLI (default: ``hermes`` on PATH, then the
+                      conventional venv location)
+  COLONY_HERMES_HOME  harness home (default ~/.hermes)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import time
+
+
+def hermes_home() -> str:
+    return os.path.expanduser(os.environ.get("COLONY_HERMES_HOME", "~/.hermes"))
+
+
+def hermes_bin() -> str:
+    env = os.environ.get("COLONY_HERMES_BIN")
+    if env:
+        return os.path.expanduser(env)
+    on_path = shutil.which("hermes")
+    if on_path:
+        return on_path
+    conventional = os.path.join(hermes_home(), "hermes-agent/venv/bin/hermes")
+    return conventional if os.path.exists(conventional) else "hermes"
+
+
+def jobs_json_path() -> str:
+    return os.path.join(hermes_home(), "cron/jobs.json")
+
+
+def scripts_dir() -> str:
+    return os.path.join(hermes_home(), "scripts")
+
+
+def _run(args: list[str], timeout: int = 60) -> str:
+    proc = subprocess.run([hermes_bin(), *args], capture_output=True, text=True,
+                          timeout=timeout)
+    if proc.returncode != 0:
+        raise RuntimeError(f"hermes {' '.join(args[:2])} failed: "
+                           f"{proc.stderr.strip() or proc.stdout.strip()}")
+    return proc.stdout
+
+
+def _load_jobs() -> list[dict]:
+    try:
+        with open(jobs_json_path(), encoding="utf-8") as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        return []
+    return data.get("jobs", data) if isinstance(data, dict) else data
+
+
+def find_jobs(name_prefix: str) -> list[dict]:
+    return [j for j in _load_jobs()
+            if isinstance(j, dict) and (j.get("name") or "").startswith(name_prefix)]
+
+
+def create_job(name: str, schedule: str, *, prompt: str | None = None,
+               script: str | None = None, no_agent: bool = False,
+               deliver: str = "local") -> str:
+    """Create a job and return its id (resolved by unique name lookup)."""
+    if find_jobs(name):
+        raise RuntimeError(f"a cron job named {name!r} already exists")
+    args = ["cron", "create", schedule, "--name", name, "--deliver", deliver]
+    if script:
+        args += ["--script", script]
+    if no_agent:
+        args += ["--no-agent"]
+    if prompt is not None:
+        args.insert(3, prompt)  # positional prompt right after the schedule
+    _run(args)
+    jobs = find_jobs(name)
+    if len(jobs) != 1:
+        raise RuntimeError(f"created job {name!r} but found {len(jobs)} matches in jobs.json")
+    return jobs[0]["id"]
+
+
+def pin_model(job_ids: list[str], provider: str, model: str) -> None:
+    """Pin jobs to an explicit provider/model in jobs.json (backup first)."""
+    if not (provider and model):
+        return
+    path = jobs_json_path()
+    shutil.copy2(path, f"{path}.bak-feeds-{int(time.time())}")
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    jobs = data.get("jobs", data) if isinstance(data, dict) else data
+    hit = 0
+    for j in jobs:
+        if isinstance(j, dict) and j.get("id") in job_ids:
+            j["provider"] = provider
+            j["model"] = model
+            hit += 1
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+    if hit != len(job_ids):
+        raise RuntimeError(f"pinned {hit}/{len(job_ids)} jobs — jobs.json out of sync")
+
+
+def remove_job(job_id: str) -> None:
+    _run(["cron", "remove", job_id])
+
+
+def pause_job(job_id: str) -> None:
+    _run(["cron", "pause", job_id])
+
+
+def resume_job(job_id: str) -> None:
+    _run(["cron", "resume", job_id])
+
+
+def run_job_detached(job_id: str) -> None:
+    """Trigger a run without blocking: agent jobs can run for many minutes."""
+    subprocess.Popen([hermes_bin(), "cron", "run", job_id],
+                     stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                     start_new_session=True)

apsimo/feeds/manager.py

@@ -0,0 +1,235 @@
+"""Feed instance lifecycle: create, list, status, pause/resume, run, delete.
+
+Everything a feed needs is derived from its spec at create time:
+
+  data dir     <data_root>/{spec.yaml,instance.json,config.json,queue.json,seen.db,briefs/}
+  engine       one shared copy of engine.py in the harness scripts dir
+  shims        tiny generated per-instance scripts that point the engine at
+               this instance's config (the scheduler's --script mechanism has
+               no argument passing, so the shim IS the argument)
+  cron jobs    "[feeds:<name>] <stage>" jobs, agent jobs pinned to the spec's
+               provider/model so global config drift can never skip them
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+
+from . import hermes_cron as hc
+from . import template
+from .spec import FeedSpec
+
+ENGINE_BASENAME = "colony-feed-engine.py"
+JOB_PREFIX = "[feeds:{name}]"
+
+
+def _prefix(name: str) -> str:
+    return JOB_PREFIX.format(name=name)
+
+
+def _instance_path(name: str) -> str:
+    return os.path.expanduser(f"~/.hermes/data/feeds/{name}/instance.json")
+
+
+def _load_instance(name: str) -> dict:
+    try:
+        with open(_instance_path(name), encoding="utf-8") as f:
+            return json.load(f)
+    except FileNotFoundError:
+        raise SystemExit(f"no feed instance named {name!r} (see: colony feeds list)")
+
+
+def _engine_src() -> str:
+    return os.path.join(os.path.dirname(os.path.abspath(__file__)), "engine.py")
+
+
+def _install_engine() -> str:
+    dst = os.path.join(hc.scripts_dir(), ENGINE_BASENAME)
+    os.makedirs(hc.scripts_dir(), exist_ok=True)
+    shutil.copy2(_engine_src(), dst)
+    return dst
+
+
+def _write_shim(name: str, stage: str, config_path: str) -> str:
+    shim = os.path.join(hc.scripts_dir(), f"feeds-{name}-{stage}.py")
+    with open(shim, "w", encoding="utf-8") as f:
+        f.write(f'''#!/usr/bin/env python3
+# Auto-generated by `colony feeds` for instance {name!r} — do not edit.
+import os, runpy
+os.environ.setdefault("COLONY_FEED_CONFIG", {config_path!r})
+os.environ.setdefault("COLONY_FEED_STAGE", {stage!r})
+runpy.run_path(os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                            {ENGINE_BASENAME!r}), run_name="__main__")
+''')
+    return shim
+
+
+# --------------------------------------------------------------------- create
+def create(spec_path: str, dry_run: bool = False) -> dict:
+    spec = FeedSpec.load(spec_path)
+    root = spec.data_root()
+    if os.path.exists(_instance_path(spec.name)):
+        raise SystemExit(f"feed {spec.name!r} already exists — delete it first or pick a new name")
+
+    prompts = {"distill": template.render_distill(spec)}
+    if spec.cadence.get("digest"):
+        prompts["digest"] = template.render_digest(spec)
+    if spec.cadence.get("discovery"):
+        prompts["discovery"] = template.render_discovery(spec)
+    if dry_run:
+        return {"name": spec.name, "root": root, "prompts": prompts}
+
+    os.makedirs(spec.briefs_dir, exist_ok=True)
+    os.makedirs(root, exist_ok=True)
+    shutil.copy2(os.path.expanduser(spec_path), os.path.join(root, "spec" + os.path.splitext(spec_path)[1]))
+
+    # Engine config: an explicit storage.config_path means an external
+    # (possibly hand-maintained / mutated-by-other-tools) config owns the
+    # collector; otherwise render one from the spec.
+    config_path = spec.storage.get("config_path")
+    if config_path:
+        config_path = os.path.expanduser(config_path)
+        if not os.path.exists(config_path):
+            raise SystemExit(f"storage.config_path {config_path} does not exist")
+    else:
+        config_path = os.path.join(root, "config.json")
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(spec.engine_config(), f, indent=2)
+
+    _install_engine()
+    shims = {"collect": _write_shim(spec.name, "collect", config_path)}
+    if spec.cadence.get("alerts"):
+        shims["alert"] = _write_shim(spec.name, "alert", config_path)
+
+    deliver_agent = (spec.destination.get("deliver", "local")
+                     if spec.destination.get("kind") == "deliver" else "local")
+    owner_deliver = spec.destination.get("owner_deliver", deliver_agent)
+
+    jobs: dict[str, str] = {}
+    try:
+        jobs["collect"] = hc.create_job(
+            f"{_prefix(spec.name)} collect", spec.cadence["collect"],
+            script=os.path.basename(shims["collect"]), no_agent=True)
+        jobs["distill"] = hc.create_job(
+            f"{_prefix(spec.name)} distill", spec.cadence["distill"],
+            prompt=prompts["distill"], deliver=deliver_agent)
+        if spec.cadence.get("digest"):
+            jobs["digest"] = hc.create_job(
+                f"{_prefix(spec.name)} digest", spec.cadence["digest"],
+                prompt=prompts["digest"], deliver=deliver_agent)
+        if spec.cadence.get("alerts"):
+            jobs["alert"] = hc.create_job(
+                f"{_prefix(spec.name)} alert", spec.cadence["alerts"],
+                script=os.path.basename(shims["alert"]), no_agent=True,
+                deliver=deliver_agent)
+        if spec.cadence.get("discovery"):
+            jobs["discovery"] = hc.create_job(
+                f"{_prefix(spec.name)} discovery", spec.cadence["discovery"],
+                prompt=prompts["discovery"], deliver=owner_deliver)
+    except Exception:
+        for jid in jobs.values():  # roll back partial registration
+            try:
+                hc.remove_job(jid)
+            except Exception:
+                pass
+        raise
+
+    agent_jobs = [jid for stage, jid in jobs.items()
+                  if stage in ("distill", "digest", "discovery")]
+    hc.pin_model(agent_jobs, spec.llm.get("provider", ""), spec.llm.get("model", ""))
+
+    instance = {"name": spec.name, "title": spec.title, "created_at": int(time.time()),
+                "spec_path": os.path.abspath(os.path.expanduser(spec_path)),
+                "config_path": config_path, "jobs": jobs, "shims": shims,
+                "paused": False}
+    with open(_instance_path(spec.name), "w", encoding="utf-8") as f:
+        json.dump(instance, f, indent=2)
+    return instance
+
+
+# ----------------------------------------------------------------- lifecycle
+def list_instances() -> list[dict]:
+    base = os.path.expanduser("~/.hermes/data/feeds")
+    out = []
+    if not os.path.isdir(base):
+        return out
+    for name in sorted(os.listdir(base)):
+        p = _instance_path(name)
+        if os.path.exists(p):
+            with open(p, encoding="utf-8") as f:
+                out.append(json.load(f))
+    return out
+
+
+def status(name: str) -> dict:
+    inst = _load_instance(name)
+    spec = FeedSpec.load(inst["spec_path"]) if os.path.exists(inst["spec_path"]) else None
+    info = dict(inst)
+    if spec and os.path.exists(spec.queue_path):
+        with open(spec.queue_path, encoding="utf-8") as f:
+            q = json.load(f)
+        info["queue"] = {"collected_at": q.get("collected_at"),
+                         "total_items": q.get("total_items")}
+    if spec and os.path.isdir(spec.briefs_dir):
+        briefs = sorted(os.listdir(spec.briefs_dir))
+        info["latest_brief"] = briefs[-1] if briefs else None
+    live = {j["id"]: j for j in hc.find_jobs(_prefix(name))}
+    info["jobs_live"] = {stage: (jid in live) for stage, jid in inst["jobs"].items()}
+    return info
+
+
+def pause(name: str) -> None:
+    inst = _load_instance(name)
+    for jid in inst["jobs"].values():
+        hc.pause_job(jid)
+    inst["paused"] = True
+    with open(_instance_path(name), "w", encoding="utf-8") as f:
+        json.dump(inst, f, indent=2)
+
+
+def resume(name: str) -> None:
+    inst = _load_instance(name)
+    for jid in inst["jobs"].values():
+        hc.resume_job(jid)
+    inst["paused"] = False
+    with open(_instance_path(name), "w", encoding="utf-8") as f:
+        json.dump(inst, f, indent=2)
+
+
+def run(name: str, stage: str) -> None:
+    """Run one stage now. collect/alert run synchronously (output streams);
+    agent stages are triggered detached because they can run for minutes."""
+    inst = _load_instance(name)
+    if stage in ("collect", "alert"):
+        shim = inst["shims"].get(stage) or inst["shims"]["collect"]
+        env = dict(os.environ, COLONY_FEED_STAGE=stage)
+        subprocess.run([sys.executable, shim], env=env, check=True)
+        return
+    jid = inst["jobs"].get(stage)
+    if not jid:
+        raise SystemExit(f"feed {name!r} has no {stage!r} job")
+    hc.run_job_detached(jid)
+    print(f"triggered {stage} (job {jid}) — check the scheduler's output dir for results")
+
+
+def delete(name: str, purge: bool = False) -> None:
+    inst = _load_instance(name)
+    for jid in inst["jobs"].values():
+        try:
+            hc.remove_job(jid)
+        except Exception as e:
+            print(f"warning: could not remove job {jid}: {e}", file=sys.stderr)
+    for shim in inst.get("shims", {}).values():
+        try:
+            os.remove(shim)
+        except FileNotFoundError:
+            pass
+    if purge:
+        shutil.rmtree(os.path.dirname(_instance_path(name)), ignore_errors=True)
+    else:
+        os.remove(_instance_path(name))

apsimo/feeds/spec.py

@@ -0,0 +1,250 @@
+"""Feed instance spec: schema, defaults, validation.
+
+A spec is a plain YAML (or JSON) mapping.  Everything that distinguishes one
+feed from another lives here — topic, sources, scoring, cadence, destination,
+privacy — so an instance is fully reproducible from its spec file.
+
+Minimal spec::
+
+    name: rust-embedded
+    title: Rust Embedded Feed
+    topic: Rust on microcontrollers — new crates, HALs, RTIC releases.
+    destination: {kind: deliver, deliver: origin}
+    cadence: {collect: "every 240m", distill: "every 120m"}
+    sources:
+      github_search: "embedded rust hal OR rtic"
+      arxiv: {categories: [cs.SE], keywords: [embedded]}
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]{1,63}$")
+
+DESTINATION_KINDS = ("command", "deliver", "file")
+
+#: Adapter keys under ``sources:`` — at least one must be configured.
+ADAPTER_KEYS = ("x_searches", "hf_keywords", "github_search", "forum_urls", "arxiv", "rss")
+
+DEFAULT_FRAMING = "What changes for us because of this?"
+
+DEFAULT_SCORING = {
+    "account_whitelist": 10,
+    "engagement": {"per_100_likes": 1, "per_1000_likes": 2, "max": 10},
+    "human_curated": 20,
+    "benchmark_numbers": 15,
+    "code_release": 10,
+    "open_weights": 10,
+    "thresholds": {"p0": 50, "p1": 35, "p2": 20},
+}
+
+DEFAULT_PRIVACY_FORBIDDEN = [
+    "private infrastructure details (hardware counts, cluster topology, hostnames, addresses)",
+    "names of the operator, their contacts, or internal agent/system codenames",
+]
+
+
+class SpecError(ValueError):
+    """Raised when a spec fails validation; ``.errors`` lists every problem."""
+
+    def __init__(self, errors: list[str]):
+        self.errors = errors
+        super().__init__("invalid feed spec:\n  - " + "\n  - ".join(errors))
+
+
+@dataclass
+class FeedSpec:
+    """Validated, defaulted view over a raw spec mapping."""
+
+    raw: dict = field(repr=False)
+    name: str = ""
+    title: str = ""
+    topic: str = ""
+    audience: str = "personal"          # personal | group
+    destination: dict = field(default_factory=dict)
+    llm: dict = field(default_factory=dict)          # {provider, model} pin
+    cadence: dict = field(default_factory=dict)
+    storage: dict = field(default_factory=dict)      # per-path overrides
+    sources: dict = field(default_factory=dict)
+    registry: list = field(default_factory=list)     # tiered source registry
+    scoring: dict = field(default_factory=dict)
+    brief: dict = field(default_factory=dict)
+    privacy: dict = field(default_factory=dict)
+    learning_loop: bool = True
+    budget: dict = field(default_factory=dict)
+
+    # ------------------------------------------------------------------ load
+    @classmethod
+    def load(cls, path: str) -> "FeedSpec":
+        with open(os.path.expanduser(path), encoding="utf-8") as f:
+            text = f.read()
+        if path.endswith(".json"):
+            raw = json.loads(text)
+        else:
+            try:
+                import yaml  # type: ignore
+            except ImportError as exc:  # pragma: no cover
+                raise SpecError([f"PyYAML unavailable ({exc}); use a .json spec"]) from exc
+            raw = yaml.safe_load(text)
+        if not isinstance(raw, dict):
+            raise SpecError(["spec root must be a mapping"])
+        return cls.from_dict(raw)
+
+    @classmethod
+    def from_dict(cls, raw: dict) -> "FeedSpec":
+        spec = cls(raw=raw)
+        errors: list[str] = []
+
+        spec.name = str(raw.get("name", "")).strip()
+        if not _SLUG_RE.match(spec.name):
+            errors.append("name: required kebab-case slug, e.g. 'ai-inference'")
+        spec.title = str(raw.get("title") or spec.name.replace("-", " ").title())
+        spec.topic = str(raw.get("topic", "")).strip()
+        if not spec.topic:
+            errors.append("topic: required — one paragraph describing what this feed tracks and why")
+
+        spec.audience = raw.get("audience", "personal")
+        if spec.audience not in ("personal", "group"):
+            errors.append("audience: must be 'personal' or 'group'")
+
+        dest = raw.get("destination") or {}
+        kind = dest.get("kind")
+        if kind not in DESTINATION_KINDS:
+            errors.append(f"destination.kind: required, one of {DESTINATION_KINDS}")
+        elif kind == "command" and not dest.get("send_command"):
+            errors.append("destination.send_command: required for kind=command "
+                          "(shell command the brief is piped to)")
+        elif kind == "deliver" and not dest.get("deliver"):
+            errors.append("destination.deliver: required for kind=deliver "
+                          "(harness delivery target, e.g. 'origin' or 'platform:chat_id')")
+        spec.destination = dest
+
+        cadence = raw.get("cadence") or {}
+        for req in ("collect", "distill"):
+            if not cadence.get(req):
+                errors.append(f"cadence.{req}: required (harness schedule string, e.g. 'every 120m')")
+        spec.cadence = cadence
+
+        sources = raw.get("sources") or {}
+        if not any(sources.get(k) for k in ADAPTER_KEYS):
+            errors.append(f"sources: at least one adapter of {ADAPTER_KEYS} must be configured")
+        spec.sources = sources
+
+        spec.registry = raw.get("registry") or []
+        for i, entry in enumerate(spec.registry):
+            if not isinstance(entry, dict) or not entry.get("name"):
+                errors.append(f"registry[{i}]: each entry needs at least a 'name'")
+            elif entry.get("weight", "P1") not in ("P0", "P1", "P2"):
+                errors.append(f"registry[{i}] ({entry.get('name')}): weight must be P0/P1/P2")
+
+        spec.scoring = _merged(DEFAULT_SCORING, raw.get("scoring") or {})
+        spec.llm = raw.get("llm") or {}
+        spec.storage = raw.get("storage") or {}
+        spec.brief = raw.get("brief") or {}
+        spec.brief.setdefault("framing", DEFAULT_FRAMING)
+        spec.brief.setdefault("standard_cap", 5)
+        spec.privacy = raw.get("privacy") or {}
+        spec.privacy.setdefault("forbidden", list(DEFAULT_PRIVACY_FORBIDDEN))
+        spec.learning_loop = bool(raw.get("learning_loop", True))
+        spec.budget = raw.get("budget") or {}
+
+        if errors:
+            raise SpecError(errors)
+        return spec
+
+    # ------------------------------------------------------------- storage
+    def data_root(self, base: str = "~/.hermes/data/feeds") -> str:
+        root = self.storage.get("root") or f"{base}/{self.name}"
+        return os.path.expanduser(root)
+
+    def path(self, key: str, default_name: str) -> str:
+        """Resolve a storage path, honouring per-key spec overrides."""
+        override = self.storage.get(key)
+        if override:
+            return os.path.expanduser(override)
+        return os.path.join(self.data_root(), default_name)
+
+    @property
+    def queue_path(self) -> str:
+        return self.path("queue_path", "queue.json")
+
+    @property
+    def seen_db(self) -> str:
+        return self.path("seen_db", "seen.db")
+
+    @property
+    def briefs_dir(self) -> str:
+        return self.path("briefs_dir", "briefs")
+
+    @property
+    def alert_path(self) -> str:
+        return self.path("alert_path", "alert.json")
+
+    @property
+    def deltas_log(self) -> str:
+        return self.path("deltas_log", "briefs/_registry_deltas.log")
+
+    # -------------------------------------------------------- engine config
+    def engine_config(self) -> dict[str, Any]:
+        """Render the self-contained collector-engine config for this feed."""
+        s = self.sources
+        arxiv = s.get("arxiv") or {}
+        sc = self.scoring
+        cfg: dict[str, Any] = {
+            "feed_name": self.name,
+            "queue_path": self.queue_path,
+            "seen_db": self.seen_db,
+            "alert_path": self.alert_path,
+            # adapters (empty list / missing = adapter disabled)
+            "x_searches": s.get("x_searches") or [],
+            "x_results_per_query": s.get("x_results_per_query", 15),
+            "key_accounts": s.get("key_accounts") or [],
+            "hf_keywords": s.get("hf_keywords") or [],
+            "github_search": s.get("github_search") or "",
+            "github_keywords": s.get("github_keywords") or [],
+            "forum_urls": s.get("forum_urls") or [],
+            "forum_title_keywords": s.get("forum_title_keywords") or [],
+            "arxiv_categories": arxiv.get("categories") or [],
+            "arxiv_query_terms": arxiv.get("query_terms") or [],
+            "arxiv_keywords": arxiv.get("keywords") or [],
+            "rss": s.get("rss") or [],
+            # scoring
+            "keyword_categories": sc.get("keyword_categories") or [],
+            "scoring": {
+                "account_whitelist": sc.get("account_whitelist", 10),
+                "engagement_per_100_likes": sc.get("engagement", {}).get("per_100_likes", 1),
+                "engagement_per_1000_likes": sc.get("engagement", {}).get("per_1000_likes", 2),
+                "engagement_max": sc.get("engagement", {}).get("max", 10),
+                "human_curated": sc.get("human_curated", 20),
+                "benchmark_numbers": sc.get("benchmark_numbers", 15),
+                "code_release": sc.get("code_release", 10),
+                "open_weights": sc.get("open_weights", 10),
+            },
+            "benchmark_regex": sc.get(
+                "benchmark_regex",
+                r"\d+\s*(tok/s|tokens?/?s|t/s|tflops?|ms|latency|throughput)",
+            ),
+            "priority_thresholds": sc.get("thresholds", DEFAULT_SCORING["thresholds"]),
+            # alert delivery for the alert stage (kind=command only)
+            "send_command": (self.destination.get("send_command")
+                             if self.destination.get("kind") == "command" else ""),
+            "alert_min_priority": (self.brief.get("alert_min_priority", "P0")),
+        }
+        # Legacy compatibility: a spec may point config_path at a hand-written
+        # engine config; then that file wins entirely (see manager.create).
+        return cfg
+
+
+def _merged(base: dict, override: dict) -> dict:
+    out = json.loads(json.dumps(base))
+    for k, v in override.items():
+        if isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k].update(v)
+        else:
+            out[k] = v
+    return out