lorebase-herald 0.2.3__tar.gz

lorebase_herald-0.2.3/.gitignore

@@ -0,0 +1,79 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.venv/
+venv/
+.python-eggs/
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+*.prof
+
+# Node
+node_modules/
+.pnpm-store/
+.npm/
+.yarn/
+!.yarn/releases
+.pnp.*
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.vite/
+*.tsbuildinfo
+apps/web/dist/
+apps/web/.vitest/
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+secrets/
+
+# Docker
+docker-compose.override.yaml
+docker-compose.override.yml
+.docker/
+
+# Data and local artifacts
+*.sqlite
+*.db
+/tmp/
+/data/
+tests/perf/results/
+
+# Editors and OS
+.idea/
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.example.json
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+*.code-workspace
+.history/
+
+# Session worktrees
+.claude/

lorebase_herald-0.2.3/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.5
+Name: lorebase-herald
+Version: 0.2.3
+Summary: Lorebase Herald: MCP server over the Keeper REST API
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: lorebase-client<0.3,>=0.2
+Requires-Dist: lorebase-platform<0.3,>=0.2
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: opentelemetry-api>=1.25
+Requires-Dist: pydantic>=2.7

lorebase_herald-0.2.3/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "lorebase-herald"
+version = "0.2.3"
+description = "Lorebase Herald: MCP server over the Keeper REST API"
+requires-python = ">=3.12"
+# mcp: the official Model Context Protocol SDK (tools, resources and prompts; stdio and
+#   Streamable HTTP transports; in-memory client sessions for tests).
+# lorebase-client: the typed client of Keeper's REST API (requests, models, errors, retries).
+# httpx: transport options of that client (TLS verification, test transports).
+# pydantic: tool input schemas and the `herald` settings section.
+# opentelemetry-api: trace context of Herald's own spans, propagated to Keeper as `traceparent`.
+# lorebase-platform: layered settings, secret references and structured logging.
+dependencies = [
+  "lorebase-platform>=0.2,<0.3",
+  "lorebase-client>=0.2,<0.3",
+  "mcp>=2.3,<3",
+  "httpx>=0.27",
+  "opentelemetry-api>=1.25",
+  "pydantic>=2.7",
+]
+
+[project.scripts]
+lorebase-herald = "lorebase_herald.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lorebase_herald"]

lorebase_herald-0.2.3/src/lorebase_herald/__init__.py

@@ -0,0 +1,3 @@
+"""Lorebase Herald: MCP server exposing a Lorebase Domain through Keeper's REST API."""
+
+__version__ = "0.2.3"

lorebase_herald-0.2.3/src/lorebase_herald/__main__.py

@@ -0,0 +1,40 @@
+"""Run Herald: `lorebase-herald` or `python -m lorebase_herald`.
+
+The transport (stdio or Streamable HTTP) and everything else come from the `herald` settings.
+Logs go to stderr: on stdio, stdout carries the MCP protocol.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import sys
+
+from lorebase_herald.keeper import KeeperClients
+from lorebase_herald.server import serve
+from lorebase_herald.settings import herald_settings
+from lorebase_platform.logging import configure_logging
+from lorebase_platform.settings import ConfigError, load_settings
+
+SERVICE_NAME = "herald"
+
+
+def main() -> None:
+    """Load settings, configure logging and serve until the host disconnects."""
+    try:
+        settings = load_settings()
+        herald = herald_settings(settings)
+    except ConfigError as exc:
+        sys.exit(str(exc))
+    configure_logging(settings.logging, service=SERVICE_NAME, stream=sys.stderr)
+    # httpx logs every Keeper request URL at INFO; keep it quiet so record keys stay out of the
+    # logs (on stdio they would land in the agent's stderr).
+    for name in ("httpx", "httpcore"):
+        logging.getLogger(name).setLevel(logging.WARNING)
+    with contextlib.suppress(KeyboardInterrupt):
+        asyncio.run(serve(herald, KeeperClients(herald.keeper)))
+
+
+if __name__ == "__main__":
+    main()

lorebase_herald-0.2.3/src/lorebase_herald/errors.py

@@ -0,0 +1,173 @@
+"""Client errors mapped to tool errors a model can act on.
+
+A tool error is one short text: `[code] what happened` followed by `next:` with the action
+that resolves it. `code` is Keeper's stable problem code (design 11.2: machine-readable code
+and a short human message), or a Herald code for failures before Keeper answers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+import httpx
+from mcp.server.mcpserver.exceptions import ToolError
+from pydantic import ValidationError
+
+from lorebase_client import (
+    ApiError,
+    AuthenticationError,
+    IdempotencyConflictError,
+    LorebaseConnectionError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProtectedBranchError,
+    RateLimitedError,
+    ReviewRequiredError,
+    ServerError,
+    StaleHeadError,
+    ValidationFailedError,
+)
+
+HintFactory = Callable[[ApiError], str]
+
+
+def _stale_head(error: ApiError) -> str:
+    current = error.current_head
+    return (
+        f"the branch head is now {current}; re-read what the change depends on, then retry "
+        f"with expected_head={current}"
+        if current
+        else "re-read the branch head and retry"
+    )
+
+
+def _review(error: ApiError) -> str:
+    proposals = error.extra.get("proposals")
+    where = f" ({proposals})" if proposals else ""
+    return (
+        "this change needs review: call again with task and intent so that Keeper runs it on "
+        "a task branch and opens the Proposal, or run it on a work branch yourself and open a "
+        f"Proposal for that branch{where}; do not retry here as it is"
+    )
+
+
+def _retry_later(error: ApiError) -> str:
+    after = error.retry_after if error.retry_after is not None else error.extra.get("retry_after")
+    if after is None:
+        return "retry later"
+    seconds = f"{after:g}" if isinstance(after, int | float) else after
+    return f"retry after {seconds} s"
+
+
+# Codes that no exception class of the client stands for.
+HINTS_BY_CODE: Mapping[str, HintFactory] = {
+    "expressions-not-enabled": lambda _: "this Operation cannot run on this deployment",
+    "branch-not-materialized": lambda _: "read this branch at a Revision with `at`",
+    "limit-exceeded": lambda _: "narrow the request",
+}
+# Most specific class first.
+HINTS_BY_TYPE: tuple[tuple[type[ApiError], HintFactory], ...] = (
+    (StaleHeadError, _stale_head),
+    (ReviewRequiredError, _review),
+    (ProtectedBranchError, _review),
+    (IdempotencyConflictError, lambda _: "use a new idempotency_key for different parameters"),
+    (ValidationFailedError, lambda _: "fix the listed members and call again"),
+    (
+        NotFoundError,
+        lambda _: "check the ref with lorebase_search or names with lorebase_schema",
+    ),
+    (PermissionDeniedError, lambda _: "this agent's API key lacks the permission; do not retry"),
+    (AuthenticationError, lambda _: "the agent's API key is missing, expired or revoked"),
+    (RateLimitedError, _retry_later),
+    (ServerError, _retry_later),
+)
+
+
+def _hint(error: ApiError) -> HintFactory | None:
+    by_code = HINTS_BY_CODE.get(error.code or "")
+    if by_code is not None:
+        return by_code
+    return next((hint for kind, hint in HINTS_BY_TYPE if isinstance(error, kind)), None)
+
+
+def _issues(extra: Mapping[str, Any], limit: int) -> list[str]:
+    """Validation findings (`issues`) or request member errors (`errors`), one line each."""
+    lines: list[str] = []
+    found = extra.get("issues") or extra.get("errors") or []
+    if not isinstance(found, list):
+        return lines
+    for issue in found[:limit]:
+        if not isinstance(issue, Mapping):
+            continue
+        where = issue.get("pointer") or "/".join(str(p) for p in issue.get("path") or [])
+        code = issue.get("code")
+        subject = "/".join(
+            str(issue[k]) for k in ("kind", "key", "attribute") if issue.get(k) is not None
+        )
+        location = " ".join(part for part in (where, f"({subject})" if subject else "") if part)
+        suffix = f" [{code}]" if code else ""
+        lines.append(f"- {location or '<request>'}: {issue.get('message', '')}{suffix}")
+    total = extra.get("issue_count")
+    if isinstance(total, int) and total > len(lines):
+        lines.append(f"- ... {total - len(lines)} more")
+    elif len(found) > limit:
+        lines.append(f"- ... {len(found) - limit} more")
+    return lines
+
+
+def tool_error(error: ApiError | LorebaseConnectionError, *, max_issues: int) -> ToolError:
+    """The tool error answering a failed Keeper call."""
+    if isinstance(error, LorebaseConnectionError):
+        return ToolError(f"[keeper-unavailable] {_unreachable(error)}. next: retry later")
+    # A problem always has a code; an answer without one is not Keeper's (a proxy, say) and its
+    # body is no message for a model.
+    message = (error.detail or error.title) if error.code else error.title
+    lines = [f"[{error.code or f'http-{error.status}'}] {message or 'Error'}"]
+    lines.extend(_issues(error.extra, max_issues))
+    hint = _hint(error)
+    if hint is not None:
+        lines.append(f"next: {hint(error)}")
+    return ToolError("\n".join(lines))
+
+
+def _unreachable(error: LorebaseConnectionError) -> str:
+    cause = error.__cause__
+    if isinstance(cause, httpx.TimeoutException):
+        return "Keeper did not answer in time"
+    return f"Keeper is unreachable ({type(cause).__name__ if cause else 'no connection'})"
+
+
+def _findings(error: ValidationError, limit: int) -> list[str]:
+    found = error.errors(include_url=False, include_context=False, include_input=False)
+    lines = [
+        f"- {'/'.join(str(p) for p in finding['loc']) or '<request>'}: {finding['msg']} "
+        f"[{finding['type']}]"
+        for finding in found[:limit]
+    ]
+    if len(found) > limit:
+        lines.append(f"- ... {len(found) - limit} more")
+    return lines
+
+
+def invalid_request(error: ValidationError, *, max_issues: int) -> ToolError:
+    """The tool error for a request the client's models refuse before anything is sent."""
+    lines = ["[validation-failed] the request is not valid", *_findings(error, max_issues)]
+    lines.append("next: fix the listed members and call again")
+    return ToolError("\n".join(lines))
+
+
+def unexpected_answer(error: ValidationError) -> ToolError:
+    """The tool error for an answer that does not fit the client's response models."""
+    first = error.errors(include_url=False, include_context=False, include_input=False)[0]
+    where = "/".join(str(p) for p in first["loc"])
+    return ToolError(
+        f"[keeper-response-invalid] Keeper's answer does not fit this Herald's API model "
+        f"({error.error_count()} problems, first at {where}: {first['msg']}).\n"
+        "next: use matching Herald and Keeper versions"
+    )
+
+
+def invalid_input(code: str, message: str, hint: str) -> ToolError:
+    """A tool error raised by Herald before calling Keeper."""
+    return ToolError(f"[{code}] {message}\nnext: {hint}")

lorebase_herald-0.2.3/src/lorebase_herald/keeper.py

@@ -0,0 +1,64 @@
+"""Keeper access for the tools: one typed Lorebase client per request.
+
+Herald reaches Lorebase only through Keeper (AC-20), so authorization, masking, audit and rate
+limits are enforced in one place. Every client carries the credential of the calling agent and
+nothing else: no client is shared between requests, so no credential, connection or cached
+answer can cross from one caller to another.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+import httpx
+
+from lorebase_client import AsyncLorebaseClient, RetryPolicy
+from lorebase_herald.settings import KeeperConnection
+from lorebase_herald.tracing import call_headers, stamp_request
+
+
+def bearer_token(credential: str | None) -> str | None:
+    """The token of a credential: a forwarded `Bearer ...` value or a bare API key."""
+    if credential is None:
+        return None
+    scheme, _, rest = credential.partition(" ")
+    return rest.strip() if rest and scheme.lower() == "bearer" else credential
+
+
+class KeeperClients:
+    """Opens the client of one request. `transport` replaces the network (tests)."""
+
+    def __init__(
+        self, connection: KeeperConnection, *, transport: httpx.AsyncBaseTransport | None = None
+    ) -> None:
+        self._connection = connection
+        self._transport = transport
+
+    def _transport_for_request(self) -> httpx.AsyncBaseTransport | None:
+        if self._transport is None and not self._connection.verify_tls:
+            return httpx.AsyncHTTPTransport(verify=False)
+        return self._transport
+
+    @asynccontextmanager
+    async def open(self, credential: str | None) -> AsyncIterator[AsyncLorebaseClient]:
+        """A client for one request, closed afterwards. With no credential, requests go out
+        anonymous: the client reads no key from the environment. It carries the trace headers of
+        the tool call being served; each of its requests gets a span of its own (see
+        `lorebase_herald.tracing`)."""
+        connection = self._connection
+        async with AsyncLorebaseClient(
+            connection.base_url,
+            api_key=bearer_token(credential),
+            api_prefix=connection.api_prefix,
+            timeout=connection.timeout_s,
+            retry=RetryPolicy(
+                max_retries=connection.max_retries, backoff_max_s=connection.retry_max_wait_s
+            ),
+            headers={"User-Agent": connection.user_agent, **(call_headers.get() or {})},
+            transport=self._transport_for_request(),
+            event_hooks={"request": [stamp_request]},
+            trust_env=connection.trust_env,
+            env={},
+        ) as client:
+            yield client

lorebase_herald-0.2.3/src/lorebase_herald/prompts.py

@@ -0,0 +1,45 @@
+"""Server instructions and the `lorebase_guide` prompt template (no model calls)."""
+
+from __future__ import annotations
+
+INSTRUCTIONS = """\
+Lorebase is a versioned knowledge graph: typed Records (refs `Kind/key`) linked by Relations,
+on branches of immutable Revisions. Workflow:
+1. Orient: lorebase_context (records or a question) or lorebase_schema.
+2. Read narrowly: lorebase_get, lorebase_query, lorebase_search, lorebase_neighborhood;
+   lorebase_explain / lorebase_lineage for where a value came from; lorebase_history for a
+   Record's changes; lorebase_changes / lorebase_diff for history.
+3. Write only with lorebase_execute: dry_run first (the default), then dry_run=false with
+   expected_head. Some Operations need review: pass task and intent and Keeper opens the
+   Proposal on a task branch for you.
+Outputs carry the Revision they were read at and say when they were cut."""
+
+GUIDE = """\
+You are working with the Lorebase Domain {domain}.
+
+How to use Lorebase:
+- Records are addressed as `Kind/key` (for example `Supplier/S-1001`); use api names exactly as
+  lorebase_schema prints them.
+- Start with lorebase_context: pass the Records the task is about, or a short question; it
+  returns those Records, their links, nearby Records and the schema of the Kinds involved,
+  within a token budget.
+- Then read only what you need: lorebase_get for one Record, lorebase_query for filtered lists
+  (JSON DSL), lorebase_search to find Records by words, lorebase_neighborhood for links.
+- Facts carry provenance: lorebase_explain shows who or what set each value and when.
+- History: lorebase_changes lists Revisions since one you saw; lorebase_diff compares two.
+- Writes go only through governed Operations with lorebase_execute. Always dry-run first
+  (dry_run is true by default), check edits and violations, then commit with dry_run=false and
+  expected_head set to the head the dry run reported. A `review-required` or
+  `protected-branch` error means the change must go through a Proposal: repeat the call with
+  `task` and `intent` and send an `idempotency_key`; Keeper opens the Proposal on a task branch.
+- Errors start with `[code]` and end with `next:`; follow that step instead of retrying blindly.
+- Outputs are cut at a size limit and say so; narrow the request or follow `next_cursor`.
+{task}"""
+
+
+def guide(domain: str | None, task: str | None) -> str:
+    """The guide text for a Domain and, optionally, the task at hand."""
+    return GUIDE.format(
+        domain=domain or "configured for this server",
+        task=f"\nTask: {task}" if task else "",
+    )

lorebase_herald-0.2.3/src/lorebase_herald/render.py

@@ -0,0 +1,82 @@
+"""Rendering helpers shared by the tools: compact values, list caps and size caps.
+
+Text output is written for a model's context window: one fact per line, `Kind/key` refs,
+no decoration. Every cut is visible: lists end with `... N more` and over-long outputs end
+with a `[truncated ...]` marker, never a silent cut.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from datetime import datetime
+from typing import Any
+
+from pydantic import TypeAdapter
+
+from lorebase_herald.settings import OutputSettings
+
+ELLIPSIS = "…"
+_TIMESTAMP = TypeAdapter(datetime)
+
+
+def ref(kind: str, key: str) -> str:
+    """The `Kind/key` reference of a Record."""
+    return f"{kind}/{key}"
+
+
+def as_json(value: Any) -> str:
+    """Compact JSON (no spaces, UTF-8 kept)."""
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False, default=str)
+
+
+def timestamp(value: datetime) -> str:
+    """A timestamp as the API writes it: RFC 3339, `Z` for UTC."""
+    return str(_TIMESTAMP.dump_python(value, mode="json"))
+
+
+def value_text(value: Any, max_chars: int) -> str:
+    """A value on one line: strings as they are, other values as compact JSON."""
+    text = value if isinstance(value, str) else as_json(value)
+    text = text.replace("\n", " ")
+    return text if len(text) <= max_chars else text[: max_chars - 1] + ELLIPSIS
+
+
+def values_text(values: Mapping[str, Any], max_chars: int, separator: str = "; ") -> str:
+    """`name=value` pairs on one line."""
+    return separator.join(f"{k}={value_text(v, max_chars)}" for k, v in values.items())
+
+
+def titled(reference: str, title: str | None) -> str:
+    return f'{reference} "{title}"' if title else reference
+
+
+def capped[T](items: Sequence[T], limit: int) -> tuple[list[T], int]:
+    """The first `limit` items and how many were left out."""
+    return list(items[:limit]), max(0, len(items) - limit)
+
+
+def more_line(omitted: int, hint: str = "") -> list[str]:
+    """`... N more` when items were left out."""
+    if omitted <= 0:
+        return []
+    return [f"... {omitted} more{f' ({hint})' if hint else ''}"]
+
+
+def finish(text: str, output: OutputSettings) -> str:
+    """Cut an output longer than `max_chars` at a line break, with a marker saying so."""
+    if len(text) <= output.max_chars:
+        return text
+    budget = output.max_chars - 120
+    cut = text.rfind("\n", 0, budget)
+    cut = budget if cut <= 0 else cut
+    omitted = len(text) - cut
+    return (
+        text[:cut] + f"\n[truncated: {omitted} more chars; narrow the request, lower `limit` "
+        "or follow `next_cursor`]"
+    )
+
+
+def render(view: Mapping[str, Any], text: str, fmt: str, output: OutputSettings) -> str:
+    """The final tool output: compact JSON of `view` or `text`, within the size cap."""
+    return finish(as_json(view) if fmt == "json" else text, output)