getstack 0.14.0__tar.gz → 0.16.0__tar.gz

{getstack-0.14.0 → getstack-0.16.0}/CLAUDE.md

@@ -12,7 +12,7 @@ Published to PyPI as `getstack`. Not a workspace member of the main monorepo
   `AsyncStack`): agents, passports (+ delegate + revoke-agent/session/all +
   list_active), services (+ connect + grant/revoke/get_permissions),
   credentials, drop-offs (+ expire), skills, identity, audit, notifications
-  (+ update), security-events, proxy, scan, intents, missions,
+  (+ update), security-events, proxy, scan, usage, intents, missions,
   evidence-packs, llm gateway, inbound-webhooks, partner, **team**,
   **delivery_methods**, **detector_config**.
 - **Offline / customer-managed crypto** (the JS headline features):

{getstack-0.14.0 → getstack-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getstack
-Version: 0.14.0
+Version: 0.16.0
 Summary: Python SDK for STACK — trust infrastructure for AI agents
 Project-URL: Homepage, https://getstack.run
 Project-URL: Documentation, https://getstack.run/docs/sdk

{getstack-0.14.0 → getstack-0.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "getstack"
-version = "0.14.0"
+version = "0.16.0"
 description = "Python SDK for STACK — trust infrastructure for AI agents"
 readme = "README.md"
 license = "MIT"

{getstack-0.14.0 → getstack-0.16.0}/src/getstack/__init__.py

@@ -49,6 +49,7 @@ from .notifications import NotificationService
 from .audit import AuditService
 from .proxy import ProxyService as ProxySvc, ProxyResponse
 from .scan import ScanService
+from .usage import UsageService
 from .security_events import SecurityEventService as SecurityEventSvc
 from .skills import SkillService
 from .identity import IdentityService
@@ -233,6 +234,7 @@ class Stack:
         self.audit = AuditService(self._client)
         self.proxy = ProxySvc(self._client)
         self.scan = ScanService(self._client)
+        self.usage = UsageService(self._client)
         self.security_events = SecurityEventSvc(self._client)
         self.skills = SkillService(self._client)
         self.identity = IdentityService(self._client)
@@ -378,6 +380,7 @@ class AsyncStack:
         from ._async.audit import AsyncAuditService
         from ._async.proxy import AsyncProxyService
         from ._async.scan import AsyncScanService
+        from ._async.usage import AsyncUsageService
         from ._async.security_events import AsyncSecurityEventService
         from ._async.skills import AsyncSkillService
         from ._async.identity import AsyncIdentityService
@@ -402,6 +405,7 @@ class AsyncStack:
         self.audit = AsyncAuditService(self._client)
         self.proxy = AsyncProxyService(self._client)
         self.scan = AsyncScanService(self._client)
+        self.usage = AsyncUsageService(self._client)
         self.security_events = AsyncSecurityEventService(self._client)
         self.skills = AsyncSkillService(self._client)
         self.identity = AsyncIdentityService(self._client)

{getstack-0.14.0 → getstack-0.16.0}/src/getstack/_async/agents.py

@@ -23,10 +23,15 @@ class AsyncAgentService:
         key_mode: str | None = None,
         on_warning: str = "notify",
         on_critical: str = "notify",
+        llm_inject_system_prompt: bool | None = None,
+        llm_redact_pii: bool | None = None,
     ) -> Agent:
         """Register an agent. See the sync :meth:`AgentService.register`
         docstring — pass ``profile="proxied-llm-bot"`` for a bot that just
-        runs. Unset fields are not sent, so they never clobber a preset."""
+        runs. Unset fields are not sent, so they never clobber a preset.
+        The GET-245 LLM gateway toggles both default True server-side;
+        ``llm_redact_pii=False`` sends user PII to the LLM provider
+        unredacted (explicit operator decision) and False IS sent."""
         body: dict[str, Any] = {"name": name}
         if description:
             body["description"] = description
@@ -42,6 +47,11 @@ class AsyncAgentService:
             body["on_warning"] = on_warning
         if on_critical != "notify":
             body["on_critical"] = on_critical
+        # is-not-None (not truthiness) so an explicit False reaches the wire.
+        if llm_inject_system_prompt is not None:
+            body["llm_inject_system_prompt"] = llm_inject_system_prompt
+        if llm_redact_pii is not None:
+            body["llm_redact_pii"] = llm_redact_pii
         return _to_agent(await self._client.post("/v1/agents/register", json=body))
 
     async def get(self, agent_id: str) -> Agent:
@@ -52,6 +62,9 @@ class AsyncAgentService:
         return [_to_agent(a) for a in data]
 
     async def update(self, agent_id: str, **kwargs: Any) -> Agent:
+        """PATCH mutable agent fields, passed through as-is — including
+        the GET-245 LLM gateway toggles; see the sync
+        :meth:`AgentService.update`."""
         return _to_agent(await self._client.patch(f"/v1/agents/{agent_id}", json=kwargs))
 
     async def suspend(self, agent_id: str) -> Agent:

getstack-0.16.0/src/getstack/_async/usage.py

@@ -0,0 +1,15 @@
+"""Async mirror of UsageService."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..client import AsyncHttpClient
+
+
+class AsyncUsageService:
+    def __init__(self, client: AsyncHttpClient):
+        self._client = client
+
+    async def get(self) -> dict[str, Any]:
+        return await self._client.request("GET", "/v1/usage")

{getstack-0.14.0 → getstack-0.16.0}/src/getstack/agents.py

@@ -28,6 +28,10 @@ def _to_agent(data: dict[str, Any]) -> Agent:
         updated_at=data["updated_at"],
         credential_access=data.get("credential_access", "direct"),
         key_mode=data.get("key_mode", "stack_managed"),
+        # GET-245 — LLM gateway toggles; True mirrors the DB default
+        # (fail-closed) when an older API omits them.
+        llm_inject_system_prompt=data.get("llm_inject_system_prompt", True),
+        llm_redact_pii=data.get("llm_redact_pii", True),
     )
 
 
@@ -45,6 +49,8 @@ class AgentService:
         key_mode: str | None = None,
         on_warning: str = "notify",
         on_critical: str = "notify",
+        llm_inject_system_prompt: bool | None = None,
+        llm_redact_pii: bool | None = None,
     ) -> Agent:
         """Register an agent.
 
@@ -59,6 +65,14 @@ class AgentService:
         server default (``enforced`` + ``direct``) OR the profile value —
         they are only sent when provided, so an unset value never clobbers
         a preset.
+
+        ``llm_inject_system_prompt`` / ``llm_redact_pii`` tune the
+        ``/v1/llm/*`` gateway per agent (both default True server-side):
+        inject prepends the STACK security context to every gateway call;
+        redact replaces PII in user messages before forwarding.
+        ``llm_redact_pii=False`` means user PII flows to the LLM provider
+        unredacted — an explicit operator decision. ``False`` is sent on
+        the wire; only ``None`` (unset) is omitted.
         """
         body: dict[str, Any] = {"name": name}
         if description:
@@ -75,6 +89,11 @@ class AgentService:
             body["on_warning"] = on_warning
         if on_critical != "notify":
             body["on_critical"] = on_critical
+        # is-not-None (not truthiness) so an explicit False reaches the wire.
+        if llm_inject_system_prompt is not None:
+            body["llm_inject_system_prompt"] = llm_inject_system_prompt
+        if llm_redact_pii is not None:
+            body["llm_redact_pii"] = llm_redact_pii
         return _to_agent(self._client.post("/v1/agents/register", json=body))
 
     def get(self, agent_id: str) -> Agent:
@@ -85,6 +104,11 @@ class AgentService:
         return [_to_agent(a) for a in data]
 
     def update(self, agent_id: str, **kwargs: Any) -> Agent:
+        """PATCH mutable agent fields, passed through as-is. The GET-245
+        LLM gateway toggles (``llm_inject_system_prompt``,
+        ``llm_redact_pii``) ride here too — see :meth:`register` for
+        semantics; ``llm_redact_pii=False`` sends user PII to the LLM
+        provider unredacted."""
         return _to_agent(self._client.patch(f"/v1/agents/{agent_id}", json=kwargs))
 
     def suspend(self, agent_id: str) -> Agent:

{getstack-0.14.0 → getstack-0.16.0}/src/getstack/types.py

@@ -28,6 +28,13 @@ class Agent:
     # see whether the box needs an agent keypair (customer_managed) or the
     # operator credential (stack_managed). Defaulted for older responses.
     key_mode: str = "stack_managed"
+    # GET-245 — per-agent LLM gateway toggles. Both default true at the DB
+    # (fail-closed): inject prepends the STACK security context to /v1/llm/*
+    # calls; redact replaces PII in user messages before forwarding. False on
+    # llm_redact_pii means user PII reaches the LLM provider unredacted.
+    # Defaulted for older API responses that predate the fields.
+    llm_inject_system_prompt: bool = True
+    llm_redact_pii: bool = True
 
 
 @dataclass

getstack-0.16.0/src/getstack/usage.py

@@ -0,0 +1,37 @@
+"""Usage service — `/v1/usage` (usage + spend + earnings rollup).
+
+The one-call rollup of what your operator consumed against its plan,
+spent, and earned this billing period. Superset of the per-domain meters
+(`stack.scan.usage()`, `stack.llm.usage`, `stack.proxy` counts) — one
+authoritative shape the CLI and dashboard read too. Money fields are in
+cents.
+
+Example::
+
+    u = stack.usage.get()
+    p = u["consumption"]["passports"]
+    print(f"Passports {p['used']}/{p['limit']}")
+    print(f"Spent this period: ${u['spend_cents']['total'] / 100:.2f}")
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import HttpClient
+
+
+class UsageService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def get(self) -> dict[str, Any]:
+        """Usage, spend, and earnings for the current billing period.
+
+        Returns:
+            Dict with keys: tier, period_start, period_end, consumption
+            (per-meter {used, limit}), spend_cents (skills / llm_compute /
+            identity / overage / total), wallet_cents ({balance}), and
+            earnings_cents ({unpaid, lifetime}). All money in cents.
+        """
+        return self._client.request("GET", "/v1/usage")

{getstack-0.14.0 → getstack-0.16.0}/tests/test_parity.py

@@ -32,8 +32,8 @@ from getstack import (  # noqa: E402
 # Services that must exist on BOTH clients.
 EXPECTED_SERVICES = [
     "agents", "passports", "credentials", "services", "dropoffs", "reviews",
-    "notifications", "audit", "proxy", "scan", "security_events", "skills",
-    "identity", "intents", "missions", "evidence_packs", "llm",
+    "notifications", "audit", "proxy", "scan", "usage", "security_events",
+    "skills", "identity", "intents", "missions", "evidence_packs", "llm",
     "inbound_webhooks", "partner_tenants", "team", "delivery_methods",
     "detector_config",
 ]
@@ -58,6 +58,7 @@ EXPECTED_METHODS = [
     ("team", "invite"),
     ("delivery_methods", "add"),
     ("detector_config", "upsert"),
+    ("usage", "get"),
 ]
 
 
@@ -88,6 +89,74 @@ def test_register_accepts_key_mode_on_both():
     for client in (s, a):
         params = inspect.signature(client.agents.register).parameters
         assert "profile" in params and "credential_access" in params
+        # GET-245 LLM gateway toggles.
+        assert "llm_inject_system_prompt" in params and "llm_redact_pii" in params
+
+
+# Minimal valid agent response for _to_agent; llm_redact_pii=False proves
+# the response field lands on the model instead of the True fallback.
+_AGENT_RESPONSE = {
+    "id": "agent_x", "operator_id": "op_x", "name": "bot", "status": "active",
+    "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z",
+    "llm_inject_system_prompt": True, "llm_redact_pii": False,
+}
+
+
+class _CaptureClient:
+    """Stands in for HttpClient/AsyncHttpClient; records the last body."""
+
+    def __init__(self, is_async: bool = False):
+        self.is_async = is_async
+        self.json = None
+
+    def _record(self, json):
+        self.json = json
+        return dict(_AGENT_RESPONSE)
+
+    def post(self, path, json=None, **kw):
+        if self.is_async:
+            async def _coro():
+                return self._record(json)
+            return _coro()
+        return self._record(json)
+
+    patch = post
+
+
+def test_register_llm_toggles_round_trip_sync():
+    s, _ = _clients()
+    s.agents._client = stub = _CaptureClient()
+    agent = s.agents.register(
+        "bot", llm_inject_system_prompt=True, llm_redact_pii=False
+    )
+    # Both flags reach the body; explicit False is sent, not dropped.
+    assert stub.json["llm_inject_system_prompt"] is True
+    assert stub.json["llm_redact_pii"] is False
+    # And the response fields land on the Agent model.
+    assert agent.llm_inject_system_prompt is True and agent.llm_redact_pii is False
+    # Unset -> omitted, so the server/profile default is never clobbered.
+    s.agents.register("bot2")
+    assert "llm_inject_system_prompt" not in stub.json
+    assert "llm_redact_pii" not in stub.json
+
+
+def test_register_llm_toggles_round_trip_async():
+    import asyncio
+
+    _, a = _clients()
+    a.agents._client = stub = _CaptureClient(is_async=True)
+    agent = asyncio.run(a.agents.register("bot", llm_redact_pii=False))
+    assert stub.json["llm_redact_pii"] is False
+    assert "llm_inject_system_prompt" not in stub.json
+    assert agent.llm_redact_pii is False
+
+
+def test_update_llm_toggles_pass_through():
+    s, _ = _clients()
+    s.agents._client = stub = _CaptureClient()
+    agent = s.agents.update("agent_x", llm_redact_pii=False)
+    assert stub.json == {"llm_redact_pii": False}
+    assert agent.llm_redact_pii is False
 
 
 def test_offline_crypto_exported():
@@ -104,6 +173,9 @@ if __name__ == "__main__":
     test_both_clients_have_all_services()
     test_both_clients_have_all_methods()
     test_register_accepts_key_mode_on_both()
+    test_register_llm_toggles_round_trip_sync()
+    test_register_llm_toggles_round_trip_async()
+    test_update_llm_toggles_pass_through()
     test_offline_crypto_exported()
     test_service_classes_exported()
     print("all parity tests passed")