spineforge 0.1.0__py3-none-any.whl

spineforge/__init__.py

@@ -0,0 +1,422 @@
+"""
+spineforge
+~~~~~~~~~~
+
+AI agent identity and observability SDK.
+
+Quick start::
+
+    import spineforge
+
+    spine = spineforge.init(agent_name="my-agent")
+
+    with spine.run(input=user_query) as run:
+        result = do_agent_work(user_query)
+        run.set_output(result)
+
+For tool functions not auto-captured by an instrumentor::
+
+    @spineforge.track_tool
+    def call_tool(name: str, query: str) -> str:
+        ...
+
+Public API:
+    init(agent_name, **kwargs) → Spine
+    track_tool(func)           → decorated func
+    Spine                      — agent identity + instrumentation handle
+    Run                        — context manager for a single agent invocation
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+import logging
+from datetime import datetime, timezone
+from typing import Any, Optional
+from uuid import uuid4
+
+from spineforge.config import SpineforgeConfig
+from spineforge.decorators import track_tool
+from spineforge.identity import SpineIdentity, resolve_or_create
+from spineforge.instrumentation import setup_instrumentation
+from spineforge.models import RunEvent
+from spineforge.sinks import ConsoleSink, FileSink, Sink
+from spineforge.span_processor import SpineforgeSpanProcessor, current_run_id
+
+logger = logging.getLogger(__name__)
+
+# Re-export public names
+__all__ = ["init", "track_tool", "Spine", "Run", "__version__"]
+
+
+# ── Run context manager ────────────────────────────────────────────────────
+
+
+class Run:
+    """Context manager representing a single top-level agent invocation.
+
+    Groups all LLM calls and tool calls that happen within the ``with``
+    block under one ``run_id``. This maps to a row in the future ``runs``
+    table.
+
+    Usage::
+
+        with spine.run(input="user question") as run:
+            result = agent.invoke(...)
+            run.set_output(result)
+    """
+
+    def __init__(self, spine: Spine, input: str = "") -> None:
+        self.run_id: str = str(uuid4())
+        self._spine = spine
+        self._input = input
+        self._output: Optional[str] = None
+        self._error: Optional[str] = None
+        self._started_at: Optional[str] = None
+        self._run_id_token: Any = None  # ContextVar token for reset
+
+    def set_output(self, output: Any) -> None:
+        """Record the final output of this run."""
+        self._output = str(output) if output is not None else None
+
+    def __enter__(self) -> Run:
+        """Start the run: emit a 'running' event and set the run_id context."""
+        self._started_at = datetime.now(timezone.utc).isoformat()
+
+        # Set the ContextVar so SpineforgeSpanProcessor.on_start() can
+        # stamp this run_id onto every span created during the run.
+        self._run_id_token = current_run_id.set(self.run_id)
+
+        # Emit the "run started" event
+        event = RunEvent(
+            run_id=self.run_id,
+            spine_id=self._spine.spine_id,
+            agent_name=self._spine.agent_name,
+            started_at=self._started_at,
+            status="running",
+            input=self._input,
+        )
+        self._spine._emit_event(event.to_dict())
+
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        """End the run: flush telemetry and emit the final 'run' event."""
+        ended_at = datetime.now(timezone.utc).isoformat()
+
+        # Determine status
+        if exc_type is not None:
+            status = "error"
+            self._error = str(exc_val) if exc_val else str(exc_type.__name__)
+        else:
+            status = "success"
+
+        # Force-flush the TracerProvider so all in-flight spans from this
+        # run are processed BEFORE we emit the run-end event. This ensures
+        # correct ordering in the JSONL log (all actions before run-end).
+        if self._spine._provider:
+            try:
+                self._spine._provider.force_flush(timeout_millis=5000)
+            except Exception:
+                pass
+
+        # Emit the "run completed/errored" event
+        event = RunEvent(
+            run_id=self.run_id,
+            spine_id=self._spine.spine_id,
+            agent_name=self._spine.agent_name,
+            started_at=self._started_at or ended_at,
+            ended_at=ended_at,
+            status=status,
+            input=self._input,
+            output=self._output,
+            error=self._error,
+        )
+        self._spine._emit_event(event.to_dict())
+
+        # Flush sinks so the run-end event is written immediately
+        for sink in self._spine._sinks:
+            try:
+                sink.flush()
+            except Exception:
+                pass
+
+        # Reset the ContextVar
+        if self._run_id_token is not None:
+            current_run_id.reset(self._run_id_token)
+            self._run_id_token = None
+
+        return False  # Never suppress exceptions
+
+
+# ── Spine (agent handle) ───────────────────────────────────────────────────
+
+
+class Spine:
+    """Initialised agent identity + instrumentation handle.
+
+    Created by ``spineforge.init()``. Holds the resolved Spine ID, the
+    OTel TracerProvider, the list of active sinks, and (when a registry
+    backend is configured) the registry client for token/credential ops.
+    """
+
+    def __init__(
+        self,
+        identity: SpineIdentity,
+        provider: Any,  # TracerProvider
+        sinks: list[Sink],
+        processor: SpineforgeSpanProcessor,
+        config: SpineforgeConfig,
+        registry_client: Optional[Any] = None,  # RegistryClient
+        private_key_pem: Optional[str] = None,
+    ) -> None:
+        self.agent_name = identity.agent_name
+        self.spine_id = identity.spine_id
+        self.created_at = identity.created_at
+        self._identity = identity
+        self._provider = provider
+        self._sinks = sinks
+        self._processor = processor
+        self._config = config
+        self._registry_client = registry_client
+        self._private_key_pem = private_key_pem
+
+    def run(self, input: str = "") -> Run:
+        """Create a new Run context manager.
+
+        Usage::
+
+            with spine.run(input="user question") as run:
+                result = agent.invoke(...)
+                run.set_output(result)
+        """
+        return Run(self, input=input)
+
+    def lease_credential(self, secret_name: str) -> str:
+        """Lease a provider secret from the registry backend.
+
+        Handles scoped token acquisition and token refresh automatically.
+        Returns the raw secret value.
+
+        Args:
+            secret_name: Name of the secret (e.g. "groq-api-key").
+
+        Returns:
+            The decrypted secret value (e.g. the actual Groq API key).
+
+        Raises:
+            RuntimeError if no registry is configured.
+            RegistryError on network/auth failures.
+        """
+        if not self._registry_client:
+            raise RuntimeError(
+                "Cannot lease credentials — no registry URL configured. "
+                "Set SPINEFORGE_REGISTRY_URL to enable."
+            )
+        if not self._private_key_pem:
+            raise RuntimeError("No private key available for credential leasing")
+
+        value, _expires_at = self._registry_client.lease_credential(
+            secret_name=secret_name,
+            spine_id=self.spine_id,
+            private_key_pem=self._private_key_pem,
+        )
+        return value
+
+    def request_token(
+        self,
+        scopes: list[str],
+        aud: str | None = None,
+    ) -> str:
+        """Request a scoped access token from the registry.
+
+        Wraps the RFC 7523 assertion flow, adding ``scopes`` and ``aud``
+        to the token request.
+
+        Args:
+            scopes: List of scope strings (must be a subset of the agent's
+                    allowed scopes declared at registration time).
+            aud: Audience claim.  Defaults to ``"registry"`` for credential
+                 lease flows.  Set to a target agent's spine_id for
+                 agent-to-agent calls.
+
+        Returns:
+            The issued JWT string.
+
+        Raises:
+            RuntimeError if no registry is configured.
+            RegistryError if scopes are not granted or other failure.
+        """
+        if not self._registry_client:
+            raise RuntimeError(
+                "Cannot request token — no registry URL configured. "
+                "Set SPINEFORGE_REGISTRY_URL to enable."
+            )
+        if not self._private_key_pem:
+            raise RuntimeError("No private key available for token request")
+
+        return self._registry_client.request_token(
+            spine_id=self.spine_id,
+            private_key_pem=self._private_key_pem,
+            scopes=scopes,
+            aud=aud,
+        )
+
+    def _emit_event(self, event_dict: dict) -> None:
+        """Route an event dict through all sinks."""
+        for sink in self._sinks:
+            try:
+                sink.emit(event_dict)
+            except Exception as exc:
+                logger.warning("Sink error: %s", exc)
+
+    def __repr__(self) -> str:
+        return (
+            f"Spine(agent_name={self.agent_name!r}, "
+            f"spine_id={self.spine_id[:8]}…)"
+        )
+
+
+# ── init() — the one-call entry point ──────────────────────────────────────
+
+
+def init(
+    agent_name: str,
+    allowed_scopes: list[str] | None = None,
+    **kwargs,
+) -> Spine:
+    """Initialise Spineforge for an agent.
+
+    This is the single entry point for the SDK.  It:
+
+    1. Resolves (or creates) a stable Spine ID for ``agent_name``
+    2. If a registry URL is configured:
+       a. Generates/loads an Ed25519 keypair (private key stays local)
+       b. Registers with the backend (sends public key, gets spine_id)
+       c. Creates a registry client for token/credential operations
+    3. Configures OpenTelemetry with our custom TracerProvider
+    4. Activates OpenLLMetry instrumentors (Groq, LangChain, etc.)
+    5. Returns a ``Spine`` handle for creating runs
+
+    Args:
+        agent_name: Human-readable agent identifier. Same name → same
+                    Spine ID across runs (persisted in registry.json).
+        allowed_scopes: Scopes declared by the agent developer at registration time.
+                        Passed to the backend so the agent can later request tokens
+                        for these scopes.
+        **kwargs: Override any ``SpineforgeConfig`` field (data_dir,
+                  log_file, verbose, trace_content, registry_url).
+
+    Returns:
+        A ``Spine`` instance. Use ``spine.run(input=...)`` to group
+        actions into runs.
+
+    Example::
+
+        import spineforge
+
+        spine = spineforge.init(agent_name="research-agent")
+
+        with spine.run(input=query) as run:
+            result = run_agent(query)
+            run.set_output(result)
+    """
+    # 1. Load config from env + overrides
+    config = SpineforgeConfig.from_env(**kwargs)
+    config.ensure_dirs()
+
+    # 2. Resolve/create identity (generates keypair if registry_url is set)
+    identity = resolve_or_create(agent_name, config)
+
+    # 3. Registry integration (if configured)
+    registry_client = None
+    private_key_pem = None
+
+    if config.registry_url:
+        from spineforge.registry_client import RegistryClient, RegistryError
+        from spineforge.identity import get_or_create_keypair
+
+        private_key_pem, public_key_pem = get_or_create_keypair(config)
+        registry_client = RegistryClient(config.registry_url)
+
+        try:
+            # Register with the backend → get the server-assigned spine_id
+            server_spine_id = registry_client.register(
+                agent_name,
+                public_key_pem,
+                allowed_scopes=allowed_scopes,
+            )
+
+            # Update identity to use the server-assigned spine_id
+            # (may differ from the locally-generated one)
+            identity = SpineIdentity(
+                agent_name=agent_name,
+                spine_id=server_spine_id,
+                created_at=identity.created_at,
+                public_key_pem=public_key_pem,
+            )
+
+            if config.verbose:
+                print(
+                    f"🔐 Registered with Spineforge registry: "
+                    f"spine_id={server_spine_id[:8]}…",
+                    flush=True,
+                )
+        except RegistryError as exc:
+            # Graceful degradation: log warning, continue with local identity
+            logger.warning(
+                "Could not reach registry at %s — continuing in offline mode: %s",
+                config.registry_url,
+                exc,
+            )
+            if config.verbose:
+                print(
+                    f"⚠️  Registry unreachable — running in offline mode",
+                    flush=True,
+                )
+            registry_client = None
+            private_key_pem = None
+
+    # 4. Create sinks
+    sinks: list[Sink] = []
+    sinks.append(ConsoleSink(config))
+    file_sink = FileSink(config)
+    sinks.append(file_sink)
+
+    # If the registry is available, add APISink with FileSink as fallback
+    if registry_client:
+        from spineforge.sinks import APISink
+
+        api_sink = APISink(
+            config=config,
+            registry_client=registry_client,
+            spine_id=identity.spine_id,
+            private_key_pem=private_key_pem,
+            fallback_sink=file_sink,
+        )
+        sinks.append(api_sink)
+
+    # 5. Set up OTel pipeline (TracerProvider + instrumentors)
+    provider, processor = setup_instrumentation(identity, config, sinks)
+
+    # 6. Log startup
+    if config.verbose:
+        print(
+            f"🦴 Spineforge initialised: "
+            f"agent={agent_name!r}  "
+            f"spine_id={identity.spine_id[:8]}…  "
+            f"log={config.log_path}"
+            + (f"  registry={config.registry_url}" if config.registry_url else ""),
+            flush=True,
+        )
+
+    return Spine(
+        identity=identity,
+        provider=provider,
+        sinks=sinks,
+        processor=processor,
+        config=config,
+        registry_client=registry_client,
+        private_key_pem=private_key_pem,
+    )

spineforge/config.py

@@ -0,0 +1,122 @@
+"""
+spineforge.config
+~~~~~~~~~~~~~~~~~
+
+Environment-configurable settings for the Spineforge SDK.
+
+All settings can be overridden via environment variables or passed directly
+to ``spineforge.init()``. Env vars take lowest precedence (kwargs win).
+
+Environment Variables:
+    SPINEFORGE_DATA_DIR       Base directory for .spineforge/ (default: CWD)
+    SPINEFORGE_LOG_FILE       JSONL log filename (default: actions.jsonl)
+    SPINEFORGE_VERBOSE        Enable console output (default: true)
+    SPINEFORGE_TRACE_CONTENT  Capture prompt/completion text (default: true)
+    SPINEFORGE_REGISTRY_URL   Registry backend URL (default: empty = offline mode)
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def _env_bool(key: str, default: bool = True) -> bool:
+    """Read a boolean from an environment variable (true/1/yes → True)."""
+    val = os.environ.get(key, "").strip().lower()
+    if not val:
+        return default
+    return val in ("true", "1", "yes")
+
+
+@dataclass(frozen=True)
+class SpineforgeConfig:
+    """Immutable configuration snapshot for a Spineforge session."""
+
+    # Base directory where .spineforge/ is created (registry + logs)
+    data_dir: Path = field(default_factory=lambda: Path.cwd())
+
+    # Filename for the JSONL action log (inside {data_dir}/.spineforge/logs/)
+    log_file: str = "actions.jsonl"
+
+    # Whether to print human-readable event lines to stdout
+    verbose: bool = True
+
+    # Whether to include prompt/completion content in logged events
+    trace_content: bool = True
+
+    # URL of the Spineforge registry backend.
+    # Empty string = offline mode (local registry.json only, no crypto identity).
+    registry_url: str = ""
+
+    # ── Derived paths (computed, not configurable directly) ──────────────
+
+    @property
+    def spineforge_dir(self) -> Path:
+        """The .spineforge/ directory under data_dir."""
+        return self.data_dir / ".spineforge"
+
+    @property
+    def registry_path(self) -> Path:
+        """Path to registry.json (agent_name → spine_id mapping)."""
+        return self.spineforge_dir / "registry.json"
+
+    @property
+    def key_path(self) -> Path:
+        """Path to the agent's Ed25519 private key (PEM format)."""
+        return self.spineforge_dir / "agent_key.pem"
+
+    @property
+    def logs_dir(self) -> Path:
+        """Directory for JSONL log files."""
+        return self.spineforge_dir / "logs"
+
+    @property
+    def log_path(self) -> Path:
+        """Full path to the JSONL action log."""
+        return self.logs_dir / self.log_file
+
+    # ── Factory ──────────────────────────────────────────────────────────
+
+    @classmethod
+    def from_env(cls, **overrides) -> SpineforgeConfig:
+        """Build config from environment variables, with optional kwarg overrides.
+
+        Kwargs override env vars. Unset values fall back to class defaults.
+        """
+        data_dir = overrides.get(
+            "data_dir",
+            os.environ.get("SPINEFORGE_DATA_DIR", None),
+        )
+        log_file = overrides.get(
+            "log_file",
+            os.environ.get("SPINEFORGE_LOG_FILE", None),
+        )
+        verbose = overrides.get("verbose", None)
+        trace_content = overrides.get("trace_content", None)
+        registry_url = overrides.get(
+            "registry_url",
+            os.environ.get("SPINEFORGE_REGISTRY_URL", ""),
+        )
+
+        kwargs = {}
+        if data_dir is not None:
+            kwargs["data_dir"] = Path(data_dir)
+        if log_file is not None:
+            kwargs["log_file"] = log_file
+        if verbose is not None:
+            kwargs["verbose"] = verbose
+        else:
+            kwargs["verbose"] = _env_bool("SPINEFORGE_VERBOSE", default=True)
+        if trace_content is not None:
+            kwargs["trace_content"] = trace_content
+        else:
+            kwargs["trace_content"] = _env_bool("SPINEFORGE_TRACE_CONTENT", default=True)
+        kwargs["registry_url"] = registry_url.rstrip("/") if registry_url else ""
+
+        return cls(**kwargs)
+
+    def ensure_dirs(self) -> None:
+        """Create the .spineforge/ directory tree if it doesn't exist."""
+        self.logs_dir.mkdir(parents=True, exist_ok=True)

spineforge/decorators.py

@@ -0,0 +1,103 @@
+"""
+spineforge.decorators
+~~~~~~~~~~~~~~~~~~~~~
+
+Manual instrumentation helpers for code paths not covered by auto-instrumentors.
+
+Primary use case: the ``@track_tool`` decorator wraps a plain Python function
+so it produces an OTel span that our ``SpineforgeSpanProcessor`` recognises as
+a tool call.
+
+When to use
+~~~~~~~~~~~
+- ``scratch.py``'s ``call_tool()`` — the Groq instrumentor only captures LLM
+  API calls, not tool execution.  ``@track_tool`` fills the gap.
+- Future agents using AutoGen, CrewAI, or raw Python tool functions that don't
+  go through LangChain's ``Tool.run()`` callback system.
+
+When NOT to use
+~~~~~~~~~~~~~~~
+- ``main.py`` (LangChain agent) — the LangChain instrumentor's callback
+  handler already captures ``on_tool_start`` / ``on_tool_end`` automatically.
+  Adding ``@track_tool`` would create duplicate spans.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+from typing import Callable, TypeVar
+
+from opentelemetry import trace
+from opentelemetry.trace import SpanKind, StatusCode
+
+logger = logging.getLogger(__name__)
+
+F = TypeVar("F", bound=Callable)
+
+
+def track_tool(func: F) -> F:
+    """Decorator that instruments a function as a Spineforge tool call.
+
+    Creates an OTel span with ``spineforge.tool_call=True`` so the
+    ``SpineforgeSpanProcessor`` can identify it and emit an ActionEvent
+    of type ``"tool_call"``.
+
+    Usage::
+
+        @spineforge.track_tool
+        def call_tool(name: str, query: str) -> str:
+            tool = LC_TOOLS[name]
+            return str(tool.run(query))
+
+    The decorator captures:
+    - Function name as the tool name
+    - Arguments as input
+    - Return value as output
+    - Exceptions as errors (re-raised after recording)
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        tracer = trace.get_tracer("spineforge.tools")
+
+        # Build a readable span name
+        span_name = f"tool_call:{func.__name__}"
+
+        # Build input description from args
+        # For call_tool(name, query), we want "name=search_tool, query=..."
+        input_parts = []
+        if args:
+            input_parts.append(", ".join(repr(a) for a in args))
+        if kwargs:
+            input_parts.append(
+                ", ".join(f"{k}={v!r}" for k, v in kwargs.items())
+            )
+        input_str = ", ".join(input_parts)
+
+        with tracer.start_as_current_span(
+            span_name,
+            kind=SpanKind.INTERNAL,
+            attributes={
+                "spineforge.tool_call": True,
+                "spineforge.tool.name": func.__name__,
+                "spineforge.tool.input": input_str[:4096] if input_str else "",
+            },
+        ) as span:
+            try:
+                result = func(*args, **kwargs)
+
+                # Record output (truncated to avoid huge spans)
+                result_str = str(result) if result is not None else ""
+                span.set_attribute(
+                    "spineforge.tool.output", result_str[:4096]
+                )
+                span.set_status(StatusCode.OK)
+                return result
+
+            except Exception as exc:
+                span.set_status(StatusCode.ERROR, str(exc))
+                span.set_attribute("spineforge.tool.error", str(exc)[:2048])
+                raise  # Always re-raise — we observe, never swallow
+
+    return wrapper  # type: ignore[return-value]