agentics-you 1.2.0__py3-none-any.whl

agentics_you/__init__.py

@@ -0,0 +1,82 @@
+"""agentics-you — the Agentics Python SDK: shared memory for AI agents, receipts and the gateway.
+
+Memory quickstart:
+
+    from agentics_you import AgenticsClient
+
+    client = AgenticsClient()                  # reads AGENTICS_API_KEY (ak_...), optional AGENTICS_AGENT
+    client.memories.add("Dana prefers aisle seats.", wait=True)
+    hits = client.memories.search("Which seat does Dana want?", k=5)["hits"]
+
+Receipts (decorator style):
+
+    from agentics_you import Network
+
+    net = Network(api_key="ak_...")
+
+    @net.task(scope=["read:tickets", "write:reply"])
+    def handle_ticket(ticket_id: str) -> str:
+        return reply
+
+Extras: ``agentics-you[openai]`` (agentics_you.openai_agents trace processor) and ``agentics-you[litellm]``
+(agentics_you.litellm_callback).
+"""
+from .client import Agentics, Task, TaskContext
+from .network import Network
+from .version import __version__
+
+# Memory client (namespaces, memories, ingest) with typed errors and retries.
+from .memory import (
+    AgenticsClient,
+    AsyncAgenticsClient,
+    AgenticsError,
+    ValidationError,
+    AuthenticationError,
+    PermissionDeniedError,
+    NotFoundError,
+    ConflictError,
+    RateLimitError,
+    ServerError,
+)
+
+# Task receipts posted to /v1/receipts (formerly packages/agentics-python).
+from .receipts import client, Client
+
+# Gateway client (drop-in OpenAI-compatible base_url swap). Stdlib-only, so this
+# import is always safe even without the `openai` package installed.
+from .gateway import (
+    AgenticsGateway,
+    GatewayError,
+    createHeaders,
+    list_models,
+    DEFAULT_GATEWAY_BASE_URL,
+)
+
+__all__ = [
+    # Memory
+    "AgenticsClient", "AsyncAgenticsClient", "AgenticsError", "ValidationError", "AuthenticationError",
+    "PermissionDeniedError", "NotFoundError", "ConflictError", "RateLimitError", "ServerError",
+    # Receipts
+    "client", "Client",
+    "Agentics", "Task", "TaskContext",
+    "Network",
+    "AgenticsTasks", "AgenticsTasksError",
+    # Gateway (drop-in OpenAI-compatible client + trace/metadata propagation)
+    "AgenticsGateway", "GatewayError", "createHeaders", "list_models",
+    "DEFAULT_GATEWAY_BASE_URL",
+    "__version__",
+]
+
+
+def __getattr__(name):
+    """Lazily expose the framework callback handlers so importing `agentics`
+    never requires LangChain/LlamaIndex/CrewAI to be installed."""
+    if name in ("AgenticsTasks", "AgenticsTasksError"):  # needs httpx, which is not a dependency
+        from . import tasks as _tasks
+
+        return getattr(_tasks, name)
+    if name in ("instrument", "LangchainCallbackHandler", "LlamaIndexCallbackHandler"):
+        from . import instrument as _instr
+
+        return getattr(_instr, name)
+    raise AttributeError(f"module 'agentics_you' has no attribute {name!r}")

agentics_you/cli.py

@@ -0,0 +1,305 @@
+"""Agentics CLI.
+
+Usage:
+  agentics login --api-key ak_...
+  agentics deploy [--manifest agentics.json]
+  agentics receipt send --agent support-bot --model anthropic/claude-opus-4-6 --outcome success --input "..." --output "..."
+  agentics agents list
+  agentics flags
+  agentics whoami
+
+  # Gateway devex verbs (sdk spec Appendix A)
+  agentics gateway test [--url https://agentics.you/api/v1] [--user a@b.com]
+  agentics config publish [config.json] [--name default]
+  agentics config validate [config.json]
+  agentics prompt push <prompt.json>
+  agentics log tail [--limit 50]
+  agentics proof verify <hash>
+  agentics proof bundle <hash>
+  agentics models [--provider anthropic]
+"""
+from __future__ import annotations
+import argparse, json, os, sys
+from urllib import request as _request
+from urllib.error import HTTPError
+
+from .client import Agentics, Task
+
+
+def _api(method: str, path: str, body=None, key: str | None = None, query: dict | None = None):
+    base = os.environ.get("AGENTICS_BASE_URL", "https://agentics.you")
+    if query:
+        from urllib.parse import urlencode
+        clean = {k: v for k, v in query.items() if v is not None}
+        if clean:
+            path = f"{path}?{urlencode(clean)}"
+    req = _request.Request(
+        f"{base}{path}",
+        data=json.dumps(body).encode("utf-8") if body is not None else None,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {key or os.environ.get('AGENTICS_API_KEY','')}",
+        },
+        method=method,
+    )
+    try:
+        with _request.urlopen(req, timeout=15) as r:
+            return json.loads(r.read().decode("utf-8") or "{}")
+    except HTTPError as e:
+        try:
+            payload = json.loads(e.read().decode("utf-8") or "{}")
+        except Exception:
+            payload = {}
+        # 404 from a flag-gated surface == "feature not enabled for this tenant".
+        if e.code == 404:
+            raise SystemExit(
+                "HTTP 404: feature not enabled for this tenant "
+                f"(path may be flag-gated). {payload.get('error') or ''}".strip()
+            )
+        raise SystemExit(f"HTTP {e.code}: {payload.get('error') or payload}")
+
+
+def _read_json_file(path: str) -> dict:
+    if not path or not os.path.exists(path):
+        raise SystemExit(f"file not found: {path}")
+    with open(path) as f:
+        return json.loads(f.read() or "{}")
+
+
+def _load_manifest(path: str | None) -> dict:
+    """Load agent manifest from JSON (or YAML if PyYAML installed)."""
+    candidates = [path] if path else ["agentics.json", "agentics.yaml", "agentics.yml"]
+    for cand in candidates:
+        if not cand or not os.path.exists(cand):
+            continue
+        with open(cand) as f:
+            raw = f.read()
+        if cand.endswith((".yaml", ".yml")):
+            try:
+                import yaml  # type: ignore
+            except ImportError:
+                raise SystemExit(
+                    f"Manifest {cand} is YAML but PyYAML is not installed. "
+                    "Install with: pip install agentics[yaml]"
+                )
+            return yaml.safe_load(raw) or {}
+        return json.loads(raw or "{}")
+    raise SystemExit(
+        "No agent manifest found. Create agentics.json (or pass --manifest) with at least: "
+        "foundation_model, scope_array, display_name."
+    )
+
+
+def _do_deploy(args) -> None:
+    manifest = _load_manifest(args.manifest)
+    # CLI flags override manifest values
+    for flag, key in (
+        ("handle", "handle"),
+        ("model", "foundation_model"),
+        ("name", "display_name"),
+        ("description", "description"),
+        ("avatar_url", "avatar_url"),
+        ("owner_email", "owner_email"),
+    ):
+        v = getattr(args, flag, None)
+        if v:
+            manifest[key] = v
+    if args.scope:
+        manifest["scope_array"] = [s.strip() for s in args.scope.split(",") if s.strip()]
+
+    if not manifest.get("foundation_model"):
+        raise SystemExit("Manifest missing required field: foundation_model")
+    if not manifest.get("scope_array"):
+        raise SystemExit("Manifest missing required field: scope_array (e.g. ['read:tickets'])")
+
+    print(f"Deploying agent to {os.environ.get('AGENTICS_BASE_URL', 'https://agentics.you')} ...")
+    resp = _api("POST", "/api/v1/agents/register", body=manifest)
+    print(json.dumps(resp, indent=2))
+    if resp.get("api_key"):
+        print(
+            "\n✓ Deployed. Save the api_key above as AGENTICS_API_KEY; the agent will start"
+            " appearing on /network/registry once its first receipt is anchored.",
+            file=sys.stderr,
+        )
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="agentics", description="Agentics CLI")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sp = sub.add_parser("login"); sp.add_argument("--api-key", required=True)
+    sub.add_parser("whoami")
+    sub.add_parser("flags")
+    sub.add_parser("agents")
+
+    dp = sub.add_parser("deploy", help="Register or update an agent from a manifest")
+    dp.add_argument("--manifest", help="Path to agentics.json / agentics.yaml (default: ./agentics.json)")
+    dp.add_argument("--handle", help="Override handle from manifest")
+    dp.add_argument("--model", help="Override foundation_model")
+    dp.add_argument("--name", help="Override display_name")
+    dp.add_argument("--description", help="Override description")
+    dp.add_argument("--avatar-url", dest="avatar_url", help="Override avatar URL")
+    dp.add_argument("--owner-email", dest="owner_email", help="Owner contact email")
+    dp.add_argument("--scope", help="Comma-separated scope override, e.g. read:tickets,write:reply")
+
+    rs = sub.add_parser("receipt"); rss = rs.add_subparsers(dest="rcmd", required=True)
+    rsn = rss.add_parser("send")
+    rsn.add_argument("--agent", required=True)
+    rsn.add_argument("--model", required=True)
+    rsn.add_argument("--version", default="")
+    rsn.add_argument("--outcome", default="success", choices=["success", "partial", "failed"])
+    rsn.add_argument("--input", default="")
+    rsn.add_argument("--output", default="")
+    rsn.add_argument("--scope", default="", help="comma-separated declared scope")
+    rsn.add_argument("--scope-used", default="", help="comma-separated used scope")
+
+    # ── gateway test ──────────────────────────────────────────────────────────
+    gt = sub.add_parser("gateway", help="Gateway client helpers")
+    gts = gt.add_subparsers(dest="gcmd", required=True)
+    gtt = gts.add_parser("test", help="Send a 1-token ping through the gateway")
+    gtt.add_argument("--url", help="Gateway base_url (…/v1). Defaults to env AGENTICS_GATEWAY_URL")
+    gtt.add_argument("--user", default=None, help="x-agentics-user attribution")
+    gtt.add_argument("--model", default="@anthropic/claude-opus-4-8")
+
+    # ── config publish / validate ─────────────────────────────────────────────
+    cp = sub.add_parser("config", help="Routing config (Routing Fabric)")
+    cps = cp.add_subparsers(dest="ccmd", required=True)
+    cpp = cps.add_parser("publish", help="Create + publish a GatewayConfig")
+    cpp.add_argument("file", nargs="?", default="gateway-config.json")
+    cpp.add_argument("--name", default=None, help="Config name (default: from file or 'default')")
+    cpv = cps.add_parser("validate", help="Dry-run validate a GatewayConfig (no publish)")
+    cpv.add_argument("file", nargs="?", default="gateway-config.json")
+
+    # ── prompt push ───────────────────────────────────────────────────────────
+    pp = sub.add_parser("prompt", help="Prompt Registry")
+    pps = pp.add_subparsers(dest="pcmd", required=True)
+    ppp = pps.add_parser("push", help="Publish a prompt template")
+    ppp.add_argument("file")
+
+    # ── log tail ──────────────────────────────────────────────────────────────
+    lt = sub.add_parser("log", help="Gateway receipt logs")
+    lts = lt.add_subparsers(dest="lcmd", required=True)
+    ltt = lts.add_parser("tail", help="Tail recent gateway receipts (with trace_id)")
+    ltt.add_argument("--limit", type=int, default=50)
+    ltt.add_argument("--since", default=None)
+
+    # ── proof verify / bundle ─────────────────────────────────────────────────
+    pr = sub.add_parser("proof", help="Verify a receipt end-to-end (Proof Mesh)")
+    prs = pr.add_subparsers(dest="prcmd", required=True)
+    prv = prs.add_parser("verify", help="4-step verify: leaf, chain, merkle, anchor")
+    prv.add_argument("hash")
+    prb = prs.add_parser("bundle", help="Offline-verifiable evidence bundle")
+    prb.add_argument("hash")
+
+    # ── models (Model Garden catalog, D8) ─────────────────────────────────────
+    md = sub.add_parser("models", help="List the Model Garden catalog")
+    md.add_argument("--provider", default=None)
+    md.add_argument("--modality", default=None)
+    md.add_argument("-q", "--query", dest="q", default=None)
+    md.add_argument("--include-deprecated", action="store_true")
+
+    args = p.parse_args(argv)
+
+    if args.cmd == "login":
+        cfg = os.path.expanduser("~/.agentics")
+        os.makedirs(cfg, exist_ok=True)
+        with open(os.path.join(cfg, "credentials"), "w") as f:
+            f.write(args.api_key)
+        print("Saved credentials to ~/.agentics/credentials")
+        return
+
+    # Load creds from file if env is empty
+    if not os.environ.get("AGENTICS_API_KEY"):
+        cfg = os.path.expanduser("~/.agentics/credentials")
+        if os.path.exists(cfg):
+            with open(cfg) as f:
+                os.environ["AGENTICS_API_KEY"] = f.read().strip()
+
+    if args.cmd == "whoami":
+        print(json.dumps(_api("GET", "/api/me"), indent=2))
+    elif args.cmd == "flags":
+        print(json.dumps(_api("GET", "/api/admin/flags"), indent=2))
+    elif args.cmd == "agents":
+        print(json.dumps(_api("GET", "/api/agents-e"), indent=2))
+    elif args.cmd == "deploy":
+        _do_deploy(args)
+    elif args.cmd == "receipt" and args.rcmd == "send":
+        client = Agentics(async_buffer=False)
+        t = Task(
+            agent_id=args.agent,
+            foundation_model=args.model,
+            model_version=args.version,
+            scope=[s for s in args.scope.split(",") if s],
+        )
+        t.set_outputs(args.output)
+        t.set_outcome(args.outcome)
+        for s in [s for s in args.scope_used.split(",") if s]:
+            t.use_scope(s)
+        client.send(t)
+        client.flush()
+        print(json.dumps({"sent": True, "task_id": t.task_id}, indent=2))
+
+    # ── gateway test ──────────────────────────────────────────────────────────
+    elif args.cmd == "gateway" and args.gcmd == "test":
+        from .gateway import AgenticsGateway, GatewayError
+        gw = AgenticsGateway(base_url=args.url).with_options(user=args.user)
+        try:
+            resp = gw.chat.completions.create(
+                model=args.model,
+                messages=[{"role": "user", "content": "ping"}],
+                max_tokens=1,
+            )
+            print(json.dumps({"ok": True, "gateway": gw.base_url, "response": resp}, indent=2))
+        except GatewayError as e:
+            raise SystemExit(f"gateway test failed: HTTP {e.status}: {e.body[:300]}")
+
+    # ── config publish / validate (Routing Fabric /api/routing/*) ─────────────
+    elif args.cmd == "config" and args.ccmd == "publish":
+        body = _read_json_file(args.file)
+        name = args.name or body.get("name") or "default"
+        created = _api("POST", "/api/routing/configs", body={"name": name, "body": body.get("body", body)})
+        cfg_id = created.get("id")
+        if not cfg_id:
+            raise SystemExit(f"create failed: {json.dumps(created)}")
+        published = _api("POST", f"/api/routing/configs/{cfg_id}/publish")
+        print(json.dumps({"published": True, "id": cfg_id, "name": name, "result": published}, indent=2))
+    elif args.cmd == "config" and args.ccmd == "validate":
+        body = _read_json_file(args.file)
+        # Routing Fabric's simulate endpoint dry-runs a config without persisting.
+        out = _api("POST", "/api/routing/simulate", body={"config": body.get("body", body)})
+        print(json.dumps(out, indent=2))
+
+    # ── prompt push (Prompt Registry /api/prompts/*) ──────────────────────────
+    elif args.cmd == "prompt" and args.pcmd == "push":
+        body = _read_json_file(args.file)
+        print(json.dumps(_api("POST", "/api/prompts", body=body), indent=2))
+
+    # ── log tail (gateway receipt tail w/ trace_id — sdk devex /api/sdk/logs) ──
+    elif args.cmd == "log" and args.lcmd == "tail":
+        out = _api("GET", "/api/sdk/logs", query={"limit": args.limit, "since": args.since})
+        for row in out.get("logs", []):
+            print(json.dumps(row))
+
+    # ── proof verify / bundle (Proof Mesh /api/proof/*) ───────────────────────
+    elif args.cmd == "proof" and args.prcmd == "verify":
+        out = _api("GET", "/api/proof/verify", query={"hash": args.hash})
+        print(json.dumps(out, indent=2))
+        if not out.get("verified"):
+            raise SystemExit(2)
+    elif args.cmd == "proof" and args.prcmd == "bundle":
+        print(json.dumps(_api("GET", "/api/proof/bundle", query={"hash": args.hash}), indent=2))
+
+    # ── models (Model Garden catalog, D8) ─────────────────────────────────────
+    elif args.cmd == "models":
+        out = _api("GET", "/api/model-garden/catalog", query={
+            "provider": args.provider, "modality": args.modality, "q": args.q,
+            "includeDeprecated": "true" if args.include_deprecated else None,
+        })
+        rows = out if isinstance(out, list) else (
+            out.get("models") or out.get("catalog") or out.get("data") or out.get("rows") or []
+        )
+        print(json.dumps(rows, indent=2))
+
+
+if __name__ == "__main__":
+    main()

agentics_you/client.py

@@ -0,0 +1,201 @@
+"""Agentics SDK client + Task context manager."""
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+import hashlib
+import threading
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterable, List, Optional
+from urllib import request as _request
+from urllib.error import URLError, HTTPError
+
+from .version import __version__
+
+DEFAULT_BASE_URL = "https://agentics.you"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _sha256(s: str) -> str:
+    return hashlib.sha256(s.encode("utf-8") if isinstance(s, str) else s).hexdigest()
+
+
+@dataclass
+class Task:
+    agent_id: str
+    foundation_model: str
+    model_version: str
+    system_prompt: str = ""
+    tool_manifest: Any = None
+    scope: List[str] = field(default_factory=list)
+    task_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    started_at: str = field(default_factory=_now_iso)
+    finished_at: Optional[str] = None
+    outcome: str = "success"
+    cost_usd: float = 0.0
+    tokens_in: int = 0
+    tokens_out: int = 0
+    scope_used: List[str] = field(default_factory=list)
+    inputs: str = ""
+    outputs: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def set_inputs(self, text: str) -> None:
+        self.inputs = text
+
+    def set_outputs(self, text: str) -> None:
+        self.outputs = text
+
+    def set_outcome(self, outcome: str) -> None:
+        if outcome not in ("success", "partial", "failed"):
+            raise ValueError("outcome must be one of: success | partial | failed")
+        self.outcome = outcome
+
+    def add_usage(self, *, tokens_in: int = 0, tokens_out: int = 0, cost_usd: float = 0.0) -> None:
+        self.tokens_in += tokens_in
+        self.tokens_out += tokens_out
+        self.cost_usd += cost_usd
+
+    def use_scope(self, scope: str) -> None:
+        if scope not in self.scope_used:
+            self.scope_used.append(scope)
+
+    def to_payload(self) -> Dict[str, Any]:
+        return {
+            "event_id": self.task_id,
+            "agent": {
+                "external_id": self.agent_id,
+                "foundation_model": self.foundation_model,
+                "model_version": self.model_version,
+                "system_prompt": self.system_prompt,
+                "tool_manifest": self.tool_manifest,
+                "scope": self.scope,
+            },
+            "task": {
+                "task_id": self.task_id,
+                "started_at": self.started_at,
+                "finished_at": self.finished_at or _now_iso(),
+                "outcome": self.outcome,
+                "cost_usd": self.cost_usd,
+                "tokens_in": self.tokens_in,
+                "tokens_out": self.tokens_out,
+                "scope_used": self.scope_used,
+                "inputs": self.inputs,
+                "outputs": self.outputs,
+                "metadata": self.metadata,
+            },
+        }
+
+
+class TaskContext:
+    """Context manager that auto-emits a receipt on exit."""
+
+    def __init__(self, client: "Agentics", task: Task) -> None:
+        self.client = client
+        self.task = task
+
+    def __enter__(self) -> Task:
+        return self.task
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if exc:
+            self.task.set_outcome("failed")
+            self.task.metadata["error"] = repr(exc)
+        self.task.finished_at = _now_iso()
+        try:
+            self.client.send(self.task)
+        except Exception:  # never break the caller because telemetry failed
+            pass
+
+
+class Agentics:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 5.0,
+        async_buffer: bool = True,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("AGENTICS_API_KEY", "")
+        if not self.api_key:
+            raise RuntimeError("Agentics SDK: AGENTICS_API_KEY required")
+        self.base_url = base_url or os.environ.get("AGENTICS_BASE_URL", DEFAULT_BASE_URL)
+        self.timeout = timeout
+        self._buffer: List[Dict[str, Any]] = []
+        self._buffer_lock = threading.Lock()
+        self._async = async_buffer
+        if async_buffer:
+            self._flusher = threading.Thread(target=self._flush_loop, daemon=True)
+            self._flusher.start()
+
+    def track(
+        self,
+        *,
+        agent_id: str,
+        foundation_model: str,
+        model_version: str = "",
+        system_prompt: str = "",
+        tool_manifest: Any = None,
+        scope: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> TaskContext:
+        return TaskContext(self, Task(
+            agent_id=agent_id, foundation_model=foundation_model,
+            model_version=model_version, system_prompt=system_prompt,
+            tool_manifest=tool_manifest, scope=list(scope or []),
+            metadata=dict(metadata or {}),
+        ))
+
+    def send(self, task: Task) -> None:
+        payload = task.to_payload()
+        if self._async:
+            with self._buffer_lock:
+                self._buffer.append(payload)
+        else:
+            self._post(payload)
+
+    def send_batch(self, tasks: Iterable[Task]) -> Dict[str, Any]:
+        return self._post({"batch": [t.to_payload() for t in tasks]})
+
+    def flush(self) -> None:
+        with self._buffer_lock:
+            items = self._buffer[:]
+            self._buffer.clear()
+        if not items:
+            return
+        try:
+            self._post({"batch": items})
+        except Exception:
+            with self._buffer_lock:
+                self._buffer.extend(items[:1000])
+
+    def _flush_loop(self) -> None:
+        while True:
+            time.sleep(2.0)
+            self.flush()
+
+    def _post(self, body: Dict[str, Any]) -> Dict[str, Any]:
+        data = json.dumps(body).encode("utf-8")
+        req = _request.Request(
+            f"{self.base_url}/api/sdk/ingest",
+            data=data,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.api_key}",
+                "User-Agent": f"agentics-python/{__version__}",
+            },
+            method="POST",
+        )
+        try:
+            with _request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except HTTPError as e:
+            return {"error": "http", "status": e.code, "body": e.read().decode("utf-8", "ignore")}
+        except URLError as e:
+            return {"error": "network", "reason": str(e)}