succession-cli 0.2.0__py3-none-any.whl

succession/acp_cli.py

@@ -0,0 +1,133 @@
+"""ACP registration, sync, and snapshot — the operator-side commands.
+
+Registration itself happens in the Virtuals app, not here: the ACP Tech
+Playbook issues a whitelisted wallet and an entity id, and no SDK call
+substitutes for that. What these commands do is everything after it — confirm
+the registration is live, pull the agent's job history, mirror it into memory so
+it becomes part of the transferable asset, and snapshot it for offline use.
+
+    export WHITELISTED_WALLET_PRIVATE_KEY=0x...
+    export AGENT_WALLET_ADDRESS=0x...
+    export ACP_ENTITY_ID=...
+
+    succession-acp status
+    succession-acp sync --db seller.db --tenant tenant-seller
+    succession-acp snapshot --out web/public/acp-snapshot.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .acp import (
+    ACPNotConfigured,
+    AgentNotRegistered,
+    LiveACP,
+    RecordedACP,
+    fetch_history,
+    job_history_from_memory,
+    require_registered,
+    sync_job_history,
+)
+from .memory.sibyl import open_tenant
+
+
+def _history(args: argparse.Namespace):
+    if getattr(args, "snapshot", None):
+        return fetch_history(RecordedACP.from_file(args.snapshot))
+    return fetch_history(LiveACP())
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    history = _history(args)
+    try:
+        require_registered(history)
+    except AgentNotRegistered as exc:
+        print(f"NOT REGISTERED: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps(history.to_dict(), indent=2))
+    return 0
+
+
+def cmd_sync(args: argparse.Namespace) -> int:
+    """Pull job history and mirror it into the tenant.
+
+    Gated on registration: syncing an unregistered agent would write an empty
+    earnings record that later reads as "this agent earned nothing" rather than
+    "this agent was never registered".
+    """
+    history = _history(args)
+    require_registered(history)
+    memory = open_tenant(args.db, args.tenant)
+    written = sync_job_history(memory, history)
+    print(f"synced {written} ACP jobs into {args.tenant}")
+    print(f"completed: {len(history.completed)}  failed: {len(history.failed)}")
+    print(f"gross volume: {history.gross_volume}")
+    rate = history.success_rate()
+    print(f"success rate: {rate if rate is not None else 'sample too small'}")
+    return 0
+
+
+def cmd_snapshot(args: argparse.Namespace) -> int:
+    """Capture live history to a file, for offline development and the hosted UI."""
+    source = LiveACP()
+    payload = {"agent": source.agent(), "jobs": [j.to_dict() for j in source.jobs()]}
+    Path(args.out).parent.mkdir(parents=True, exist_ok=True)
+    Path(args.out).write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    print(f"wrote {len(payload['jobs'])} jobs to {args.out}")
+    return 0
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    """Read back the history a tenant already carries. Needs no credentials."""
+    memory = open_tenant(args.db, args.tenant)
+    print(json.dumps(job_history_from_memory(memory).to_dict(), indent=2))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="succession-acp", description="Virtuals ACP job history."
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def snapshot_opt(p: argparse.ArgumentParser) -> None:
+        p.add_argument(
+            "--snapshot",
+            help="read from a captured snapshot instead of the live API",
+        )
+
+    def tenant_opts(p: argparse.ArgumentParser) -> None:
+        p.add_argument("--db", type=Path, required=True)
+        p.add_argument("--tenant", required=True)
+
+    p = sub.add_parser("status", help="confirm registration and show job history")
+    snapshot_opt(p)
+    p.set_defaults(func=cmd_status)
+
+    p = sub.add_parser("sync", help="mirror ACP job history into a tenant's memory")
+    tenant_opts(p)
+    snapshot_opt(p)
+    p.set_defaults(func=cmd_sync)
+
+    p = sub.add_parser("snapshot", help="capture live job history to a file")
+    p.add_argument("--out", required=True)
+    p.set_defaults(func=cmd_snapshot)
+
+    p = sub.add_parser("show", help="show the job history a tenant already carries")
+    tenant_opts(p)
+    p.set_defaults(func=cmd_show)
+
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except (ACPNotConfigured, AgentNotRegistered) as exc:
+        print(f"FAILED: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

succession/agent.py

@@ -0,0 +1,288 @@
+"""A minimal agent that answers strictly out of Sibyl Memory.
+
+This backs the demo's final beat — the buyer's agent, cold-booted on new
+infrastructure, continuing a live customer relationship it has never seen.
+
+It is retrieval over the tenant, not a language model, and that is a deliberate
+choice rather than a shortcut. The claim being demonstrated is "the memory
+transferred and is usable", and a deterministic responder demonstrates exactly
+that: every line it produces is traceable to a specific record, with the
+category and name it came from. A model in this position would produce a more
+fluent answer and a weaker demonstration, because a fluent answer is exactly
+what a model can produce with no memory at all.
+
+Swapping in a real model is a small change and the right one for production —
+:meth:`Agent.context_for` already returns the grounded context a prompt would
+carry. The demo keeps the deterministic path so what is on screen is evidence.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["Agent", "Reply", "Citation"]
+
+#: Words too common to retrieve anything useful. Kept short on purpose: an
+#: aggressive list would strip the domain terms ("reefer", "flatbed", "lane")
+#: that are exactly what makes a message findable.
+_STOPWORDS = frozenset(
+    """a an and are as at be but by can could do for from has have hi hello
+    how i if in is it me my need of on or our out still that the their them
+    then there this to us we what when where which will with would you your
+    again about any anything back get got just like more not now one same
+    still than too very was were yes""".split()
+)
+
+
+def _terms(text: str) -> list[str]:
+    """The distinctive words in a message, in order, deduplicated."""
+    import re
+
+    seen: set[str] = set()
+    out: list[str] = []
+    for raw in re.findall(r"[A-Za-z][A-Za-z'-]+", text):
+        word = raw.lower().strip("'-")
+        if len(word) < 4 or word in _STOPWORDS or word in seen:
+            continue
+        seen.add(word)
+        out.append(raw)
+    return out[:8]
+
+
+@dataclass(frozen=True)
+class Citation:
+    """Where a line of the answer came from. Every claim carries one."""
+
+    tier: str
+    key: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"tier": self.tier, "key": self.key}
+
+
+@dataclass
+class Reply:
+    text: str
+    citations: list[Citation] = field(default_factory=list)
+    recalled: bool = True
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "text": self.text,
+            "recalled": self.recalled,
+            "citations": [c.to_dict() for c in self.citations],
+        }
+
+
+class Agent:
+    """Answers about a counterparty from whatever the tenant actually holds."""
+
+    def __init__(self, memory: Any) -> None:
+        self.memory = memory
+
+    # -- retrieval -----------------------------------------------------
+
+    def find_counterparty(self, text: str) -> dict[str, Any] | None:
+        """Match a message to a known counterparty.
+
+        Goes through Sibyl's FTS5 index (``search_entities``, anchored to the
+        ``relationship`` category) rather than scanning every entity in Python.
+        That matters for more than speed: the index covers the entity's name,
+        category and body, so a customer who mentions their lane or a detail
+        from the notes is matched even when they never say the company name —
+        which is the realistic case for a returning customer.
+
+        The scan is kept as a fallback. FTS returns nothing for a query whose
+        every token is a stopword or punctuation, and "recall failed" is the
+        wrong answer when the company name is sitting right there in the text.
+        """
+        hits = self._search_relationships(text)
+
+        needle = text.lower()
+        best: tuple[int, dict[str, Any]] | None = None
+        for entity in hits or self._all_relationships():
+            company = str(entity["body"].get("company", ""))
+            for candidate in (company.lower(), entity["name"].replace("-", " ")):
+                if candidate and candidate in needle:
+                    # Longest literal match wins, so "Northwind Mills" beats "mills".
+                    if best is None or len(candidate) > best[0]:
+                        best = (len(candidate), entity)
+        if best is not None:
+            return best[1]
+
+        # No literal name in the message, but FTS matched something on the body
+        # — the lane, or a detail from the notes. Take its top-ranked hit.
+        return hits[0] if hits else None
+
+    def _search_relationships(self, text: str) -> list[dict[str, Any]]:
+        """FTS over the relationship category, one distinctive term at a time.
+
+        The SDK sanitizes a query into a single FTS5 *phrase*, so passing a
+        whole sentence asks the index for that exact sentence and finds
+        nothing. Searching the message's distinctive terms individually and
+        merging by how many of them hit is what actually retrieves a
+        counterparty from "we need a reefer from Yakima to Denver" — where the
+        company is never named and the match has to come from the lane and the
+        notes.
+        """
+        scored: dict[tuple[str, str], tuple[int, dict[str, Any]]] = {}
+        for term in _terms(text):
+            try:
+                results = self.memory.client.search_entities(
+                    term, limit=5, category="relationship"
+                )
+            except Exception:  # noqa: BLE001 - a search that errors is skipped
+                continue
+            for entity in results:
+                key = (entity["category"], entity["name"])
+                count, _ = scored.get(key, (0, entity))
+                scored[key] = (count + 1, entity)
+
+        return [
+            entity
+            for _, entity in sorted(scored.values(), key=lambda p: -p[0])
+        ]
+
+    def _all_relationships(self) -> list[dict[str, Any]]:
+        return [e for e in self.memory.entities() if e["category"] == "relationship"]
+
+    def open_commitment_for(self, company: str) -> dict[str, Any] | None:
+        for entity in self.memory.entities():
+            if entity["category"] != "commitment":
+                continue
+            if entity["body"].get("counterparty") == company:
+                return entity
+        return None
+
+    def behaviour_for(self, company: str) -> dict[str, Any] | None:
+        for entity in self.memory.entities():
+            if entity["category"] != "learned-behavior":
+                continue
+            if company.lower() in str(entity["body"].get("pattern", "")).lower():
+                return entity
+        return None
+
+    def working_state(self) -> dict[str, Any] | None:
+        state = self.memory.client.get_state("current-negotiation")
+        return state["body"] if state else None
+
+    def context_for(self, message: str) -> dict[str, Any]:
+        """The grounded context behind an answer — what a prompt would carry."""
+        counterparty = self.find_counterparty(message)
+        if counterparty is None:
+            return {}
+        company = counterparty["body"].get("company", counterparty["name"])
+        return {
+            "counterparty": counterparty,
+            "commitment": self.open_commitment_for(company),
+            "behaviour": self.behaviour_for(company),
+            "state": self.working_state(),
+            "history": self._history_for(counterparty),
+        }
+
+    def _history_for(self, counterparty: dict[str, Any]) -> list[str]:
+        """Journal lines about this counterparty.
+
+        Matching on the company name alone misses most of them: the journal
+        records work by lane ("quoted Duluth to Kansas City at 2380; accepted"),
+        because that is how the agent thinks about a booking. The lane is
+        therefore part of the needle, not just the name.
+        """
+        body = counterparty["body"]
+        needles = {str(body.get("company", "")).lower(), counterparty["name"].replace("-", " ")}
+        lane = str(body.get("primary_lane", "")).lower()
+        if lane and lane != "withheld":
+            needles.add(lane)
+        needles = {n for n in needles if n}
+
+        return [
+            line
+            for event in self.memory.events()
+            for line in (event.get("acted") or [])
+            if any(n in line.lower() for n in needles)
+        ]
+
+    # -- response ------------------------------------------------------
+
+    def respond(self, message: str) -> Reply:
+        context = self.context_for(message)
+        if not context:
+            return Reply(
+                text=(
+                    "I don't have a record of this counterparty. Could you tell me "
+                    "the company and the lane, and I'll quote it fresh?"
+                ),
+                recalled=False,
+            )
+
+        counterparty = context["counterparty"]
+        company = counterparty["body"].get("company", counterparty["name"])
+        citations = [Citation("relationship", counterparty["name"])]
+
+        parts = [f"Yes — {company}."]
+
+        commitment = context.get("commitment")
+        state = context.get("state")
+        if commitment is not None:
+            parts.append(_describe_commitment(commitment))
+            citations.append(Citation("commitment", commitment["name"]))
+
+        if state and state.get("counterparty") == company:
+            parts.append(state["our_position"])
+            citations.append(Citation("state", "current-negotiation"))
+
+        behaviour = context.get("behaviour")
+        if behaviour is not None:
+            parts.append(behaviour["body"]["pattern"])
+            citations.append(Citation("learned-behavior", behaviour["name"]))
+
+        history = context.get("history") or []
+        if history:
+            n = len(history)
+            parts.append(
+                f"That's {n} prior interaction{'' if n == 1 else 's'} on record."
+            )
+            citations.append(
+                Citation("history", f"{n} journal event{'' if n == 1 else 's'}")
+            )
+
+        return Reply(text=" ".join(parts), citations=citations)
+
+
+#: Fields that name *what* a commitment is about, in order of preference. An
+#: agent's domain decides which of these its commitments carry, so the
+#: description composes from whichever are present rather than assuming one
+#: vocabulary — the first version of this hardcoded freight and produced a
+#: KeyError the moment a recruiting agent was seeded.
+_SUBJECT_FIELDS = (
+    "lane", "role", "line", "deliverable", "offer", "counterparty", "units",
+)
+
+#: Fields carrying a monetary amount, again in preference order.
+_VALUE_FIELDS = (
+    "quoted_rate_usd", "proposed_standing_rate_usd", "fee_usd", "value_usd",
+)
+
+
+def _describe_commitment(commitment: dict[str, Any]) -> str:
+    """One sentence about an open commitment, from whatever fields it has."""
+    body = commitment.get("body") or {}
+
+    subject = next(
+        (str(body[f]) for f in _SUBJECT_FIELDS if body.get(f) not in (None, "")),
+        None,
+    )
+    amount = next(
+        (body[f] for f in _VALUE_FIELDS if isinstance(body.get(f), (int, float))),
+        None,
+    )
+    status = body.get("status")
+
+    clause = "We have " + (f"{subject} open" if subject else "an open item")
+    if amount is not None:
+        clause += f" at ${amount:,}"
+    clause += f", recorded as {commitment['name']}"
+    if status:
+        clause += f" and still {status}"
+    return clause + "."