primust 1.0.0__tar.gz

primust-1.0.0/.gitignore

@@ -0,0 +1,22 @@
+node_modules/
+dist/
+.next/
+__pycache__/
+*.egg-info/
+.venv/
+.env
+.env.local
+.env.*.local
+*.pyc
+.turbo/
+*.pem
+*.key
+.DS_Store
+.claude/
+.claude.json
+.claude.json.backup
+.pytest_cache/
+*.db
+*.db-shm
+*.db-wal
+.vercel

primust-1.0.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: primust
+Version: 1.0.0
+Summary: Prove your governance checks ran. Portable, offline-verifiable cryptographic credentials.
+Project-URL: Homepage, https://primust.com
+Project-URL: Documentation, https://docs.primust.com
+Project-URL: Verify, https://verify.primust.com
+Author-email: "Primust, Inc." <eng@primust.com>
+License-Expression: LicenseRef-Proprietary
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=41.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: primust-artifact-core>=1.0.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'

primust-1.0.0/README.md

@@ -0,0 +1,183 @@
+# Primust Python SDK
+
+Prove governance ran. Disclose nothing.
+
+```bash
+pip install primust
+```
+
+## What this is
+
+Primust issues **Verifiable Process Execution Credentials (VPECs)** — portable, offline-verifiable proofs that a defined governance process executed correctly on specific data, without disclosing the data.
+
+A VPEC answers: *"Did your AML screening actually run on this entity?"* — without your watchlist matching criteria, velocity thresholds, or customer data leaving your environment.
+
+## Quickstart
+
+```python
+import primust
+
+p = primust.Pipeline(
+    api_key="pk_live_...",
+    workflow_id="aml-screening-v2"
+)
+
+run = p.open()
+
+result = run.record(
+    check="aml_entity_screen",
+    manifest_id="sha256:abc123...",   # from p.register_check()
+    input=entity_data,                # committed locally — never sent to Primust
+    check_result="pass",
+    visibility="opaque",
+)
+
+# Write result.commitment_hash to your own logs
+# This is your log linkage anchor — connects your logs to the VPEC
+print(result.commitment_hash)  # sha256:...
+
+vpec = run.close()
+# vpec is the signed, portable credential
+# Provide to your regulator. They verify at verify.primust.com
+# without receiving your data.
+```
+
+## Privacy guarantee
+
+Raw input values are committed locally via SHA-256 (Poseidon2 when the native extension is available) before any network call. Only the commitment hash and bounded normalized metadata transit to `api.primust.com`.
+
+**Your data never leaves your environment.**
+
+This is enforced in the SDK — not advisory. The transport layer never receives raw values. Tests verify this by intercepting every outbound HTTP request and asserting sensitive input strings are absent.
+
+## Proof levels
+
+| Level | When | Verifier confidence |
+|---|---|---|
+| `mathematical` | Deterministic rule, arithmetic verifiable | Cryptographic — can replay |
+| `execution` | In-process instrumentation | Strong — execution binding |
+| `witnessed` | Human review with RFC 3161 timing | Regulatory — signed review |
+| `attestation` | API-level observation | Audit — process ran |
+
+The VPEC applies weakest-link: the overall credential level is the lowest level across all checks in the run.
+
+## API reference
+
+### `Pipeline(api_key, workflow_id, ...)`
+
+```python
+p = primust.Pipeline(
+    api_key="pk_live_...",        # or set PRIMUST_API_KEY env var
+    workflow_id="my-workflow",    # identifies the governed process
+    surface_id=None,              # optional: instrumentation surface
+    environment="production",     # inferred from key prefix
+)
+```
+
+### `p.open(policy_pack_id?) → Run`
+
+Opens a governed process run. Returns a `Run`. All `.record()` calls belong to this run. Close with `.close()` to issue the VPEC.
+
+### `run.record(check, manifest_id, check_result, input, ...) → RecordResult`
+
+```python
+result = run.record(
+    check="pii_scan",
+    manifest_id="sha256:...",
+    check_result="pass",          # pass | fail | error | skipped | degraded | override
+    input=content,                # committed locally — never sent
+    details={"score": 0.04},      # bounded metadata — will transit, must not be sensitive
+    output=None,                  # optional output commitment
+    visibility="opaque",          # transparent | selective | opaque
+)
+
+result.commitment_hash   # sha256:... — write this to your logs
+result.record_id         # rec_...
+result.proof_level       # attestation | execution | witnessed | mathematical
+result.queued            # True if API was unreachable — will flush on reconnect
+```
+
+### `run.open_check(check, manifest_id) → CheckSession`
+
+Opens a timed check session. Returns an RFC 3161 timestamp at open time. Pass to `run.record(check_session=...)`. Sub-100ms ML inference emits `check_timing_suspect` gap.
+
+### `run.open_review(check, manifest_id, reviewer_key_id, ...) → ReviewSession`
+
+Opens a Witnessed level human review session. Pass to `run.record(check_session=..., reviewer_signature=..., rationale=...)`.
+
+### `run.close() → VPEC`
+
+Closes the run and issues the VPEC. After close, no further records can be added.
+
+```python
+vpec = run.close()
+
+vpec.vpec_id                  # vpec_...
+vpec.proof_level              # weakest-link across all checks
+vpec.chain_intact             # True if commitment chain is unbroken
+vpec.governance_gaps          # list of GovernanceGap — missing checks, timing anomalies
+vpec.is_clean()               # True if chain intact and zero gaps
+vpec.to_dict()                # full JSON for offline verification
+```
+
+### `p.register_check(manifest) → ManifestRegistration`
+
+Register a check manifest. Call once per manifest version. Returns `manifest_id` — content-addressed SHA-256, idempotent.
+
+## Offline durability
+
+If `api.primust.com` is unreachable, records queue locally in SQLite. The SDK never throws to the caller due to API unavailability. When connectivity recovers, the queue flushes automatically on the next successful call.
+
+If the queue is permanently lost, a `system_unavailable` gap is recorded in the VPEC — the SDK never silently drops governance evidence.
+
+```python
+p.pending_queue_count()   # items waiting in local queue
+p.flush_queue()           # manually trigger flush attempt
+```
+
+## Governance gaps
+
+The VPEC records gaps automatically:
+
+| Gap type | Meaning |
+|---|---|
+| `check_missing` | Expected check in manifest not executed |
+| `check_failed` | Check ran and returned fail |
+| `check_timing_suspect` | Execution time implausibly fast (< 100ms for ML check) |
+| `sequence_gap` | Record sequence broken — possible tampering |
+| `system_unavailable` | Primust API unreachable during run |
+| `policy_config_drift` | Policy changed between run open and close |
+
+## Log linkage
+
+Every `RecordResult` contains a `commitment_hash`. Write this to your operational logs alongside the transaction or decision ID it corresponds to. This creates a verifiable link between your logs and the VPEC — a verifier can confirm your log entry corresponds to a specific record in the credential.
+
+```python
+result = run.record(...)
+logger.info("aml_screen completed",
+    commitment_hash=result.commitment_hash,
+    transaction_id=txn_id,
+)
+```
+
+## Verify a VPEC
+
+```bash
+pip install primust-verify
+primust-verify vpec.json
+```
+
+Or online at [verify.primust.com](https://verify.primust.com) — no account required.
+
+## Requirements
+
+- Python 3.11+
+- `httpx>=0.27.0`
+
+## License
+
+Proprietary — see LICENSE file.
+
+---
+
+[Docs](https://docs.primust.com) · [Verify](https://verify.primust.com) · [Connectors](https://github.com/primust-dev/connectors)

primust-1.0.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "primust"
+version = "1.0.0"
+description = "Prove your governance checks ran. Portable, offline-verifiable cryptographic credentials."
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "Primust, Inc.", email = "eng@primust.com" }]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security :: Cryptography",
+]
+dependencies = [
+  "httpx>=0.27.0",
+  "pydantic>=2.0",
+  "cryptography>=41.0",
+  "primust-artifact-core>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+]
+
+[project.scripts]
+primust = "primust.cli:main"
+
+[project.urls]
+Homepage = "https://primust.com"
+Documentation = "https://docs.primust.com"
+Verify = "https://verify.primust.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/primust"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

primust-1.0.0/src/primust/__init__.py

@@ -0,0 +1,74 @@
+"""
+Primust SDK
+===========
+Verifiable Process Execution Credentials for regulated workflows.
+
+Quickstart:
+    import primust
+
+    p = primust.Pipeline(api_key="pk_live_...", workflow_id="my-workflow")
+
+    run = p.open()
+    result = run.record(
+        check="aml_screen",
+        manifest_id="sha256:abc123...",
+        input=entity_data,       # committed locally — never sent to Primust
+        check_result="pass",
+    )
+    # Write result.commitment_hash to your own logs (log linkage anchor)
+    vpec = run.close()
+
+Privacy guarantee:
+    Raw input values are committed locally via Poseidon2 (or SHA-256 when
+    the native extension is unavailable). Only commitment hashes and bounded
+    normalized metadata transit to api.primust.com. Your data never leaves
+    your environment.
+
+Docs: https://docs.primust.com
+Verify: https://verify.primust.com
+"""
+
+from primust.pipeline import (
+    Pipeline,
+    CheckSession,
+    ReviewSession,
+    ResumedContext,
+    ZK_IS_BLOCKING,
+)
+from primust.models import (
+    CheckResult,
+    GovernanceGap,
+    LoggerOptions,
+    ManifestRegistration,
+    PrimustLogEvent,
+    ProofLevel,
+    ProofLevelBreakdown,
+    RecordResult,
+    VPEC,
+    VisibilityMode,
+)
+from primust.models import (
+    CheckSession as ModelCheckSession,
+    ReviewSession as ModelReviewSession,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "Pipeline",
+    "CheckResult",
+    "CheckSession",
+    "GovernanceGap",
+    "LoggerOptions",
+    "ManifestRegistration",
+    "ModelCheckSession",
+    "ModelReviewSession",
+    "PrimustLogEvent",
+    "ProofLevel",
+    "ProofLevelBreakdown",
+    "RecordResult",
+    "ResumedContext",
+    "ReviewSession",
+    "VPEC",
+    "VisibilityMode",
+    "ZK_IS_BLOCKING",
+]

primust-1.0.0/src/primust/adapters/__init__.py

@@ -0,0 +1 @@
+"""Primust framework adapters."""

primust-1.0.0/src/primust/adapters/crewai.py

@@ -0,0 +1,147 @@
+"""
+Primust CrewAI adapter — step_callback observer.
+
+Privacy invariant: raw agent output NEVER leaves the customer environment.
+Only commitment hashes (poseidon2) transit to the Primust API.
+
+Usage:
+    from primust.adapters.crewai import PrimustCrewAICallback
+
+    callback = PrimustCrewAICallback(
+        pipeline=p,
+        manifest_map={
+            "Research Analyst": "manifest_research_v1",
+            "Content Writer":  "manifest_output_policy_v2",
+        }
+    )
+
+    crew = Crew(
+        agents=[research_analyst, content_writer],
+        tasks=[research_task, write_task],
+        step_callback=callback.on_step
+    )
+    result = crew.kickoff()
+    vpec = p.close()
+
+Surface declaration:
+  surface_type: in_process_adapter
+  surface_name: crewai_step_callback
+  observation_mode: post_action_realtime
+  scope_type: full_workflow
+  proof_ceiling: execution
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from primust import Pipeline
+
+logger = logging.getLogger("primust.crewai")
+
+SURFACE_DECLARATION = {
+    "surface_type": "in_process_adapter",
+    "surface_name": "crewai_step_callback",
+    "observation_mode": "post_action_realtime",
+    "scope_type": "full_workflow",
+    "proof_ceiling": "execution",
+    "surface_coverage_statement": (
+        "All CrewAI agent steps observed via step_callback. "
+        "Actions taken by agents outside the CrewAI step lifecycle are not observed."
+    ),
+}
+
+
+class PrimustCrewAICallback:
+    """
+    CrewAI step_callback observer. Attaches as crew.step_callback.
+
+    Callback NEVER raises into CrewAI — all exceptions caught, logged, continue.
+    Raw agent output committed locally — only commitment_hash transits.
+    CrewAI step_callback has no return value — Primust is purely observational.
+    """
+
+    def __init__(
+        self,
+        pipeline: Pipeline,
+        manifest_map: dict[str, str] | None = None,
+    ) -> None:
+        self.pipeline = pipeline
+        self.manifest_map = manifest_map or {}
+
+    def on_step(self, agent_output: Any) -> None:
+        """
+        CrewAI step_callback handler.
+
+        agent_output can be:
+          - AgentAction: tool call in progress
+          - AgentFinish: agent output ready
+          - dict or other: fallback handling
+        """
+        try:
+            self._handle_step(agent_output)
+        except Exception:
+            # CRITICAL: never raise into CrewAI
+            logger.exception("Primust callback error (swallowed)")
+
+    def _handle_step(self, agent_output: Any) -> None:
+        output_type = type(agent_output).__name__
+
+        # Extract agent role for manifest lookup
+        agent_role = getattr(agent_output, "agent", None)
+        if agent_role and hasattr(agent_role, "role"):
+            agent_role = agent_role.role
+        elif isinstance(agent_output, dict):
+            agent_role = agent_output.get("agent_role", "unknown")
+        else:
+            agent_role = getattr(agent_output, "role", "unknown")
+
+        manifest_id = self.manifest_map.get(str(agent_role), f"auto:{agent_role}")
+
+        # Determine if this is an action (tool call) or finish (output)
+        is_action = output_type == "AgentAction" or (
+            isinstance(agent_output, dict) and agent_output.get("type") == "action"
+        )
+        is_finish = output_type == "AgentFinish" or (
+            isinstance(agent_output, dict) and agent_output.get("type") == "finish"
+        )
+
+        # Extract input and output
+        if isinstance(agent_output, dict):
+            input_data = agent_output.get("input", agent_output.get("tool_input", str(agent_output)))
+            output_data = agent_output.get("output", agent_output.get("result"))
+        else:
+            input_data = getattr(agent_output, "tool_input", getattr(agent_output, "text", str(agent_output)))
+            output_data = getattr(agent_output, "output", getattr(agent_output, "return_values", None))
+
+        check_name = f"crewai_{output_type.lower()}"
+        if is_action:
+            tool = getattr(agent_output, "tool", None) or (
+                agent_output.get("tool") if isinstance(agent_output, dict) else None
+            )
+            if tool:
+                check_name = f"crewai_action:{tool}"
+
+        # Check if agent role is mapped
+        unverified = str(agent_role) not in self.manifest_map
+
+        session = self.pipeline.open_check(check_name, manifest_id)
+
+        record_kwargs: dict[str, Any] = {}
+        if output_data is not None:
+            record_kwargs["output"] = output_data
+
+        check_result = "pass"
+        if unverified:
+            check_result = "pass"  # still pass, but marked unverified via metadata
+
+        self.pipeline.record(
+            session,
+            input=input_data,
+            check_result=check_result,
+            **record_kwargs,
+        )
+
+    def get_surface_declaration(self) -> dict[str, str]:
+        return dict(SURFACE_DECLARATION)