spctre-sdk 0.1.0__tar.gz

spctre_sdk-0.1.0/.gitignore

@@ -0,0 +1,60 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# pnpm is the sole package manager; reject stray npm/yarn lockfiles
+package-lock.json
+yarn.lock
+
+# Environment and local secrets
+.env
+.env.*
+!.env*.example
+
+# Build outputs
+dist/
+target/
+apps/web/.next/
+apps/web/.source/
+apps/worker/dist/
+packages/cli/dist/
+packages/mcp-server/dist/
+packages/policy-schema/dist/
+packages/policy-schema/native/target/
+packages/ui/storybook-static/
+
+# Caches and test output
+.turbo/
+.cache/
+coverage/
+cover.out
+.nyc_output/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.tsbuildinfo
+
+# Native artifacts
+*.node
+
+# Local tooling
+.venv/
+.agents/
+.antigravitycli/
+.claude/
+.codex/
+.impeccable/
+.vscode/
+.idea/
+.spctre/
+packages/cli/.spctre/
+.polly/
+.worktrees/
+.pi/
+
+# Local notes and OS files
+concepts/
+.DS_Store
+.playwright-cli/
+DESIGN.md
+PRODUCT.md

spctre_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: spctre-sdk
+Version: 0.1.0
+Summary: Python SDK for the Spctre policy operations control plane.
+Project-URL: Homepage, https://spctre.dev
+Project-URL: Source, https://github.com/getspctre/spctre
+Author-email: Spctre <support@spctre.dev>
+License-Expression: Apache-2.0
+Keywords: agents,governance,policy,spctre
+Requires-Python: >=3.11
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: httpx<0.29.0,>=0.23.0
+Requires-Dist: python-dateutil>=2.8.0
+Provides-Extra: test
+Requires-Dist: pyrefly==1.1.0; extra == 'test'
+Requires-Dist: pytest>=9.0.3; extra == 'test'
+Description-Content-Type: text/markdown
+
+# spctre-sdk
+
+Python client for the [Spctre](https://spctre.dev) policy operations control plane.
+
+```sh
+pip install spctre-sdk
+```
+
+Requires Python 3.11+.
+
+## Usage
+
+```python
+from spctre import SpctreClient
+from spctre.models import GatewayDecisionRequest
+
+client = SpctreClient(
+    base_url="https://app-staging.spctre.dev",
+    token=token,
+)
+
+decision = client.gateway.decide(
+    GatewayDecisionRequest(
+        decision_id="d-1",
+        artifact_hash="sha256:...",
+        policy_context=[...],
+    )
+)
+
+if decision.decision.outcome.value == "PROCEED":
+    ...  # act
+    client.evidence.ingest(record)
+```
+
+`base_url` is the deployment origin, not the API root — the client owns the
+`/api/v1` path segment. Staging, production and self-hosted deployments differ
+only in this value:
+
+| Given                                 | Requests go to                                   |
+| ------------------------------------- | ------------------------------------------------ |
+| `https://app-staging.spctre.dev`      | `https://app-staging.spctre.dev/api/v1/...`      |
+| `http://localhost:3000`               | `http://localhost:3000/api/v1/...`               |
+| `https://internal.example.com/spctre` | `https://internal.example.com/spctre/api/v1/...` |
+
+A URL that already ends in `/api/v1` is accepted as-is rather than doubled.
+
+## Domains
+
+The client is organized by product domain, following the control-plane loop:
+policy changes become published controls, controls produce enforced decisions,
+decisions produce evidence, evidence supports assurance.
+
+| Domain                | Operations                                                                              |
+| --------------------- | --------------------------------------------------------------------------------------- |
+| `client.gateway`      | `decide`, `resolve`, `escalation_status`, `list_escalations`, `register_agt_escalation` |
+| `client.evidence`     | `ingest`, `ingest_git_checkpoint`, `forensic_query`                                     |
+| `client.policy`       | `import_policy`                                                                         |
+| `client.trust`        | `ingest_score`, `evaluate`, `ingest_context_budget`                                     |
+| `client.verification` | `ingest`, `list`                                                                        |
+| `client.bundle`       | `latest`, `retain_latest`                                                               |
+| `client.compliance`   | `export`                                                                                |
+| `client.approvals`    | `get`                                                                                   |
+
+Models come from `spctre.models`. Field names are snake_case in Python and are
+serialized to the API's camelCase automatically.
+
+Operations outside these domains — SCIM, auth token rotation, blueprint import,
+simulation — are reachable through `spctre._generated`, which is regenerated
+wholesale from the OpenAPI spec and carries no stability promise. Anything you
+find yourself needing there is a reasonable thing to request as a facade
+addition.
+
+## Errors
+
+Every failure is raised as a `SpctreError` subclass. Generated exceptions never
+escape:
+
+| Raised                  | When                                        |
+| ----------------------- | ------------------------------------------- |
+| `SpctreAuthError`       | 401: token missing, expired, or revoked     |
+| `SpctrePermissionError` | 403: token lacks the required scope         |
+| `SpctreRequestError`    | other 4xx                                   |
+| `SpctreServerError`     | 5xx                                         |
+| `SpctreTransportError`  | no HTTP response at all (DNS, TLS, timeout) |
+| `SpctreResponseError`   | answered, but the response did not parse    |
+
+Each carries `status`, `body`, and `trace_id` lifted from the response
+envelope's `meta.traceId` — quote it when reporting a problem.
+
+`SpctreResponseError` is deliberately distinct from `SpctreTransportError`: it
+means the client and the deployment disagree about the API contract, usually an
+SDK too old or too new for the server. Reporting that as an unreachable host
+would send debugging in the wrong direction.
+
+## Testing
+
+`transport=` accepts any `httpx.BaseTransport`, so tests need no network:
+
+```python
+import httpx
+from spctre import SpctreClient
+
+
+def handler(request: httpx.Request) -> httpx.Response:
+    assert request.url.path == "/api/v1/gateway/decide"
+    return httpx.Response(200, json={...})
+
+
+client = SpctreClient(
+    base_url="https://app.example.com",
+    token="test-token",
+    transport=httpx.MockTransport(handler),
+)
+```
+
+## How this package is built
+
+`spctre._generated` is produced by
+[openapi-python-client](https://github.com/openapi-generators/openapi-python-client)
+from the control plane's OpenAPI spec, at a pinned generator version. Unlike
+most generated code in this repository it is **checked in**, so installing or
+building the package needs no code generator, and CI can assert the committed
+client still matches the spec.
+
+## License
+
+Apache-2.0

spctre_sdk-0.1.0/README.md

@@ -0,0 +1,127 @@
+# spctre-sdk
+
+Python client for the [Spctre](https://spctre.dev) policy operations control plane.
+
+```sh
+pip install spctre-sdk
+```
+
+Requires Python 3.11+.
+
+## Usage
+
+```python
+from spctre import SpctreClient
+from spctre.models import GatewayDecisionRequest
+
+client = SpctreClient(
+    base_url="https://app-staging.spctre.dev",
+    token=token,
+)
+
+decision = client.gateway.decide(
+    GatewayDecisionRequest(
+        decision_id="d-1",
+        artifact_hash="sha256:...",
+        policy_context=[...],
+    )
+)
+
+if decision.decision.outcome.value == "PROCEED":
+    ...  # act
+    client.evidence.ingest(record)
+```
+
+`base_url` is the deployment origin, not the API root — the client owns the
+`/api/v1` path segment. Staging, production and self-hosted deployments differ
+only in this value:
+
+| Given                                 | Requests go to                                   |
+| ------------------------------------- | ------------------------------------------------ |
+| `https://app-staging.spctre.dev`      | `https://app-staging.spctre.dev/api/v1/...`      |
+| `http://localhost:3000`               | `http://localhost:3000/api/v1/...`               |
+| `https://internal.example.com/spctre` | `https://internal.example.com/spctre/api/v1/...` |
+
+A URL that already ends in `/api/v1` is accepted as-is rather than doubled.
+
+## Domains
+
+The client is organized by product domain, following the control-plane loop:
+policy changes become published controls, controls produce enforced decisions,
+decisions produce evidence, evidence supports assurance.
+
+| Domain                | Operations                                                                              |
+| --------------------- | --------------------------------------------------------------------------------------- |
+| `client.gateway`      | `decide`, `resolve`, `escalation_status`, `list_escalations`, `register_agt_escalation` |
+| `client.evidence`     | `ingest`, `ingest_git_checkpoint`, `forensic_query`                                     |
+| `client.policy`       | `import_policy`                                                                         |
+| `client.trust`        | `ingest_score`, `evaluate`, `ingest_context_budget`                                     |
+| `client.verification` | `ingest`, `list`                                                                        |
+| `client.bundle`       | `latest`, `retain_latest`                                                               |
+| `client.compliance`   | `export`                                                                                |
+| `client.approvals`    | `get`                                                                                   |
+
+Models come from `spctre.models`. Field names are snake_case in Python and are
+serialized to the API's camelCase automatically.
+
+Operations outside these domains — SCIM, auth token rotation, blueprint import,
+simulation — are reachable through `spctre._generated`, which is regenerated
+wholesale from the OpenAPI spec and carries no stability promise. Anything you
+find yourself needing there is a reasonable thing to request as a facade
+addition.
+
+## Errors
+
+Every failure is raised as a `SpctreError` subclass. Generated exceptions never
+escape:
+
+| Raised                  | When                                        |
+| ----------------------- | ------------------------------------------- |
+| `SpctreAuthError`       | 401: token missing, expired, or revoked     |
+| `SpctrePermissionError` | 403: token lacks the required scope         |
+| `SpctreRequestError`    | other 4xx                                   |
+| `SpctreServerError`     | 5xx                                         |
+| `SpctreTransportError`  | no HTTP response at all (DNS, TLS, timeout) |
+| `SpctreResponseError`   | answered, but the response did not parse    |
+
+Each carries `status`, `body`, and `trace_id` lifted from the response
+envelope's `meta.traceId` — quote it when reporting a problem.
+
+`SpctreResponseError` is deliberately distinct from `SpctreTransportError`: it
+means the client and the deployment disagree about the API contract, usually an
+SDK too old or too new for the server. Reporting that as an unreachable host
+would send debugging in the wrong direction.
+
+## Testing
+
+`transport=` accepts any `httpx.BaseTransport`, so tests need no network:
+
+```python
+import httpx
+from spctre import SpctreClient
+
+
+def handler(request: httpx.Request) -> httpx.Response:
+    assert request.url.path == "/api/v1/gateway/decide"
+    return httpx.Response(200, json={...})
+
+
+client = SpctreClient(
+    base_url="https://app.example.com",
+    token="test-token",
+    transport=httpx.MockTransport(handler),
+)
+```
+
+## How this package is built
+
+`spctre._generated` is produced by
+[openapi-python-client](https://github.com/openapi-generators/openapi-python-client)
+from the control plane's OpenAPI spec, at a pinned generator version. Unlike
+most generated code in this repository it is **checked in**, so installing or
+building the package needs no code generator, and CI can assert the committed
+client still matches the spec.
+
+## License
+
+Apache-2.0

spctre_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spctre-sdk"
+dynamic = ["version"]
+description = "Python SDK for the Spctre policy operations control plane."
+readme = "README.md"
+# 3.11, not 3.10: the generated client parses timestamps with
+# datetime.fromisoformat, which did not accept the trailing `Z` until 3.11, and
+# every API response carries a required meta.ts. Matches the adapter packages.
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "Spctre", email = "support@spctre.dev" }]
+keywords = ["spctre", "policy", "governance", "agents"]
+dependencies = [
+  "httpx >= 0.23.0, < 0.29.0",
+  "attrs >= 22.2.0",
+  "python-dateutil >= 2.8.0",
+]
+
+[project.urls]
+Homepage = "https://spctre.dev"
+Source = "https://github.com/getspctre/spctre"
+
+[project.optional-dependencies]
+test = [
+  "pytest>=9.0.3",
+  "pyrefly==1.1.0",
+]
+
+# Single source of truth for the version, matching the adapter packages. The
+# release workflow rewrites this file to stamp a .devN suffix for TestPyPI.
+[tool.hatch.version]
+path = "spctre/_version.py"
+
+# One top-level package. spctre/_generated is generated by
+# scripts/generate-python-sdk.sh but IS checked in, so building needs no code
+# generator.
+[tool.hatch.build.targets.wheel]
+packages = ["spctre"]
+
+[tool.hatch.build.targets.sdist]
+include = ["spctre", "README.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.pyrefly]
+# The generated tree is checked by its own generator's conventions, not ours;
+# type-checking it would report the generator's style, which we cannot fix.
+project-includes = ["spctre", "tests"]
+project-excludes = ["spctre/_generated/**"]
+# pytest puts the rootdir's tests/ directory on sys.path, which is how the
+# test modules import shared helpers from conftest. Tell the checker the same.
+search-path = [".", "tests"]

spctre_sdk-0.1.0/spctre/__init__.py

@@ -0,0 +1,43 @@
+"""Supported Python client for the Spctre control plane.
+
+    from spctre import SpctreClient
+
+    client = SpctreClient(base_url="https://app-staging.spctre.dev", token=token)
+    decision = client.gateway.decide(request)
+
+Request and response models live in `spctre.models`. The full generated
+surface, including operations the facade does not wrap, is under
+`spctre._generated` — regenerated wholesale from the OpenAPI spec and not
+covered by this package's stability promise.
+"""
+
+from . import models
+from ._url import API_PREFIX, normalize_base_url
+from ._version import __version__
+from .client import UNSET, SpctreClient, Unset
+from .errors import (
+    SpctreAuthError,
+    SpctreError,
+    SpctrePermissionError,
+    SpctreRequestError,
+    SpctreResponseError,
+    SpctreServerError,
+    SpctreTransportError,
+)
+
+__all__ = [
+    "API_PREFIX",
+    "SpctreAuthError",
+    "SpctreClient",
+    "SpctreError",
+    "SpctrePermissionError",
+    "SpctreRequestError",
+    "SpctreResponseError",
+    "SpctreServerError",
+    "SpctreTransportError",
+    "UNSET",
+    "Unset",
+    "__version__",
+    "models",
+    "normalize_base_url",
+]

spctre_sdk-0.1.0/spctre/_generated/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing Spctre API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

spctre_sdk-0.1.0/spctre/_generated/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

spctre_sdk-0.1.0/spctre/_generated/api/approvals/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

spctre_sdk-0.1.0/spctre/_generated/api/approvals/get_approval.py

@@ -0,0 +1,174 @@
+from http import HTTPStatus
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.api_error import ApiError
+from ...models.approval_response import ApprovalResponse
+from ...types import Response
+
+
+def _get_kwargs(
+    id: str,
+) -> dict[str, Any]:
+
+    _kwargs: dict[str, Any] = {
+        "method": "get",
+        "url": "/approvals/{id}".format(
+            id=quote(str(id), safe=""),
+        ),
+    }
+
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> ApiError | ApprovalResponse | None:
+    if response.status_code == 200:
+        response_200 = ApprovalResponse.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 401:
+        response_401 = ApiError.from_dict(response.json())
+
+        return response_401
+
+    if response.status_code == 404:
+        response_404 = ApiError.from_dict(response.json())
+
+        return response_404
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[ApiError | ApprovalResponse]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    id: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> Response[ApiError | ApprovalResponse]:
+    """Get an approval by ID
+
+     Returns the approval record for a specific revision approval ID.
+
+    Args:
+        id (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ApiError | ApprovalResponse]
+    """
+
+    kwargs = _get_kwargs(
+        id=id,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    id: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> ApiError | ApprovalResponse | None:
+    """Get an approval by ID
+
+     Returns the approval record for a specific revision approval ID.
+
+    Args:
+        id (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ApiError | ApprovalResponse
+    """
+
+    return sync_detailed(
+        id=id,
+        client=client,
+    ).parsed
+
+
+async def asyncio_detailed(
+    id: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> Response[ApiError | ApprovalResponse]:
+    """Get an approval by ID
+
+     Returns the approval record for a specific revision approval ID.
+
+    Args:
+        id (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[ApiError | ApprovalResponse]
+    """
+
+    kwargs = _get_kwargs(
+        id=id,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    id: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> ApiError | ApprovalResponse | None:
+    """Get an approval by ID
+
+     Returns the approval record for a specific revision approval ID.
+
+    Args:
+        id (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        ApiError | ApprovalResponse
+    """
+
+    return (
+        await asyncio_detailed(
+            id=id,
+            client=client,
+        )
+    ).parsed

spctre_sdk-0.1.0/spctre/_generated/api/auth/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""