forgesight-registry 0.1.1__tar.gz

forgesight_registry-0.1.1/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# venv / tooling
+.venv/
+venv/
+.uv/
+uv.lock
+
+# test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# secrets / local env (never commit)
+.env
+.env.*
+
+# editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# local-only session working state (per the workspace pipeline)
+.claude/state/
+
+# local-only launch planning (not part of the published repo)
+/launch/

forgesight_registry-0.1.1/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: forgesight-registry
+Version: 0.1.1
+Summary: ForgeSight registry — declared agent ownership auto-stamped onto runs; chargeback + catalogue rollups.
+Project-URL: Homepage, https://github.com/Scaffoldic/forgesight
+Project-URL: Repository, https://github.com/Scaffoldic/forgesight
+Project-URL: Issues, https://github.com/Scaffoldic/forgesight/issues
+Project-URL: Changelog, https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md
+Author: kjoshi
+License-Expression: Apache-2.0
+Keywords: ai-agents,chargeback,finops,forgesight,observability,registry
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: forgesight-core
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# forgesight-registry
+
+Declared agent **ownership** auto-stamped onto every run — plus offline **chargeback** and
+**catalogue** rollups — for [ForgeSight](https://github.com/Scaffoldic/forgesight). The last
+mile from per-run cost to org-level FinOps: declare an agent *once* instead of tagging it
+every run, everywhere, inconsistently.
+
+```bash
+pip install forgesight-registry
+```
+
+```yaml
+# agents.yaml — one source of truth
+agents:
+  - name: invoice-parser
+    version: "2.3.0"
+    owner: "fin-platform@acme.com"
+    team: "finance-platform"
+    repo: "acme/invoice-agents"
+    lifecycle: "ga"
+    sla_tier: "tier-1"
+  - name: nightly-summariser
+    version: "*"
+    owner: "growth@acme.com"
+    team: "growth"
+    lifecycle: "beta"
+```
+
+```python
+import forgesight
+from forgesight_registry import Registry
+
+reg = Registry.from_file("agents.yaml")
+forgesight.configure(run_metadata_provider=reg.ownership_metadata)  # stamp ownership at run start
+
+# Agent author writes nothing extra — every run now carries team/owner/repo/... on the
+# root span and every child (FR-5):
+with forgesight.telemetry.agent_run("invoice-parser", version="2.3.0") as run:
+    ...
+```
+
+## How it works
+
+- **Stamp at run start.** The registry resolves `(name, version)` — exact → `"*"` wildcard →
+  unmatched — and merges the agent's ownership fields into the run's metadata. **Caller-set
+  keys win** (a one-off `environment=staging` survives). Undeclared agents are counted
+  (`on_unmatched` = `warn` | `ignore` | `error`), so the registry doubles as a "what's running
+  but undeclared" detector.
+- **Chargeback is a group-by.** `ChargebackReport.from_records(records, dimensions=["team", "environment"])`
+  sums `cost_usd` / tokens / runs / failures per group — clean, because the dimensions were
+  stamped at source. An absent dimension groups under `<unattributed>` so cost never vanishes.
+- **Catalogue = declared ∪ observed.** `AgentCatalogue.from_records(records, registry=reg, now_unix_nanos=…)`
+  joins the declared registry (owner / lifecycle / SLA) with observed telemetry (last-seen /
+  run count / windowed cost), surfacing declared-but-silent and active-but-undeclared agents.
+
+## Configuration
+
+```yaml
+registry:
+  enabled: true              # master switch (default false — install does nothing until on)
+  source: "file"             # file | http | <custom>
+  path: "agents.yaml"
+  on_unmatched: "warn"       # warn | ignore | error
+  stamp:
+    fields: ["team", "owner", "repo", "lifecycle", "sla_tier"]
+    prefix: ""               # e.g. "org." → org.team, org.owner
+```
+
+Non-blocking: stamping is an in-memory dict merge (P6). No vendor SDK (P1) — the HTTP source
+uses stdlib `urllib`. Attribution, not control — budget *enforcement* on these same dimensions
+is `forgesight-governance` (feat-020).
+
+## License
+
+Apache-2.0

forgesight_registry-0.1.1/README.md

@@ -0,0 +1,75 @@
+# forgesight-registry
+
+Declared agent **ownership** auto-stamped onto every run — plus offline **chargeback** and
+**catalogue** rollups — for [ForgeSight](https://github.com/Scaffoldic/forgesight). The last
+mile from per-run cost to org-level FinOps: declare an agent *once* instead of tagging it
+every run, everywhere, inconsistently.
+
+```bash
+pip install forgesight-registry
+```
+
+```yaml
+# agents.yaml — one source of truth
+agents:
+  - name: invoice-parser
+    version: "2.3.0"
+    owner: "fin-platform@acme.com"
+    team: "finance-platform"
+    repo: "acme/invoice-agents"
+    lifecycle: "ga"
+    sla_tier: "tier-1"
+  - name: nightly-summariser
+    version: "*"
+    owner: "growth@acme.com"
+    team: "growth"
+    lifecycle: "beta"
+```
+
+```python
+import forgesight
+from forgesight_registry import Registry
+
+reg = Registry.from_file("agents.yaml")
+forgesight.configure(run_metadata_provider=reg.ownership_metadata)  # stamp ownership at run start
+
+# Agent author writes nothing extra — every run now carries team/owner/repo/... on the
+# root span and every child (FR-5):
+with forgesight.telemetry.agent_run("invoice-parser", version="2.3.0") as run:
+    ...
+```
+
+## How it works
+
+- **Stamp at run start.** The registry resolves `(name, version)` — exact → `"*"` wildcard →
+  unmatched — and merges the agent's ownership fields into the run's metadata. **Caller-set
+  keys win** (a one-off `environment=staging` survives). Undeclared agents are counted
+  (`on_unmatched` = `warn` | `ignore` | `error`), so the registry doubles as a "what's running
+  but undeclared" detector.
+- **Chargeback is a group-by.** `ChargebackReport.from_records(records, dimensions=["team", "environment"])`
+  sums `cost_usd` / tokens / runs / failures per group — clean, because the dimensions were
+  stamped at source. An absent dimension groups under `<unattributed>` so cost never vanishes.
+- **Catalogue = declared ∪ observed.** `AgentCatalogue.from_records(records, registry=reg, now_unix_nanos=…)`
+  joins the declared registry (owner / lifecycle / SLA) with observed telemetry (last-seen /
+  run count / windowed cost), surfacing declared-but-silent and active-but-undeclared agents.
+
+## Configuration
+
+```yaml
+registry:
+  enabled: true              # master switch (default false — install does nothing until on)
+  source: "file"             # file | http | <custom>
+  path: "agents.yaml"
+  on_unmatched: "warn"       # warn | ignore | error
+  stamp:
+    fields: ["team", "owner", "repo", "lifecycle", "sla_tier"]
+    prefix: ""               # e.g. "org." → org.team, org.owner
+```
+
+Non-blocking: stamping is an in-memory dict merge (P6). No vendor SDK (P1) — the HTTP source
+uses stdlib `urllib`. Attribution, not control — budget *enforcement* on these same dimensions
+is `forgesight-governance` (feat-020).
+
+## License
+
+Apache-2.0

forgesight_registry-0.1.1/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "forgesight-registry"
+version = "0.1.1"
+description = "ForgeSight registry — declared agent ownership auto-stamped onto runs; chargeback + catalogue rollups."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "kjoshi" }]
+keywords = ["observability", "finops", "chargeback", "registry", "ai-agents", "forgesight"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Topic :: System :: Monitoring",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["forgesight-core", "PyYAML>=6.0"]
+
+[project.entry-points."forgesight.modules"]
+registry = "forgesight_registry:install"
+
+[project.entry-points."forgesight.registry_sources"]
+file = "forgesight_registry.source:FileSource"
+http = "forgesight_registry.source:HttpSource"
+
+[project.urls]
+Homepage = "https://github.com/Scaffoldic/forgesight"
+Repository = "https://github.com/Scaffoldic/forgesight"
+Issues = "https://github.com/Scaffoldic/forgesight/issues"
+Changelog = "https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forgesight_registry"]
+
+[tool.uv.sources]
+forgesight-core = { workspace = true }

forgesight_registry-0.1.1/src/forgesight_registry/__init__.py

@@ -0,0 +1,67 @@
+"""ForgeSight registry — declared agent ownership auto-stamped onto runs; chargeback rollups.
+
+Wire the registry's stamping at bootstrap, then chargeback and the catalogue are group-bys
+over the clean dimensions the SDK stamped:
+
+```python
+import forgesight
+from forgesight_registry import Registry
+
+reg = Registry.from_file("agents.yaml")
+forgesight.configure(run_metadata_provider=reg.ownership_metadata)
+```
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .model import AgentEntry, Lifecycle
+from .registry import Registry, RegistryUnmatched
+from .rollup import AgentCatalogue, CatalogueEntry, ChargebackReport, ChargebackRow
+from .source import FileSource, HttpSource, RegistrySource
+
+__version__ = "0.1.0"
+
+_installed: Registry | None = None
+
+
+def install(config: Mapping[str, Any] | None = None) -> Registry:
+    """The ``forgesight.modules`` entry point: build the registry from config and stash it.
+
+    Wire it as the run-start provider with
+    ``configure(run_metadata_provider=installed_registry().ownership_metadata)``.
+    """
+    global _installed
+    _installed = Registry.from_config(config)
+    return _installed
+
+
+def installed_registry() -> Registry | None:
+    """The registry built by :func:`install`, or ``None`` if not installed."""
+    return _installed
+
+
+def reset_for_tests() -> None:
+    global _installed
+    _installed = None
+
+
+__all__ = [
+    "AgentCatalogue",
+    "AgentEntry",
+    "CatalogueEntry",
+    "ChargebackReport",
+    "ChargebackRow",
+    "FileSource",
+    "HttpSource",
+    "Lifecycle",
+    "Registry",
+    "RegistrySource",
+    "RegistryUnmatched",
+    "__version__",
+    "install",
+    "installed_registry",
+    "reset_for_tests",
+]

forgesight_registry-0.1.1/src/forgesight_registry/model.py

@@ -0,0 +1,50 @@
+"""``AgentEntry`` — one declared agent's ownership metadata (feat-022).
+
+The registry's value type: the name→team→owner→repo→lifecycle mapping that, declared once,
+is auto-stamped onto every run so chargeback rolls up on clean dimensions and every run is
+traceable to a human. ``version`` is an exact string or ``"*"`` (any version). Experimental.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from types import MappingProxyType
+
+_EMPTY: Mapping[str, str] = MappingProxyType({})
+
+
+class Lifecycle(StrEnum):
+    EXPERIMENTAL = "experimental"
+    BETA = "beta"
+    GA = "ga"
+    DEPRECATED = "deprecated"
+
+
+@dataclass(frozen=True, slots=True)
+class AgentEntry:
+    name: str
+    version: str = "*"  # exact version or "*" wildcard
+    owner: str | None = None
+    team: str | None = None
+    repo: str | None = None
+    lifecycle: Lifecycle = Lifecycle.GA
+    sla_tier: str | None = None
+    extra: Mapping[str, str] = field(default_factory=lambda: _EMPTY)
+
+    def fields(self) -> dict[str, str]:
+        """The stampable fields as a flat ``key → value`` dict (omitting unset ones)."""
+        out: dict[str, str] = {}
+        if self.owner is not None:
+            out["owner"] = self.owner
+        if self.team is not None:
+            out["team"] = self.team
+        if self.repo is not None:
+            out["repo"] = self.repo
+        out["lifecycle"] = self.lifecycle.value
+        if self.sla_tier is not None:
+            out["sla_tier"] = self.sla_tier
+        for key, value in self.extra.items():
+            out[key] = value
+        return out

forgesight_registry-0.1.1/src/forgesight_registry/registry.py

@@ -0,0 +1,124 @@
+"""``Registry`` — resolve ``(name, version)`` → ownership and stamp it onto every run.
+
+Wired at bootstrap as the runtime's run-start metadata provider (feat-022): at run start the
+SDK looks the agent up and merges its ownership fields into the run's metadata (on the root
+span and every child, FR-5) — caller-set keys win. Resolution is exact ``(name, version)`` →
+``(name, "*")`` wildcard → unmatched (counted; ``on_unmatched`` decides warn/ignore/error).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from .model import AgentEntry
+from .source import FileSource, HttpSource, RegistrySource, parse_entries
+
+_log = logging.getLogger("forgesight.registry")
+_ON_UNMATCHED = ("warn", "ignore", "error")
+
+
+class RegistryUnmatched(LookupError):
+    """Raised at run start when ``on_unmatched='error'`` and an agent isn't declared."""
+
+
+class Registry:
+    """The declared agent registry: resolve ownership and produce run-start metadata."""
+
+    def __init__(
+        self,
+        entries: Sequence[AgentEntry],
+        *,
+        stamp_fields: Sequence[str] | None = None,
+        prefix: str = "",
+        on_unmatched: str = "warn",
+    ) -> None:
+        if on_unmatched not in _ON_UNMATCHED:
+            raise ValueError(f"on_unmatched must be one of {_ON_UNMATCHED}, got {on_unmatched!r}")
+        self._entries = list(entries)
+        self._exact: dict[tuple[str, str], AgentEntry] = {}
+        self._wildcard: dict[str, AgentEntry] = {}
+        for entry in entries:
+            if entry.version == "*":
+                self._wildcard[entry.name] = entry
+            else:
+                self._exact[(entry.name, entry.version)] = entry
+        self._fields = tuple(stamp_fields) if stamp_fields is not None else None
+        self._prefix = prefix
+        self._on_unmatched = on_unmatched
+        self.unmatched_count = 0
+
+    @property
+    def entries(self) -> list[AgentEntry]:
+        return list(self._entries)
+
+    def resolve(self, name: str, version: str | None) -> AgentEntry | None:
+        if version is not None:
+            exact = self._exact.get((name, version))
+            if exact is not None:
+                return exact
+        return self._wildcard.get(name)
+
+    def ownership_metadata(self, name: str, version: str | None = None) -> dict[str, str]:
+        """The metadata to stamp on a run for ``(name, version)``. The run-start provider."""
+        entry = self.resolve(name, version)
+        if entry is None:
+            self.unmatched_count += 1
+            if self._on_unmatched == "error":
+                raise RegistryUnmatched(
+                    f"agent {name!r} v{version} is not declared in the registry"
+                )
+            if self._on_unmatched == "warn":
+                _log.warning("forgesight-registry: undeclared agent %r v%s", name, version)
+            return {}
+        fields = entry.fields()
+        if self._fields is not None:
+            fields = {k: v for k, v in fields.items() if k in self._fields}
+        if self._prefix:
+            fields = {f"{self._prefix}{k}": v for k, v in fields.items()}
+        return fields
+
+    # --- construction -----------------------------------------------------
+    @classmethod
+    def from_source(cls, source: RegistrySource, **kwargs: Any) -> Registry:
+        return cls(source.load(), **kwargs)
+
+    @classmethod
+    def from_file(cls, path: str, **kwargs: Any) -> Registry:
+        return cls.from_source(FileSource(path), **kwargs)
+
+    @classmethod
+    def from_entries(cls, entries: Sequence[Mapping[str, Any]], **kwargs: Any) -> Registry:
+        return cls(parse_entries(list(entries)), **kwargs)
+
+    @classmethod
+    def from_config(cls, settings: Mapping[str, Any] | None = None) -> Registry:
+        from forgesight_core.config import load_settings
+
+        resolved = settings if settings is not None else load_settings()
+        block = resolved.get("registry")
+        block = block if isinstance(block, Mapping) else {}
+        stamp = block.get("stamp")
+        stamp = stamp if isinstance(stamp, Mapping) else {}
+        kwargs: dict[str, Any] = {
+            "on_unmatched": str(block.get("on_unmatched", "warn")),
+            "prefix": str(stamp.get("prefix", "")),
+            "stamp_fields": list(stamp["fields"])
+            if isinstance(stamp.get("fields"), Sequence)
+            else None,
+        }
+        if not block.get("enabled", False):
+            return cls([], **kwargs)  # installed but not switched on (P2) ⇒ stamps nothing
+        source = str(block.get("source", "file"))
+        if source == "file":
+            path = block.get("path")
+            if not path:
+                raise ValueError("registry.source 'file' requires path")
+            return cls.from_file(str(path), **kwargs)
+        if source == "http":
+            url = block.get("url")
+            if not url:
+                raise ValueError("registry.source 'http' requires url")
+            return cls.from_source(HttpSource(str(url)), **kwargs)
+        raise ValueError(f"unknown registry source {source!r}")

forgesight_registry-0.1.1/src/forgesight_registry/rollup.py

@@ -0,0 +1,179 @@
+"""Offline chargeback + catalogue rollups over exported records (feat-022).
+
+Pure aggregation, off the hot path. Because the ownership dimensions were stamped *at
+source* from one declaration, the group-by is clean — no missing / misspelled ``team``. An
+absent dimension groups under ``"<unattributed>"`` so cost never silently vanishes. The
+catalogue joins the *declared* registry (owner / lifecycle / SLA) with *observed* telemetry
+(last-seen / run count / windowed cost), surfacing declared-but-silent and undeclared agents.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+
+from forgesight_api import Kind, Record, RunStatus
+
+from .model import Lifecycle
+from .registry import Registry
+
+UNATTRIBUTED = "<unattributed>"
+_NANOS_PER_DAY = 86_400 * 1_000_000_000
+_OK = frozenset({RunStatus.OK, RunStatus.RUNNING})
+
+
+@dataclass(frozen=True, slots=True)
+class ChargebackRow:
+    dimensions: Mapping[str, str]
+    cost_usd: float
+    run_count: int
+    token_total: int
+    failure_count: int
+
+
+class ChargebackReport:
+    """Cost / tokens / runs / failures grouped by ownership dimensions."""
+
+    def __init__(self, rows: Sequence[ChargebackRow]) -> None:
+        self._rows = list(rows)
+
+    @classmethod
+    def from_records(
+        cls,
+        records: Sequence[Record],
+        *,
+        dimensions: Sequence[str],
+        registry: Registry | None = None,
+    ) -> ChargebackReport:
+        groups: dict[tuple[str, ...], list[float]] = {}
+        for record in records:
+            key = tuple(str(record.attributes.get(dim, UNATTRIBUTED)) for dim in dimensions)
+            acc = groups.setdefault(key, [0.0, 0.0, 0.0, 0.0])  # cost, tokens, runs, failures
+            if record.llm is not None:
+                acc[0] += record.llm.cost_usd or 0.0
+                acc[1] += record.llm.usage.total
+            if record.kind is Kind.AGENT:
+                acc[2] += 1
+                if record.status not in _OK:
+                    acc[3] += 1
+        rows = [
+            ChargebackRow(
+                dimensions=dict(zip(dimensions, key, strict=True)),
+                cost_usd=acc[0],
+                token_total=int(acc[1]),
+                run_count=int(acc[2]),
+                failure_count=int(acc[3]),
+            )
+            for key, acc in groups.items()
+        ]
+        return cls(rows)
+
+    def rows(self) -> list[ChargebackRow]:
+        return list(self._rows)
+
+    def total_usd(self) -> float:
+        return sum(row.cost_usd for row in self._rows)
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogueEntry:
+    name: str
+    version: str
+    owner: str | None
+    team: str | None
+    lifecycle: Lifecycle | None
+    sla_tier: str | None
+    last_seen: int | None
+    run_count: int
+    cost_30d: float
+    declared: bool
+    active: bool
+
+
+@dataclass
+class _Observed:
+    run_count: int = 0
+    last_seen: int | None = None
+    cost_window: float = 0.0
+    run_ids: set[str] = field(default_factory=set)
+
+
+class AgentCatalogue:
+    """Declared+observed union: agents with owner, lifecycle, last-seen, and windowed cost."""
+
+    def __init__(self, entries: Sequence[CatalogueEntry]) -> None:
+        self._entries = list(entries)
+
+    @classmethod
+    def from_records(
+        cls,
+        records: Sequence[Record],
+        *,
+        registry: Registry,
+        now_unix_nanos: int,
+        window_days: int = 30,
+    ) -> AgentCatalogue:
+        cutoff = now_unix_nanos - window_days * _NANOS_PER_DAY
+        observed: dict[str, _Observed] = {}
+        run_to_name: dict[str, str] = {}
+        for record in records:
+            if record.kind is Kind.AGENT:
+                obs = observed.setdefault(record.name, _Observed())
+                obs.run_count += 1
+                obs.run_ids.add(record.run_id)
+                run_to_name[record.run_id] = record.name
+                end = record.end_unix_nanos
+                if end is not None and (obs.last_seen is None or end > obs.last_seen):
+                    obs.last_seen = end
+        for record in records:  # attribute LLM cost to the owning agent run, within the window
+            if record.llm is None:
+                continue
+            name = run_to_name.get(record.run_id)
+            if name is None:
+                continue
+            end = record.end_unix_nanos or 0
+            if end >= cutoff and record.llm.cost_usd:
+                observed[name].cost_window += record.llm.cost_usd
+
+        entries: list[CatalogueEntry] = []
+        seen_names: set[str] = set()
+        for declared in registry.entries:  # declared-and-active + declared-but-silent
+            declared_obs = observed.get(declared.name)
+            seen_names.add(declared.name)
+            entries.append(
+                CatalogueEntry(
+                    name=declared.name,
+                    version=declared.version,
+                    owner=declared.owner,
+                    team=declared.team,
+                    lifecycle=declared.lifecycle,
+                    sla_tier=declared.sla_tier,
+                    last_seen=declared_obs.last_seen if declared_obs else None,
+                    run_count=declared_obs.run_count if declared_obs else 0,
+                    cost_30d=declared_obs.cost_window if declared_obs else 0.0,
+                    declared=True,
+                    active=declared_obs is not None,
+                )
+            )
+        for name, obs in observed.items():  # active-but-undeclared (a governance gap)
+            if name in seen_names:
+                continue
+            entries.append(
+                CatalogueEntry(
+                    name=name,
+                    version="*",
+                    owner=None,
+                    team=None,
+                    lifecycle=None,
+                    sla_tier=None,
+                    last_seen=obs.last_seen,
+                    run_count=obs.run_count,
+                    cost_30d=obs.cost_window,
+                    declared=False,
+                    active=True,
+                )
+            )
+        return cls(entries)
+
+    def entries(self) -> list[CatalogueEntry]:
+        return list(self._entries)

forgesight_registry-0.1.1/src/forgesight_registry/source.py

@@ -0,0 +1,82 @@
+"""Where registry entries come from — file and HTTP shipped, custom via the Protocol.
+
+A ``RegistrySource`` loads ``AgentEntry`` records from a declared source. The file source
+reads YAML/JSON once at ``configure()``; the HTTP source TTL-refreshes best-effort and keeps
+the last-good set on a failed refresh (the cost-table pattern). No vendor SDK — the HTTP
+source uses stdlib ``urllib`` (P1).
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from collections.abc import Mapping, Sequence
+from typing import Any, Protocol, runtime_checkable
+
+import yaml
+
+from .model import AgentEntry, Lifecycle
+
+
+@runtime_checkable
+class RegistrySource(Protocol):
+    """Loads the declared registry entries. Shipped: file + HTTP; custom via this Protocol."""
+
+    def load(self) -> Sequence[AgentEntry]: ...
+
+
+def parse_entries(raw: Any) -> list[AgentEntry]:
+    """Parse the ``agents:`` list (or a bare list) into :class:`AgentEntry` records."""
+    items = raw.get("agents") if isinstance(raw, Mapping) else raw
+    if not isinstance(items, Sequence):
+        return []
+    entries: list[AgentEntry] = []
+    for item in items:
+        if not isinstance(item, Mapping) or not item.get("name"):
+            continue
+        known = {"name", "version", "owner", "team", "repo", "lifecycle", "sla_tier"}
+        extra = {str(k): str(v) for k, v in item.items() if k not in known and k != "extra"}
+        extra.update({str(k): str(v) for k, v in (item.get("extra") or {}).items()})
+        entries.append(
+            AgentEntry(
+                name=str(item["name"]),
+                version=str(item.get("version", "*")),
+                owner=_opt(item.get("owner")),
+                team=_opt(item.get("team")),
+                repo=_opt(item.get("repo")),
+                lifecycle=Lifecycle(str(item.get("lifecycle", "ga"))),
+                sla_tier=_opt(item.get("sla_tier")),
+                extra=extra,
+            )
+        )
+    return entries
+
+
+class FileSource:
+    """Loads entries from a YAML or JSON file (read once at load)."""
+
+    def __init__(self, path: str) -> None:
+        self._path = path
+
+    def load(self) -> Sequence[AgentEntry]:
+        with open(self._path, encoding="utf-8") as handle:
+            raw = yaml.safe_load(handle)  # YAML is a JSON superset
+        return parse_entries(raw)
+
+
+class HttpSource:  # pragma: no cover - requires a live endpoint
+    """Loads entries from an HTTP(S) URL (stdlib urllib; TTL refresh is the Registry's job)."""
+
+    def __init__(self, url: str, *, timeout: float = 5.0) -> None:
+        self._url = url
+        self._timeout = timeout
+
+    def load(self) -> Sequence[AgentEntry]:
+        request = urllib.request.Request(self._url, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(request, timeout=self._timeout) as response:
+            raw = json.loads(response.read().decode("utf-8"))
+        return parse_entries(raw)
+
+
+def _opt(value: Any) -> str | None:
+    return str(value) if value is not None else None

forgesight_registry-0.1.1/tests/test_registry.py

@@ -0,0 +1,352 @@
+"""Tests for the registry: resolution, stamping, chargeback, catalogue, config."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+
+import pytest
+
+from forgesight_api import Kind, LLMCall, Record, RunStatus, TokenUsage
+from forgesight_core import InMemoryExporter, configure, reset_runtime, telemetry
+from forgesight_registry import (
+    AgentCatalogue,
+    AgentEntry,
+    ChargebackReport,
+    Lifecycle,
+    Registry,
+    RegistryUnmatched,
+    install,
+    installed_registry,
+    reset_for_tests,
+)
+
+ENTRIES = [
+    {
+        "name": "invoice-parser",
+        "version": "2.3.0",
+        "owner": "fin@acme",
+        "team": "finance",
+        "repo": "acme/inv",
+        "lifecycle": "ga",
+        "sla_tier": "tier-1",
+    },
+    {
+        "name": "summariser",
+        "version": "*",
+        "owner": "growth@acme",
+        "team": "growth",
+        "lifecycle": "beta",
+    },
+]
+
+
+@pytest.fixture(autouse=True)
+def _reset() -> Iterator[None]:
+    yield
+    reset_runtime()
+    reset_for_tests()
+
+
+def _reg(**kw: object) -> Registry:
+    return Registry.from_entries(ENTRIES, **kw)
+
+
+# --- resolution ---------------------------------------------------------------
+def test_resolve_exact_then_wildcard_then_none() -> None:
+    reg = _reg()
+    assert reg.resolve("invoice-parser", "2.3.0").team == "finance"  # type: ignore[union-attr]
+    assert reg.resolve("invoice-parser", "9.9.9") is None  # exact miss, no wildcard
+    assert reg.resolve("summariser", "1.0.0").team == "growth"  # type: ignore[union-attr]  # wildcard
+    assert reg.resolve("unknown", "1.0") is None
+
+
+def test_ownership_metadata_fields() -> None:
+    reg = _reg()
+    meta = reg.ownership_metadata("invoice-parser", "2.3.0")
+    assert meta == {
+        "owner": "fin@acme",
+        "team": "finance",
+        "repo": "acme/inv",
+        "lifecycle": "ga",
+        "sla_tier": "tier-1",
+    }
+
+
+def test_ownership_metadata_field_filter_and_prefix() -> None:
+    reg = _reg(stamp_fields=["team", "owner"], prefix="org.")
+    meta = reg.ownership_metadata("invoice-parser", "2.3.0")
+    assert meta == {"org.team": "finance", "org.owner": "fin@acme"}
+
+
+def test_extra_fields_stamped() -> None:
+    reg = Registry.from_entries([{"name": "x", "version": "*", "team": "t", "cost_center": "cc-9"}])
+    assert reg.ownership_metadata("x", "1")["cost_center"] == "cc-9"
+
+
+# --- on_unmatched -------------------------------------------------------------
+def test_on_unmatched_warn_counts(caplog: pytest.LogCaptureFixture) -> None:
+    reg = _reg(on_unmatched="warn")
+    with caplog.at_level("WARNING"):
+        assert reg.ownership_metadata("ghost", "1.0") == {}
+    assert reg.unmatched_count == 1
+    assert any("undeclared agent" in r.message for r in caplog.records)
+
+
+def test_on_unmatched_ignore_silent() -> None:
+    reg = _reg(on_unmatched="ignore")
+    assert reg.ownership_metadata("ghost", "1.0") == {}
+    assert reg.unmatched_count == 1
+
+
+def test_on_unmatched_error_raises() -> None:
+    reg = _reg(on_unmatched="error")
+    with pytest.raises(RegistryUnmatched):
+        reg.ownership_metadata("ghost", "1.0")
+
+
+def test_invalid_on_unmatched() -> None:
+    with pytest.raises(ValueError, match="on_unmatched must be"):
+        _reg(on_unmatched="explode")
+
+
+# --- stamping at run start (core hook) ---------------------------------------
+def test_stamps_ownership_on_run_and_children() -> None:
+    reg = _reg()
+    exporter = InMemoryExporter()
+    configure(exporters=[exporter], sync_export=True, run_metadata_provider=reg.ownership_metadata)
+    with (
+        telemetry.agent_run("invoice-parser", version="2.3.0") as run,
+        run.llm_call("anthropic", "m"),
+    ):
+        pass
+    agent = next(r for r in exporter.records if r.kind is Kind.AGENT)
+    llm = next(r for r in exporter.records if r.kind is Kind.LLM)
+    assert agent.attributes["team"] == "finance"
+    assert agent.attributes["owner"] == "fin@acme"
+    assert llm.attributes["team"] == "finance"  # propagated onto the child (FR-5)
+
+
+def test_caller_metadata_wins_over_registry() -> None:
+    reg = _reg()
+    exporter = InMemoryExporter()
+    configure(exporters=[exporter], sync_export=True, run_metadata_provider=reg.ownership_metadata)
+    with telemetry.agent_run("invoice-parser", version="2.3.0", metadata={"team": "override"}):
+        pass
+    agent = next(r for r in exporter.records if r.kind is Kind.AGENT)
+    assert agent.attributes["team"] == "override"  # caller-set key wins
+
+
+def test_unregistered_run_is_unstamped() -> None:
+    reg = _reg(on_unmatched="ignore")
+    exporter = InMemoryExporter()
+    configure(exporters=[exporter], sync_export=True, run_metadata_provider=reg.ownership_metadata)
+    with telemetry.agent_run("ghost", version="9.9"):
+        pass
+    agent = next(r for r in exporter.records if r.kind is Kind.AGENT)
+    assert "team" not in agent.attributes
+    assert reg.unmatched_count == 1
+
+
+# --- file source --------------------------------------------------------------
+def test_from_file(tmp_path: Path) -> None:
+    path = tmp_path / "agents.yaml"
+    path.write_text(
+        "agents:\n"
+        "  - name: a\n    version: '1.0'\n    team: t1\n    owner: o1\n"
+        "  - name: b\n    team: t2\n"
+    )
+    reg = Registry.from_file(str(path))
+    assert reg.resolve("a", "1.0").team == "t1"  # type: ignore[union-attr]
+    assert reg.resolve("b", "anything").team == "t2"  # type: ignore[union-attr]  # default wildcard
+
+
+# --- chargeback ---------------------------------------------------------------
+def _agent(team: str, env: str, run_id: str, status: RunStatus = RunStatus.OK) -> Record:
+    from types import MappingProxyType
+
+    return Record(
+        kind=Kind.AGENT,
+        run_id=run_id,
+        trace_id="t",
+        span_id=run_id,
+        parent_span_id=None,
+        name="a",
+        status=status,
+        start_unix_nanos=1,
+        end_unix_nanos=2,
+        attributes=MappingProxyType({"team": team, "environment": env}),
+    )
+
+
+def _llm(team: str, env: str, run_id: str, cost: float, tokens: int = 100) -> Record:
+    from types import MappingProxyType
+
+    return Record(
+        kind=Kind.LLM,
+        run_id=run_id,
+        trace_id="t",
+        span_id=f"{run_id}-l",
+        parent_span_id=run_id,
+        name="m",
+        status=RunStatus.OK,
+        start_unix_nanos=1,
+        end_unix_nanos=2,
+        attributes=MappingProxyType({"team": team, "environment": env}),
+        llm=LLMCall(provider="p", request_model="m", usage=TokenUsage(input=tokens), cost_usd=cost),
+    )
+
+
+def test_chargeback_groups_and_totals() -> None:
+    records = [
+        _agent("growth", "prod", "r1"),
+        _llm("growth", "prod", "r1", 0.10, 100),
+        _agent("growth", "prod", "r2"),
+        _llm("growth", "prod", "r2", 0.20, 200),
+        _agent("research", "dev", "r3", RunStatus.ERROR),
+        _llm("research", "dev", "r3", 0.05, 50),
+    ]
+    report = ChargebackReport.from_records(records, dimensions=["team", "environment"])
+    rows = {(r.dimensions["team"], r.dimensions["environment"]): r for r in report.rows()}
+    growth = rows[("growth", "prod")]
+    assert growth.cost_usd == pytest.approx(0.30)
+    assert growth.run_count == 2
+    assert growth.token_total == 300
+    assert growth.failure_count == 0
+    assert rows[("research", "dev")].failure_count == 1
+    assert report.total_usd() == pytest.approx(0.35)
+
+
+def test_chargeback_unattributed_bucket() -> None:
+    from types import MappingProxyType
+
+    rec = Record(
+        kind=Kind.LLM,
+        run_id="r",
+        trace_id="t",
+        span_id="s",
+        parent_span_id=None,
+        name="m",
+        status=RunStatus.OK,
+        start_unix_nanos=1,
+        end_unix_nanos=2,
+        attributes=MappingProxyType({}),  # no team
+        llm=LLMCall(provider="p", request_model="m", cost_usd=0.5),
+    )
+    report = ChargebackReport.from_records([rec], dimensions=["team"])
+    assert report.rows()[0].dimensions["team"] == "<unattributed>"  # cost never vanishes
+    assert report.total_usd() == pytest.approx(0.5)
+
+
+# --- catalogue ----------------------------------------------------------------
+def test_catalogue_declared_active_silent_undeclared() -> None:
+    reg = Registry.from_entries(
+        [
+            {
+                "name": "active-agent",
+                "version": "1.0",
+                "owner": "o",
+                "team": "t",
+                "lifecycle": "ga",
+            },
+            {"name": "silent-agent", "version": "1.0", "owner": "o2", "lifecycle": "deprecated"},
+        ]
+    )
+    now = 1_000 * 86_400 * 1_000_000_000  # day 1000 in ns
+    records = [
+        _agent("t", "prod", "ra"),
+        _llm("t", "prod", "ra", 0.4),
+    ]
+    # relabel the active agent's records to name "active-agent"
+    from dataclasses import replace
+
+    records = [replace(r, name="active-agent") if r.kind is Kind.AGENT else r for r in records]
+    records.append(_agent("x", "dev", "ru"))
+    records[-1] = replace(records[-1], name="rogue-agent")  # undeclared
+
+    # stamp recent end times so the cost falls inside the 30-day window
+    catalogue = AgentCatalogue.from_records(
+        [replace(r, end_unix_nanos=now) for r in records], registry=reg, now_unix_nanos=now
+    )
+    by_name = {e.name: e for e in catalogue.entries()}
+    assert by_name["active-agent"].active is True
+    assert by_name["active-agent"].cost_30d == pytest.approx(0.4)
+    assert by_name["silent-agent"].active is False  # declared but no runs
+    assert by_name["silent-agent"].lifecycle is Lifecycle.DEPRECATED
+    assert by_name["rogue-agent"].declared is False  # active but undeclared
+    assert by_name["rogue-agent"].owner is None
+
+
+def test_catalogue_cost_window_excludes_old() -> None:
+    from dataclasses import replace
+
+    reg = Registry.from_entries([{"name": "a", "version": "*", "team": "t"}])
+    now = 1_000 * 86_400 * 1_000_000_000
+    old = now - 40 * 86_400 * 1_000_000_000  # 40 days ago, outside the 30-day window
+    records = [
+        replace(_agent("t", "prod", "r1"), name="a", end_unix_nanos=old),
+        replace(_llm("t", "prod", "r1", 0.9), end_unix_nanos=old),
+    ]
+    catalogue = AgentCatalogue.from_records(records, registry=reg, now_unix_nanos=now)
+    assert catalogue.entries()[0].cost_30d == 0.0  # old cost excluded from the window
+
+
+# --- config / install ---------------------------------------------------------
+def test_from_config_disabled_stamps_nothing() -> None:
+    reg = Registry.from_config({"registry": {"enabled": False, "source": "file", "path": "x"}})
+    assert reg.entries == []  # not switched on ⇒ empty
+
+
+def test_from_config_file(tmp_path: Path) -> None:
+    path = tmp_path / "a.yaml"
+    path.write_text("agents:\n  - name: a\n    team: t\n")
+    reg = Registry.from_config({"registry": {"enabled": True, "source": "file", "path": str(path)}})
+    assert reg.resolve("a", "1").team == "t"  # type: ignore[union-attr]
+
+
+def test_from_config_file_requires_path() -> None:
+    with pytest.raises(ValueError, match="requires path"):
+        Registry.from_config({"registry": {"enabled": True, "source": "file"}})
+
+
+def test_from_config_unknown_source() -> None:
+    with pytest.raises(ValueError, match="unknown registry source"):
+        Registry.from_config({"registry": {"enabled": True, "source": "carrier-pigeon"}})
+
+
+def test_install_stashes_registry(tmp_path: Path) -> None:
+    path = tmp_path / "a.yaml"
+    path.write_text("agents:\n  - name: a\n    team: t\n")
+    install({"registry": {"enabled": True, "source": "file", "path": str(path)}})
+    assert installed_registry() is not None
+    assert installed_registry().resolve("a", "1").team == "t"  # type: ignore[union-attr]
+
+
+def test_agent_entry_lifecycle_default() -> None:
+    entry = AgentEntry(name="x")
+    assert entry.lifecycle is Lifecycle.GA
+    assert entry.version == "*"
+
+
+def test_from_config_http_requires_url() -> None:
+    with pytest.raises(ValueError, match="requires url"):
+        Registry.from_config({"registry": {"enabled": True, "source": "http"}})
+
+
+def test_parse_entries_skips_malformed() -> None:
+    from forgesight_registry.source import parse_entries
+
+    assert parse_entries({"agents": "not-a-list"}) == []
+    assert parse_entries(42) == []  # not a list at all
+    reg = Registry.from_entries(["not-a-dict", {"no_name": "x"}, {"name": "ok", "team": "t"}])
+    assert len(reg.entries) == 1  # only the well-formed entry survives
+    assert reg.entries[0].name == "ok"
+
+
+def test_chargeback_ignores_orphan_llm_in_catalogue() -> None:
+    # an LLM record whose run_id has no agent run is not attributed to any agent
+    reg = Registry.from_entries([{"name": "a", "version": "*", "team": "t"}])
+    now = 1_000 * 86_400 * 1_000_000_000
+    orphan = _llm("t", "prod", "no-agent-run", 0.9)
+    catalogue = AgentCatalogue.from_records([orphan], registry=reg, now_unix_nanos=now)
+    assert catalogue.entries()[0].cost_30d == 0.0  # declared "a" has no runs; orphan cost ignored