codemap-aimemory 0.3.0__py3-none-any.whl

codemap_aimemory/__init__.py

@@ -0,0 +1,5 @@
+"""Four-layer memory model L1 (.ai-memory) emitter."""
+
+from codemap_aimemory.emitter import AiMemoryEmitter
+
+__all__ = ["AiMemoryEmitter"]

codemap_aimemory/cli.py

@@ -0,0 +1,157 @@
+"""``codemap enrich`` subcommand — populate the LLM enrichment overlay.
+
+Registered via the ``codemap.cli_commands`` entry-point group (introduced in
+codemap-core 0.3.0). Core CLI discovers and mounts the subcommand at startup;
+without ``codemap-aimemory`` installed it simply isn't there.
+
+The command runs the deterministic L1 emitter is **not** affected — this
+only writes the optional ``.ai-memory/enrichment/<sha1>.yml`` overlay files.
+The next time the emitter runs (next ``codemap index``), it merges them into
+``entities/functions.yml`` keyed by ``symbol_id``.
+
+Configuration sources (in priority order, first wins):
+
+1. CLI flags: ``--api-key``, ``--base-url``, ``--model``, ``--backend``
+2. Environment variables:
+   * ``CODEMAP_LLM_API_KEY`` (fallbacks: ``ANTHROPIC_API_KEY`` /
+     ``OPENAI_API_KEY``)
+   * ``CODEMAP_LLM_BASE_URL`` (fallback: ``OPENAI_BASE_URL`` /
+     ``ANTHROPIC_BASE_URL``)
+   * ``CODEMAP_LLM_MODEL``
+   * ``CODEMAP_LLM_BACKEND``
+3. Built-in defaults (model: ``gpt-4o-mini``; backend: ``openai``).
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from codemap_aimemory.enrich import enrich
+from codemap_aimemory.llm import build_client, env_default
+
+__all__ = ["register"]
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("enrich")
+    def enrich_command(
+        path: Annotated[
+            Path,
+            typer.Argument(
+                exists=True,
+                file_okay=False,
+                dir_okay=True,
+                resolve_path=True,
+                help="Project root containing ``.codemap/``.",
+            ),
+        ] = Path("."),
+        backend: Annotated[
+            str,
+            typer.Option(
+                "--backend",
+                envvar="CODEMAP_LLM_BACKEND",
+                help="LLM backend: ``openai`` (default, any OpenAI-compatible "
+                "endpoint), ``anthropic`` (native SDK), or ``ollama``.",
+            ),
+        ] = "openai",
+        model: Annotated[
+            str,
+            typer.Option(
+                "--model",
+                envvar="CODEMAP_LLM_MODEL",
+                help="Model name passed verbatim to the backend.",
+            ),
+        ] = "gpt-4o-mini",
+        api_key: Annotated[
+            str,
+            typer.Option(
+                "--api-key",
+                envvar="CODEMAP_LLM_API_KEY",
+                help="API key (also picked up from CODEMAP_LLM_API_KEY, "
+                "ANTHROPIC_API_KEY, or OPENAI_API_KEY).",
+            ),
+        ] = "",
+        base_url: Annotated[
+            str,
+            typer.Option(
+                "--base-url",
+                envvar="CODEMAP_LLM_BASE_URL",
+                help="Override the LLM API base URL (e.g. a self-hosted "
+                "OpenAI-compatible endpoint).",
+            ),
+        ] = "",
+        changed_only: Annotated[
+            bool,
+            typer.Option(
+                "--changed-only",
+                help="Skip symbols whose enrichment file already exists.",
+            ),
+        ] = False,
+        dry_run: Annotated[
+            bool,
+            typer.Option(
+                "--dry-run",
+                help="Report what would be enriched and exit without calling the LLM.",
+            ),
+        ] = False,
+    ) -> None:
+        """Generate LLM enrichment overlay files under ``.ai-memory/enrichment/``."""
+        from codemap.io.json_store import JsonStore  # local import — IO layer
+
+        codemap_dir = path / ".codemap"
+        if not codemap_dir.exists():
+            typer.echo(
+                f"Error: no .codemap/ at {path}. Run `codemap index` first.",
+                err=True,
+            )
+            raise typer.Exit(code=2)
+
+        # Resolve credentials with env fallbacks beyond what envvar= covers.
+        resolved_key = api_key or env_default(
+            "CODEMAP_LLM_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"
+        )
+        resolved_base = base_url or env_default(
+            "CODEMAP_LLM_BASE_URL", "OPENAI_BASE_URL", "ANTHROPIC_BASE_URL"
+        )
+
+        out_dir = path / ".ai-memory"
+
+        if dry_run:
+            with JsonStore.open(codemap_dir, mode="r") as store:
+                fn_count = sum(1 for s in store.iter_symbols() if s.kind in {"method", "function"})
+            typer.echo(
+                f"Would enrich {fn_count} function/method symbols using "
+                f"{backend}/{model}.\nOutput dir: {out_dir / 'enrichment'}"
+            )
+            return
+
+        if backend != "ollama" and not resolved_key:
+            typer.echo(
+                "Error: API key is required for non-Ollama backends. Set "
+                "--api-key or CODEMAP_LLM_API_KEY / OPENAI_API_KEY / "
+                "ANTHROPIC_API_KEY.",
+                err=True,
+            )
+            raise typer.Exit(code=2)
+
+        client = build_client(
+            backend=backend,
+            model=model,
+            api_key=resolved_key or "",
+            base_url=resolved_base,
+        )
+
+        generated_at = datetime.now(UTC).strftime("%Y-%m-%d")
+        with JsonStore.open(codemap_dir, mode="r") as store:
+            written = enrich(
+                store,
+                client,
+                out_dir,
+                generated_at=generated_at,
+                changed_only=changed_only,
+            )
+        typer.echo(f"Wrote {len(written)} enrichment file(s) under {out_dir / 'enrichment'}.")

codemap_aimemory/emitter.py

@@ -0,0 +1,184 @@
+"""AiMemoryEmitter — write the four-layer memory model's L1 layout atomically.
+
+Reads a :class:`codemap.core.store.ReadOnlyStore` and emits, under
+``<output_dir>/.ai-memory/`` (or the explicit ``output_dir`` if it already
+ends in ``.ai-memory``):
+
+* ``entities/functions.yml``  — fn-/cls- entities with calls/called_by/
+  related_tables, signature, line_range, change_count_90d, confidence
+* ``entities/tables.yml``     — tbl- entities
+* ``entities/files.yml``      — file-* entities
+* ``relations/call-graph.yml``      — calls edges
+* ``relations/table-relations.yml`` — accesses_table edges
+* ``relations/rule-constraints.yml`` — empty placeholder (L2 owns)
+
+If an ``enrichment/`` folder sits alongside the output, the emitter loads
+``business_meaning`` / ``related_rules`` keyed by ``symbol_id`` and merges
+them in — but never writes back to the core index. Per ADR-0013 / the
+spec's two-layer separation, the deterministic index never carries
+explanation text.
+
+All writes are atomic (tmp + ``os.replace``) so an Agent reading
+``.ai-memory/`` mid-rebuild never sees a partial tree.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import tempfile
+from collections import defaultdict
+from pathlib import Path
+from typing import Any, ClassVar
+
+import yaml
+
+from codemap.core.store import ReadOnlyStore
+from codemap.emitters.base import EmitContext, EmitResult
+from codemap_aimemory.enrich import load_enrichment
+from codemap_aimemory.ids import build_entity_ids
+
+_FN_KINDS = frozenset({"method", "function"})
+_CLS_KINDS = frozenset({"class", "interface"})
+
+__all__ = ["AiMemoryEmitter"]
+
+
+class AiMemoryEmitter:
+    name: ClassVar[str] = "ai-memory"
+    version: ClassVar[str] = "0.1.0"
+
+    def emit(self, store: ReadOnlyStore, ctx: EmitContext) -> EmitResult:
+        out_dir = _resolve_out_dir(ctx.output_dir)
+
+        symbols = list(store.iter_symbols())
+        edges = list(store.iter_edges())
+        sid_str: dict[Any, str] = {s.id: str(s.id) for s in symbols}
+        kinds: dict[str, str] = {sid_str[s.id]: s.kind for s in symbols}
+        eid = build_entity_ids(list(kinds.keys()), kinds)
+        known: set[str] = set(eid)
+        enrichment = load_enrichment(out_dir / "enrichment")
+
+        calls: defaultdict[str, list[str]] = defaultdict(list)
+        called_by: defaultdict[str, list[str]] = defaultdict(list)
+        related_tables: defaultdict[str, list[str]] = defaultdict(list)
+        # Two-hop expansion: a Java method that maps_to a sql_mapping which
+        # in turn accesses_table T should surface T in the method's
+        # related_tables. We collect maps_to and accesses_table separately
+        # first, then fan out maps_to sources onto the targets' tables.
+        maps_to_src: defaultdict[str, list[str]] = defaultdict(list)
+        accesses_by_src: defaultdict[str, list[str]] = defaultdict(list)
+        rel_calls: list[dict[str, Any]] = []
+        rel_tables: list[dict[str, Any]] = []
+
+        for edge in edges:
+            src = str(edge.source)
+            tgt = str(edge.target)
+            if src not in known or tgt not in known:
+                continue
+            if edge.kind == "calls":
+                calls[src].append(eid[tgt])
+                called_by[tgt].append(eid[src])
+                rel_calls.append(
+                    {
+                        "from": eid[src],
+                        "to": eid[tgt],
+                        "type": "calls",
+                        "confidence": edge.confidence,
+                    }
+                )
+            elif edge.kind == "accesses_table":
+                accesses_by_src[src].append(eid[tgt])
+                related_tables[src].append(eid[tgt])
+                rel_tables.append(
+                    {
+                        "from": eid[src],
+                        "to": eid[tgt],
+                        "type": "accesses_table",
+                        "confidence": edge.confidence,
+                    }
+                )
+            elif edge.kind == "maps_to":
+                maps_to_src[src].append(tgt)
+
+        # Fan out: for every java method that maps_to a sql_mapping, copy
+        # that sql_mapping's table targets onto the method's related_tables.
+        for method_sid, mapping_sids in maps_to_src.items():
+            for mapping_sid in mapping_sids:
+                for table_eid in accesses_by_src.get(mapping_sid, []):
+                    if table_eid not in related_tables[method_sid]:
+                        related_tables[method_sid].append(table_eid)
+
+        functions: list[dict[str, Any]] = []
+        tables: list[dict[str, Any]] = []
+        for sym in symbols:
+            sid = sid_str[sym.id]
+            enr = enrichment.get(sid, {})
+            base = {
+                "id": eid[sid],
+                "symbol_id": sid,
+                "file": str(sym.file),
+                "line_range": [sym.range.start_line, sym.range.end_line],
+                "signature": sym.signature,
+                "confidence": sym.confidence,
+                "change_count_90d": sym.extra.get("change_count_90d"),
+                "business_meaning": enr.get("business_meaning"),
+            }
+            if sym.kind in _FN_KINDS:
+                base["type"] = "function"
+                base["calls"] = calls.get(sid, [])
+                base["called_by"] = called_by.get(sid, [])
+                base["related_tables"] = related_tables.get(sid, [])
+                base["related_rules"] = enr.get("related_rules", [])
+                functions.append(base)
+            elif sym.kind in _CLS_KINDS:
+                base["type"] = "class"
+                base["calls"] = calls.get(sid, [])
+                base["called_by"] = called_by.get(sid, [])
+                base["related_tables"] = related_tables.get(sid, [])
+                base["related_rules"] = enr.get("related_rules", [])
+                functions.append(base)
+            elif sym.kind == "table":
+                base["type"] = "table"
+                tables.append(base)
+
+        files = sorted({str(s.file) for s in symbols})
+        files_yml = [{"id": f"file-{i}", "path": p} for i, p in enumerate(files)]
+
+        outputs: dict[str, list[Any]] = {
+            "entities/functions.yml": functions,
+            "entities/tables.yml": tables,
+            "entities/files.yml": files_yml,
+            "relations/call-graph.yml": rel_calls,
+            "relations/table-relations.yml": rel_tables,
+            "relations/rule-constraints.yml": [],
+        }
+        written = _atomic_write_tree(out_dir, outputs)
+        return EmitResult(files_written=written, diagnostics=[])
+
+
+def _resolve_out_dir(out_dir: Path) -> Path:
+    """The orchestrator passes ``<project>/.ai-memory`` already; treat any
+    other path as the project root and append the standard subdir."""
+    if out_dir.name == ".ai-memory":
+        return out_dir
+    return out_dir / ".ai-memory"
+
+
+def _atomic_write_tree(out_dir: Path, outputs: dict[str, list[Any]]) -> list[str]:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    written: list[str] = []
+    for rel, data in outputs.items():
+        target = out_dir / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=target.parent, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                yaml.safe_dump(data, fh, allow_unicode=True, sort_keys=False)
+            os.replace(tmp, target)
+        except Exception:
+            with contextlib.suppress(OSError):
+                os.unlink(tmp)
+            raise
+        written.append(rel)
+    return written

codemap_aimemory/enrich.py

@@ -0,0 +1,113 @@
+"""Optional LLM enrichment overlay.
+
+Two contract surfaces:
+
+* :func:`load_enrichment` — read every ``enrichment/*.yml`` in a folder,
+  return a ``symbol_id → payload dict`` map; missing folder → ``{}``. Used
+  by :class:`AiMemoryEmitter` to merge ``business_meaning`` /
+  ``related_rules`` at emit time.
+* :func:`enrich` — for every function/method symbol in the store, call the
+  injected ``LlmClient.describe(...)`` to produce the explanation payload
+  and write one file per symbol under ``enrichment/``. Files use a sha1
+  prefix of the SCIP id as the filename so re-runs are idempotent and
+  collision-free. ``changed_only=True`` skips symbols whose enrichment
+  file already exists.
+
+The core deterministic index never reads these files; only the emitter
+does, and even then only to fill the explanation slots — structural fields
+remain whatever the indexers + bridges produced.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Protocol
+
+import yaml
+
+from codemap.core.store import ReadOnlyStore
+
+__all__ = ["LlmClient", "enrich", "load_enrichment"]
+
+_FN_KINDS = frozenset({"method", "function"})
+
+
+class LlmClient(Protocol):
+    model: str
+
+    def describe(self, symbol: dict[str, Any]) -> dict[str, Any]: ...
+
+
+def load_enrichment(dir_: Path) -> dict[str, dict[str, Any]]:
+    if not dir_.exists():
+        return {}
+    out: dict[str, dict[str, Any]] = {}
+    for f in sorted(dir_.glob("*.yml")):
+        try:
+            data = yaml.safe_load(f.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError:
+            continue
+        sid = data.get("symbol_id")
+        if isinstance(sid, str):
+            out[sid] = data
+    return out
+
+
+def enrich(
+    store: ReadOnlyStore,
+    llm: LlmClient,
+    out_dir: Path,
+    *,
+    generated_at: str,
+    changed_only: bool = False,
+) -> list[str]:
+    enr_dir = _resolve_enr_dir(out_dir)
+    enr_dir.mkdir(parents=True, exist_ok=True)
+    existing = load_enrichment(enr_dir) if changed_only else {}
+    written: list[str] = []
+    for sym in store.iter_symbols():
+        if sym.kind not in _FN_KINDS:
+            continue
+        sid = str(sym.id)
+        if changed_only and sid in existing:
+            continue
+        result = llm.describe(
+            {
+                "symbol_id": sid,
+                "signature": sym.signature,
+                "file": str(sym.file),
+            }
+        )
+        payload = {
+            "symbol_id": sid,
+            "business_meaning": result.get("business_meaning"),
+            "related_rules": result.get("related_rules", []),
+            "confidence": "llm",
+            "source_model": llm.model,
+            "generated_at": generated_at,
+        }
+        target = enr_dir / f"{hashlib.sha1(sid.encode('utf-8')).hexdigest()[:12]}.yml"
+        fd, tmp = tempfile.mkstemp(dir=enr_dir, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                yaml.safe_dump(payload, fh, allow_unicode=True, sort_keys=False)
+            os.replace(tmp, target)
+        except Exception:
+            with contextlib.suppress(OSError):
+                os.unlink(tmp)
+            raise
+        written.append(target.name)
+    return written
+
+
+def _resolve_enr_dir(out_dir: Path) -> Path:
+    """Accept either ``<project>/.ai-memory`` or its ``enrichment`` subdir."""
+    if out_dir.name == "enrichment":
+        return out_dir
+    if out_dir.name == ".ai-memory":
+        return out_dir / "enrichment"
+    return out_dir / ".ai-memory" / "enrichment"

codemap_aimemory/ids.py

@@ -0,0 +1,63 @@
+"""Derive stable, unique ``entity_id`` slugs from SCIP symbol id strings.
+
+Rules:
+
+* base slug = ``{prefix}-{last_descriptor_name}`` where ``prefix`` is
+  decided by the symbol's kind via :func:`prefix_for` (fn / cls / tbl /
+  route / field / sym).
+* if multiple symbols collide on the same base slug (different SCIP ids
+  but same kind + last name), every entry in the collision group gets an
+  ``-<sha1[:8]>`` suffix derived from its SCIP id — never just the second
+  one, so the resulting ids stay stable when adding / removing symbols.
+* iteration order is sorted(symbol_ids) for determinism.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections import defaultdict
+
+from codemap.core.symbol import SymbolID
+
+__all__ = ["build_entity_ids", "prefix_for", "slug_base"]
+
+_PREFIX_BY_KIND: dict[str, str] = {
+    "method": "fn",
+    "function": "fn",
+    "class": "cls",
+    "interface": "cls",
+    "table": "tbl",
+    "route": "route",
+    "field": "field",
+    "sql_mapping": "sql",
+}
+
+
+def prefix_for(kind: str) -> str:
+    return _PREFIX_BY_KIND.get(kind, "sym")
+
+
+def slug_base(symbol_id_str: str) -> str:
+    return SymbolID.parse(symbol_id_str).descriptors[-1].name
+
+
+def build_entity_ids(
+    symbol_ids: list[str],
+    kinds: dict[str, str] | None = None,
+) -> dict[str, str]:
+    kinds = kinds or {}
+    base_of: dict[str, str] = {}
+    groups: defaultdict[str, list[str]] = defaultdict(list)
+    for sid in sorted(symbol_ids):
+        base = f"{prefix_for(kinds.get(sid, ''))}-{slug_base(sid)}"
+        base_of[sid] = base
+        groups[base].append(sid)
+    out: dict[str, str] = {}
+    for sid in symbol_ids:
+        base = base_of[sid]
+        if len(groups[base]) == 1:
+            out[sid] = base
+        else:
+            h = hashlib.sha1(sid.encode("utf-8")).hexdigest()[:8]
+            out[sid] = f"{base}-{h}"
+    return out

codemap_aimemory/llm.py

@@ -0,0 +1,205 @@
+"""Minimal OpenAI-compatible HTTP client for the optional ``codemap enrich``
+CLI command.
+
+Talks the OpenAI Chat Completions wire format, which both proper OpenAI,
+Anthropic-via-proxy, Ollama, vLLM, and most aggregators speak. The only
+runtime dependency is ``httpx`` (already widely co-installed with pydantic /
+Anthropic SDK families). The plugin's optional ``[llm]`` extra pulls the
+official ``anthropic`` SDK for users who want it instead — that path goes
+through :class:`AnthropicClient` below.
+
+The client satisfies the ``LlmClient`` Protocol in :mod:`codemap_aimemory.enrich`:
+
+    class LlmClient(Protocol):
+        model: str
+        def describe(self, symbol: dict[str, Any]) -> dict[str, Any]: ...
+
+``describe(symbol)`` returns ``{"business_meaning": str, "related_rules":
+list[str]}``. Network / parse failures degrade gracefully — both keys come
+back empty so the enrichment file still lands with the correct shape and
+the orchestrator never crashes a Plan-4 pipeline on a transient LLM hiccup.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+__all__ = ["AnthropicClient", "OpenAICompatibleClient", "build_client"]
+
+
+_SYSTEM_PROMPT = (
+    "You annotate code symbols for an internal knowledge graph. "
+    "For each symbol you receive, return STRICT JSON with exactly two keys: "
+    "`business_meaning` (a one-sentence Chinese or English description of "
+    "what the symbol does in business terms) and `related_rules` (a list of "
+    "short rule identifiers it implements; [] if none). Do not wrap the JSON "
+    "in markdown, do not add commentary, do not include any other keys."
+)
+
+
+class OpenAICompatibleClient:
+    """Works against any /v1/chat/completions endpoint (OpenAI, vLLM, Ollama
+    + ``--openai-api`` adapter, LM Studio, OneAPI / Higress aggregators)."""
+
+    def __init__(
+        self,
+        *,
+        model: str,
+        api_key: str,
+        base_url: str = "https://api.openai.com/v1",
+        timeout: float = 30.0,
+    ) -> None:
+        self.model = model
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    def describe(self, symbol: dict[str, Any]) -> dict[str, Any]:
+        try:
+            import httpx
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "codemap enrich requires httpx. Install with: pip install codemap-aimemory[llm]"
+            ) from exc
+
+        payload = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": _SYSTEM_PROMPT},
+                {
+                    "role": "user",
+                    "content": (
+                        f"Symbol: {symbol.get('symbol_id')}\n"
+                        f"Signature: {symbol.get('signature') or '(none)'}\n"
+                        f"File: {symbol.get('file')}\n"
+                        "Respond with the JSON object."
+                    ),
+                },
+            ],
+            "temperature": 0.0,
+            "response_format": {"type": "json_object"},
+        }
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+        }
+        try:
+            with httpx.Client(timeout=self._timeout) as client:
+                resp = client.post(
+                    f"{self._base_url}/chat/completions",
+                    json=payload,
+                    headers=headers,
+                )
+            resp.raise_for_status()
+            data = resp.json()
+            content = data["choices"][0]["message"]["content"]
+            parsed = json.loads(content)
+        except (httpx.HTTPError, KeyError, IndexError, json.JSONDecodeError, ValueError):
+            return {"business_meaning": None, "related_rules": []}
+        return {
+            "business_meaning": parsed.get("business_meaning"),
+            "related_rules": list(parsed.get("related_rules") or []),
+        }
+
+
+class AnthropicClient:
+    """Native Anthropic Messages API (`anthropic` SDK). Use this when the
+    project already depends on the official SDK; otherwise the OpenAI-compat
+    path covers Claude through the standard Bearer-token aggregators too."""
+
+    def __init__(
+        self,
+        *,
+        model: str,
+        api_key: str,
+        base_url: str | None = None,
+    ) -> None:
+        self.model = model
+        self._api_key = api_key
+        self._base_url = base_url
+
+    def describe(self, symbol: dict[str, Any]) -> dict[str, Any]:
+        try:
+            import anthropic  # type: ignore[import-not-found]
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "AnthropicClient requires the anthropic SDK. "
+                "Install with: pip install codemap-aimemory[llm]"
+            ) from exc
+
+        client_kwargs: dict[str, Any] = {"api_key": self._api_key}
+        if self._base_url:
+            client_kwargs["base_url"] = self._base_url
+        try:
+            client = anthropic.Anthropic(**client_kwargs)
+            response = client.messages.create(
+                model=self.model,
+                max_tokens=1024,
+                system=_SYSTEM_PROMPT,
+                messages=[
+                    {
+                        "role": "user",
+                        "content": (
+                            f"Symbol: {symbol.get('symbol_id')}\n"
+                            f"Signature: {symbol.get('signature') or '(none)'}\n"
+                            f"File: {symbol.get('file')}\n"
+                            "Respond with the JSON object only."
+                        ),
+                    }
+                ],
+            )
+            text = "".join(block.text for block in response.content if hasattr(block, "text"))
+            parsed = json.loads(text)
+        except Exception:  # pragma: no cover - depends on SDK errors
+            return {"business_meaning": None, "related_rules": []}
+        return {
+            "business_meaning": parsed.get("business_meaning"),
+            "related_rules": list(parsed.get("related_rules") or []),
+        }
+
+
+def build_client(
+    *,
+    backend: str,
+    model: str,
+    api_key: str,
+    base_url: str | None = None,
+) -> Any:
+    """Construct a client by backend keyword. Resolves OpenAI-style defaults.
+
+    ``backend``:
+      * ``"openai"`` / ``"openai-compatible"`` — :class:`OpenAICompatibleClient`,
+        default base_url ``https://api.openai.com/v1``
+      * ``"anthropic"`` — :class:`AnthropicClient` using the official SDK
+      * ``"ollama"`` — :class:`OpenAICompatibleClient`, default base_url
+        ``http://localhost:11434/v1``, ignores api_key
+    """
+    b = backend.lower()
+    if b in {"openai", "openai-compatible"}:
+        return OpenAICompatibleClient(
+            model=model,
+            api_key=api_key,
+            base_url=base_url or "https://api.openai.com/v1",
+        )
+    if b == "anthropic":
+        return AnthropicClient(model=model, api_key=api_key, base_url=base_url)
+    if b == "ollama":
+        return OpenAICompatibleClient(
+            model=model,
+            api_key=api_key or "ollama",
+            base_url=base_url or "http://localhost:11434/v1",
+        )
+    raise ValueError(f"unknown LLM backend {backend!r}; expected openai / anthropic / ollama")
+
+
+def env_default(*names: str) -> str | None:
+    """Return the first non-empty value among ``os.environ[name]`` for any
+    ``name`` in ``names``. Used to thread CLI options through environment
+    variables when the user doesn't pass them explicitly."""
+    for name in names:
+        value = os.environ.get(name)
+        if value:
+            return value
+    return None

codemap_aimemory-0.3.0.dist-info/METADATA

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: codemap-aimemory
+Version: 0.3.0
+Summary: Emit the four-layer memory model's L1 (.ai-memory/) from a CodeMap index
+Project-URL: Homepage, https://github.com/qxbyte/codemap
+Author: CodeMap Contributors
+License: MIT
+Keywords: ai-memory,codemap,emitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: codemap-core<0.4,>=0.3.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.39; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# codemap-aimemory
+
+Emits the [four-layer memory model](https://github.com/qxbyte/codemap)'s
+L1 (`.ai-memory/`) output from a CodeMap index.
+
+## What it writes
+
+```
+.ai-memory/
+├── entities/
+│   ├── functions.yml       fn-* / cls-* entities, with calls / called_by /
+│   │                       related_tables / signature / line_range
+│   ├── tables.yml          tbl-* entities
+│   └── files.yml           file-* entities
+├── relations/
+│   ├── call-graph.yml      from / to / type=calls / confidence
+│   ├── table-relations.yml from / to / type=accesses_table / confidence
+│   └── rule-constraints.yml (empty; managed by L2)
+└── enrichment/             optional LLM overlay (one file per enriched
+                            symbol, loaded by the emitter to fill
+                            business_meaning / related_rules)
+```
+
+All writes are atomic per file (tmp + rename), so an Agent reading
+`.ai-memory/` never sees a half-written tree.
+
+## Two-layer separation
+
+The core L1 output (above) is purely deterministic — no LLM. The optional
+`enrich` CLI fills `business_meaning` / `related_rules` into separate
+`enrichment/*.yml` files. The emitter merges enrichment values when it
+re-emits, but the core JSON-store index never carries explanation text.

codemap_aimemory-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+codemap_aimemory/__init__.py,sha256=4pw3riA5cPNsFbeEBC64VhwKBqFj7RkRiBChAwW-oYE,140
+codemap_aimemory/cli.py,sha256=o9mRy7rqwLLHlmhhbjvNFM6X8jN6JGIlCXGw7OTAsag,5483
+codemap_aimemory/emitter.py,sha256=R7mrNDS6JalfqsXWAFGQMuDOahuIG_6FHWBa821vcyA,7614
+codemap_aimemory/enrich.py,sha256=TLl5kPjZbyE55KIDq95996tTPY8w8wcVsuwvpHLMqL0,3604
+codemap_aimemory/ids.py,sha256=AYNbBno1U47IpLBqY8amIqpUMngqSM4BUIesAOOdUcE,1866
+codemap_aimemory/llm.py,sha256=FVfrZvaFNcQzIAbUquOXw7dY2jV5RnCrJeB13xclXrc,7717
+codemap_aimemory-0.3.0.dist-info/METADATA,sha256=8hQPKznDmyPp4CdhYvazWK-6eNLrdz9MXmJ0T2hIehc,2056
+codemap_aimemory-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+codemap_aimemory-0.3.0.dist-info/entry_points.txt,sha256=ex8A_irptUKBNzUDA9giikrK8ZQ5umw7xQiJSGCxiLM,135
+codemap_aimemory-0.3.0.dist-info/RECORD,,

codemap_aimemory-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

codemap_aimemory-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[codemap.cli_commands]
+enrich = codemap_aimemory.cli:register
+
+[codemap.emitters]
+ai-memory = codemap_aimemory.emitter:AiMemoryEmitter