zolva 0.1.0__py3-none-any.whl

zolva/__init__.py

@@ -0,0 +1,44 @@
+"""Zolva: self-hosted agent platform for banks and fintechs."""
+
+from zolva.audit import AuditLog, Scorecard, scorecard
+from zolva.bus import Bus, Step, Verdict
+from zolva.config import AgentConfig, ConfigError, load_agents
+from zolva.evals import EvalReport, EvalRunner, load_cohorts
+from zolva.feedback import Failure, FeedbackQueue
+from zolva.guardrails import Guardrails
+from zolva.handover import HandoverBackend, LogBackend, Ticket, WebhookBackend
+from zolva.orchestrator import BLOCKED_MESSAGE, AgentApp
+from zolva.synthetics import SyntheticResult, SyntheticRunner, load_synthetics
+from zolva.tools import ToolRegistry, default_registry, tool
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BLOCKED_MESSAGE",
+    "AgentApp",
+    "AgentConfig",
+    "AuditLog",
+    "Bus",
+    "ConfigError",
+    "EvalReport",
+    "EvalRunner",
+    "Failure",
+    "FeedbackQueue",
+    "Guardrails",
+    "HandoverBackend",
+    "LogBackend",
+    "Scorecard",
+    "Step",
+    "SyntheticResult",
+    "SyntheticRunner",
+    "Ticket",
+    "ToolRegistry",
+    "Verdict",
+    "WebhookBackend",
+    "default_registry",
+    "load_agents",
+    "load_cohorts",
+    "load_synthetics",
+    "scorecard",
+    "tool",
+]

zolva/_db.py

@@ -0,0 +1,17 @@
+"""Shared sqlite helper: sqlite3's own context manager commits but never closes."""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+
+@contextmanager
+def sqlite_conn(path: str) -> Iterator[sqlite3.Connection]:
+    conn = sqlite3.connect(path)
+    try:
+        with conn:
+            yield conn
+    finally:
+        conn.close()

zolva/_judge.py

@@ -0,0 +1,15 @@
+"""Shared binary LLM-judge call. Fail-closed: any answer that isn't PASS is a fail."""
+
+from __future__ import annotations
+
+from zolva.bridge import LLMAdapter, Message
+
+
+async def judge_passes(adapter: LLMAdapter, *, model: str, system: str, content: str) -> bool:
+    resp = await adapter.complete(
+        model=model,
+        system=system,
+        messages=[Message(role="user", content=content)],
+        tools=[],
+    )
+    return resp.text.strip().upper().startswith("PASS")

zolva/audit.py

@@ -0,0 +1,124 @@
+"""Audit plugin: hash-chained, append-only log of every bus step + the SARR scorecard.
+
+Each row's hash covers the previous row's hash, so silent edits and deletions
+are detectable (`AuditLog.verify()`). SQLite by default; point the path at
+WORM-backed storage for regulators.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+from contextlib import AbstractContextManager
+from datetime import datetime, timezone
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from zolva._db import sqlite_conn
+from zolva.bus import Step, Verdict
+from zolva.orchestrator import AgentApp
+
+_GENESIS = "genesis"
+
+
+class AuditLog:
+    def __init__(self, path: str | Path) -> None:
+        self._path = str(path)
+        self._attached = False
+        with self._conn() as conn:
+            conn.execute(
+                "CREATE TABLE IF NOT EXISTS audit ("
+                "id INTEGER PRIMARY KEY AUTOINCREMENT, ts TEXT NOT NULL, "
+                "session_id TEXT NOT NULL, agent TEXT NOT NULL, type TEXT NOT NULL, "
+                "data TEXT NOT NULL, prev_hash TEXT NOT NULL, hash TEXT NOT NULL)"
+            )
+
+    def _conn(self) -> AbstractContextManager[sqlite3.Connection]:
+        return sqlite_conn(self._path)
+
+    def attach(self, app: AgentApp) -> None:
+        if self._attached:
+            return  # idempotent: a second attach must not double-log every step
+        self._attached = True
+        app.bus.on(self._observe)
+
+    async def _observe(self, step: Step) -> Verdict | None:
+        self.append(step)
+        return None
+
+    def append(self, step: Step) -> None:
+        ts = datetime.now(timezone.utc).isoformat()
+        payload = json.dumps(step.data, sort_keys=True, default=str)
+        with self._conn() as conn:
+            row = conn.execute("SELECT hash FROM audit ORDER BY id DESC LIMIT 1").fetchone()
+            prev = row[0] if row else _GENESIS
+            digest = hashlib.sha256(
+                f"{prev}|{ts}|{step.session_id}|{step.agent}|{step.type}|{payload}".encode()
+            ).hexdigest()
+            conn.execute(
+                "INSERT INTO audit (ts, session_id, agent, type, data, prev_hash, hash) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (ts, step.session_id, step.agent, step.type, payload, prev, digest),
+            )
+
+    def verify(self) -> bool:
+        """Recompute the chain; any edited, deleted, or reordered row breaks it."""
+        prev = _GENESIS
+        with self._conn() as conn:
+            rows = conn.execute(
+                "SELECT ts, session_id, agent, type, data, prev_hash, hash FROM audit ORDER BY id"
+            ).fetchall()
+        for ts, session_id, agent, step_type, data, prev_hash, digest in rows:
+            if prev_hash != prev:
+                return False
+            expected = hashlib.sha256(
+                f"{prev}|{ts}|{session_id}|{agent}|{step_type}|{data}".encode()
+            ).hexdigest()
+            if digest != expected:
+                return False
+            prev = digest
+        return True
+
+    def step_types_by_session(self) -> dict[str, set[str]]:
+        with self._conn() as conn:
+            rows = conn.execute("SELECT session_id, type FROM audit").fetchall()
+        by_session: dict[str, set[str]] = {}
+        for session_id, step_type in rows:
+            by_session.setdefault(session_id, set()).add(step_type)
+        return by_session
+
+
+class Scorecard(BaseModel):
+    sessions: int
+    resolved: int
+    escalated: int
+    sarr: float  # Safe Automated Resolution Rate
+    containment: float
+
+    def summary(self) -> str:
+        return (
+            f"sessions={self.sessions}  resolved={self.resolved}  escalated={self.escalated}\n"
+            f"SARR={self.sarr:.1%}  containment={self.containment:.1%}"
+        )
+
+
+def scorecard(audit: AuditLog) -> Scorecard:
+    """SARR v1: session got a response and never escalated.
+
+    ponytail: no re-contact window yet (needs customer identity across
+    sessions); add when a bank wires customer refs into session ids.
+    """
+    by_session = audit.step_types_by_session()
+    sessions = [types for sid, types in by_session.items() if "user_msg" in types]
+    total = len(sessions)
+    escalated = sum(1 for types in sessions if "handover" in types)
+    resolved = sum(1 for types in sessions if "response" in types and "handover" not in types)
+    return Scorecard(
+        sessions=total,
+        resolved=resolved,
+        escalated=escalated,
+        sarr=resolved / total if total else 0.0,
+        containment=1 - (escalated / total) if total else 0.0,
+    )

zolva/bridge/__init__.py

@@ -0,0 +1,51 @@
+"""Vendor-neutral LLM bridge: one Protocol, one adapter per provider."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Literal, Protocol
+
+from pydantic import BaseModel
+
+from zolva.tools import ToolSpec
+
+
+class BridgeError(Exception):
+    """LLM provider or adapter failure."""
+
+
+class ToolCall(BaseModel):
+    id: str
+    name: str
+    args: dict[str, Any]
+
+
+class Message(BaseModel):
+    role: Literal["system", "user", "assistant", "tool"]
+    content: str
+    tool_call_id: str | None = None
+    tool_calls: list[ToolCall] = []
+
+
+class LLMResponse(BaseModel):
+    text: str = ""
+    tool_calls: list[ToolCall] = []
+
+
+class LLMAdapter(Protocol):
+    async def complete(
+        self, *, model: str, system: str, messages: list[Message], tools: list[ToolSpec]
+    ) -> LLMResponse: ...
+
+
+_ADAPTERS: dict[str, Callable[[], LLMAdapter]] = {}
+
+
+def register_adapter(provider: str, factory: Callable[[], LLMAdapter]) -> None:
+    _ADAPTERS[provider] = factory
+
+
+def get_adapter(provider: str) -> LLMAdapter:
+    try:
+        return _ADAPTERS[provider]()
+    except KeyError:
+        raise BridgeError(f"unknown provider {provider!r}") from None

zolva/bridge/anthropic.py

@@ -0,0 +1,91 @@
+"""Anthropic messages adapter."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from zolva.bridge import BridgeError, LLMResponse, Message, ToolCall, register_adapter
+from zolva.tools import ToolSpec
+
+
+class AnthropicAdapter:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = "https://api.anthropic.com",
+        transport: httpx.AsyncBaseTransport | None = None,
+        max_tokens: int = 4096,
+    ) -> None:
+        self._max_tokens = max_tokens
+        key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        if not key:
+            raise BridgeError("ANTHROPIC_API_KEY not set and no api_key given")
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers={"x-api-key": key, "anthropic-version": "2023-06-01"},
+            transport=transport,
+            timeout=60.0,
+        )
+
+    def _wire_messages(self, messages: list[Message]) -> list[dict[str, Any]]:
+        wire: list[dict[str, Any]] = []
+        for m in messages:
+            if m.role == "tool":
+                wire.append(
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "tool_result",
+                                "tool_use_id": m.tool_call_id,
+                                "content": m.content,
+                            }
+                        ],
+                    }
+                )
+            elif m.role == "assistant" and m.tool_calls:
+                blocks: list[dict[str, Any]] = []
+                if m.content:
+                    blocks.append({"type": "text", "text": m.content})
+                blocks += [
+                    {"type": "tool_use", "id": tc.id, "name": tc.name, "input": tc.args}
+                    for tc in m.tool_calls
+                ]
+                wire.append({"role": "assistant", "content": blocks})
+            else:
+                wire.append({"role": m.role, "content": m.content})
+        return wire
+
+    async def complete(
+        self, *, model: str, system: str, messages: list[Message], tools: list[ToolSpec]
+    ) -> LLMResponse:
+        body: dict[str, Any] = {
+            "model": model,
+            "max_tokens": self._max_tokens,
+            "system": system,
+            "messages": self._wire_messages(messages),
+        }
+        if tools:
+            body["tools"] = [
+                {"name": t.name, "description": t.description, "input_schema": t.parameters}
+                for t in tools
+            ]
+        try:
+            r = await self._client.post("/v1/messages", json=body)
+            r.raise_for_status()
+        except httpx.HTTPError as e:
+            raise BridgeError(f"anthropic: {e}") from e
+        text = ""
+        calls: list[ToolCall] = []
+        for block in r.json()["content"]:
+            if block["type"] == "text":
+                text += block["text"]
+            elif block["type"] == "tool_use":
+                calls.append(ToolCall(id=block["id"], name=block["name"], args=block["input"]))
+        return LLMResponse(text=text, tool_calls=calls)
+
+
+register_adapter("anthropic", AnthropicAdapter)

zolva/bridge/fake.py

@@ -0,0 +1,22 @@
+"""Scripted adapter for tests and offline development. Shipped on purpose."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from zolva.bridge import BridgeError, LLMResponse, Message
+from zolva.tools import ToolSpec
+
+
+class FakeAdapter:
+    def __init__(self, script: list[LLMResponse]) -> None:
+        self._script = list(script)
+        self.calls: list[dict[str, Any]] = []
+
+    async def complete(
+        self, *, model: str, system: str, messages: list[Message], tools: list[ToolSpec]
+    ) -> LLMResponse:
+        self.calls.append({"model": model, "system": system, "messages": messages, "tools": tools})
+        if not self._script:
+            raise BridgeError("FakeAdapter script exhausted")
+        return self._script.pop(0)

zolva/bridge/openai.py

@@ -0,0 +1,83 @@
+"""OpenAI chat-completions adapter."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+import httpx
+
+from zolva.bridge import BridgeError, LLMResponse, Message, ToolCall, register_adapter
+from zolva.tools import ToolSpec
+
+
+class OpenAIAdapter:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = "https://api.openai.com/v1",
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        key = api_key or os.environ.get("OPENAI_API_KEY")
+        if not key:
+            raise BridgeError("OPENAI_API_KEY not set and no api_key given")
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {key}"},
+            transport=transport,
+            timeout=60.0,
+        )
+
+    def _wire_messages(self, system: str, messages: list[Message]) -> list[dict[str, Any]]:
+        wire: list[dict[str, Any]] = [{"role": "system", "content": system}]
+        for m in messages:
+            item: dict[str, Any] = {"role": m.role, "content": m.content}
+            if m.role == "tool":
+                item["tool_call_id"] = m.tool_call_id
+            if m.tool_calls:
+                item["tool_calls"] = [
+                    {
+                        "id": tc.id,
+                        "type": "function",
+                        "function": {"name": tc.name, "arguments": json.dumps(tc.args)},
+                    }
+                    for tc in m.tool_calls
+                ]
+            wire.append(item)
+        return wire
+
+    async def complete(
+        self, *, model: str, system: str, messages: list[Message], tools: list[ToolSpec]
+    ) -> LLMResponse:
+        body: dict[str, Any] = {"model": model, "messages": self._wire_messages(system, messages)}
+        if tools:
+            body["tools"] = [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": t.name,
+                        "description": t.description,
+                        "parameters": t.parameters,
+                    },
+                }
+                for t in tools
+            ]
+        try:
+            r = await self._client.post("/chat/completions", json=body)
+            r.raise_for_status()
+        except httpx.HTTPError as e:
+            raise BridgeError(f"openai: {e}") from e
+        msg = r.json()["choices"][0]["message"]
+        calls = [
+            ToolCall(
+                id=tc["id"],
+                name=tc["function"]["name"],
+                args=json.loads(tc["function"]["arguments"]),
+            )
+            for tc in (msg.get("tool_calls") or [])
+        ]
+        return LLMResponse(text=msg.get("content") or "", tool_calls=calls)
+
+
+register_adapter("openai", OpenAIAdapter)

zolva/bus.py

@@ -0,0 +1,39 @@
+"""Middleware bus: every orchestrator step flows through here. Plugins attach as hooks."""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Literal
+
+from pydantic import BaseModel
+
+StepType = Literal["user_msg", "model_call", "tool_call", "response", "handover", "feedback"]
+
+
+class Step(BaseModel):
+    type: StepType
+    session_id: str
+    agent: str
+    data: dict[str, Any]
+
+
+class Verdict(BaseModel):
+    allow: bool = True
+    reason: str | None = None
+
+
+Hook = Callable[[Step], Awaitable[Verdict | None]]
+
+
+class Bus:
+    def __init__(self) -> None:
+        self._hooks: list[Hook] = []
+
+    def on(self, hook: Hook) -> None:
+        self._hooks.append(hook)
+
+    async def emit(self, step: Step) -> Verdict:
+        for hook in self._hooks:
+            verdict = await hook(step)
+            if verdict is not None and not verdict.allow:
+                return verdict
+        return Verdict()

zolva/cli.py

@@ -0,0 +1,141 @@
+"""zolva CLI: validate, eval, scorecard, triage, export-dataset."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import json
+import sys
+from typing import Any
+
+from zolva.config import ConfigError, load_agents
+from zolva.orchestrator import AgentApp
+
+
+def _load_app(spec: str) -> AgentApp:
+    """Import 'module.path:attr' and return the bank's AgentApp instance."""
+    module_name, _, attr = spec.partition(":")
+    if not module_name or not attr:
+        raise ConfigError(f"--app must be 'module.path:attr', got {spec!r}")
+    module = importlib.import_module(module_name)
+    app = getattr(module, attr, None)
+    if not isinstance(app, AgentApp):
+        raise ConfigError(f"{spec} is not an AgentApp instance")
+    return app
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    agents = load_agents(args.config_dir)
+    for cfg in agents.values():
+        print(
+            f"{cfg.name}  {cfg.model.provider}/{cfg.model.name}  "
+            f"tools={len(cfg.tools)}  handoffs={cfg.handoffs}"
+        )
+    print(f"OK: {len(agents)} agent(s) valid")
+    return 0
+
+
+def _cmd_eval(args: argparse.Namespace) -> int:
+    from zolva.bridge import get_adapter
+    from zolva.evals import EvalRunner
+
+    app = _load_app(args.app)
+    judge = get_adapter(args.judge_provider) if args.judge_provider else None
+    runner = EvalRunner(app, judge=judge, judge_model=args.judge_model)
+    report = asyncio.run(runner.run(args.evals_dir))
+    print(report.summary())
+    if args.out:
+        with open(args.out, "w") as f:
+            json.dump(report.model_dump(), f, indent=2)
+        print(f"wrote {args.out}")
+    if args.gate and not report.gate_passed:
+        return 1  # the CI story: any CI can run a command that exits 1
+    return 0
+
+
+def _cmd_scorecard(args: argparse.Namespace) -> int:
+    from zolva.audit import AuditLog, scorecard
+
+    log = AuditLog(args.audit_db)
+    if not log.verify():
+        print("AUDIT CHAIN BROKEN: log has been tampered with", file=sys.stderr)
+        return 1
+    print(scorecard(log).summary())
+    return 0
+
+
+def _cmd_triage(args: argparse.Namespace) -> int:
+    from zolva.feedback import FeedbackQueue
+
+    q = FeedbackQueue(args.failures_db)
+    if args.accept is not None:
+        if not args.cohort or not args.expect:
+            print("--accept requires --cohort and --expect", file=sys.stderr)
+            return 1
+        q.accept(args.accept, args.cohort, expect=args.expect)
+        print(f"failure {args.accept} promoted to {args.cohort}")
+        return 0
+    if args.reject is not None:
+        q.reject(args.reject)
+        print(f"failure {args.reject} rejected")
+        return 0
+    pending = q.pending()
+    for f in pending:
+        last_user = next((m.content for m in reversed(f.transcript) if m.role == "user"), "")
+        print(f"#{f.id}  [{f.kind}]  agent={f.agent}  note={f.note!r}  last_user={last_user!r}")
+    print(f"{len(pending)} pending failure(s)")
+    return 0
+
+
+def _cmd_export_dataset(args: argparse.Namespace) -> int:
+    from zolva.feedback import FeedbackQueue
+
+    n = FeedbackQueue(args.failures_db).export_dataset(args.out)
+    print(f"wrote {n} accepted failure(s) to {args.out}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="zolva")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_validate = sub.add_parser("validate", help="validate an agent config directory")
+    p_validate.add_argument("config_dir")
+
+    p_eval = sub.add_parser("eval", help="run eval cohorts against your app")
+    p_eval.add_argument("evals_dir")
+    p_eval.add_argument("--app", required=True, help="import path to your AgentApp: module:attr")
+    p_eval.add_argument("--gate", action="store_true", help="exit 1 if the worst cohort fails")
+    p_eval.add_argument("--judge-provider", default="", help="bridge provider for the judge")
+    p_eval.add_argument("--judge-model", default="", help="model name for the judge")
+    p_eval.add_argument("--out", default="", help="write full report JSON to this path")
+
+    p_score = sub.add_parser("scorecard", help="verify the audit chain and print SARR")
+    p_score.add_argument("audit_db")
+
+    p_triage = sub.add_parser("triage", help="list/promote/reject pending failures")
+    p_triage.add_argument("failures_db")
+    p_triage.add_argument("--accept", type=int, default=None, metavar="ID")
+    p_triage.add_argument("--cohort", default="", help="eval cohort file to promote into")
+    p_triage.add_argument("--expect", default="", help="expected behavior for the judge")
+    p_triage.add_argument("--reject", type=int, default=None, metavar="ID")
+
+    p_export = sub.add_parser("export-dataset", help="accepted failures as fine-tuning JSONL")
+    p_export.add_argument("failures_db")
+    p_export.add_argument("out")
+
+    args = parser.parse_args(argv)
+    commands: dict[str, Any] = {
+        "validate": _cmd_validate,
+        "eval": _cmd_eval,
+        "scorecard": _cmd_scorecard,
+        "triage": _cmd_triage,
+        "export-dataset": _cmd_export_dataset,
+    }
+    try:
+        result: int = commands[args.command](args)
+        return result
+    except ConfigError as e:
+        print(f"config error: {e}", file=sys.stderr)
+        return 1