invoance 0.1.0__tar.gz

invoance-0.1.0/.env.example

@@ -0,0 +1,4 @@
+# Copy to .env and fill in your real values. Never commit .env.
+# Get an API key from https://app.invoance.com/dashboard/api-keys
+
+INVOANCE_API_KEY=invoance_live_REPLACE_WITH_YOUR_KEY

invoance-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+# Run pytest + smoke build on every push and PR.
+# Matrixed across the Python versions we support.
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: python -m pip install --upgrade pip build
+      - run: pip install -e ".[dev]"
+      - run: pytest -v
+      - name: Build sdist + wheel (smoke)
+        run: python -m build --sdist --wheel

invoance-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,101 @@
+# Auto-publish to PyPI via Trusted Publishing when a tag matching `v*`
+# is pushed. No API token required — OIDC handshake against the PyPI
+# Trusted Publisher you configure once.
+#
+# To release:
+#   1. Bump version in pyproject.toml AND invoance/_version.py
+#   2. Update CHANGELOG.md
+#   3. Commit, push to main
+#   4. Tag and push:
+#        git tag v0.1.1 -m "0.1.1"
+#        git push origin v0.1.1
+#   5. This workflow runs, publishes to PyPI, creates a GitHub Release.
+#
+# One-time PyPI Trusted Publisher setup:
+#   1. Go to https://pypi.org/manage/account/publishing/
+#   2. Add a new pending publisher:
+#        PyPI Project Name:  invoance
+#        Owner:              Invoance
+#        Repository name:    invoance-python
+#        Workflow name:      release.yml
+#        Environment name:   pypi
+#   3. Create the GitHub environment named `pypi` in the repo's
+#      Settings → Environments.
+#   4. After the first successful publish, the project is live and
+#      future tags publish automatically.
+
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write       # to create the GitHub Release
+  id-token: write       # required for PyPI Trusted Publishing OIDC
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches pyproject.toml version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$PKG" ]; then
+            echo "ERROR: tag $GITHUB_REF_NAME does not match pyproject.toml version $PKG" >&2
+            exit 1
+          fi
+          echo "Tag $GITHUB_REF_NAME matches pyproject.toml version $PKG"
+
+      - run: python -m pip install --upgrade pip build
+      - run: pip install -e ".[dev]"
+      - run: pytest -v
+      - run: python -m build --sdist --wheel
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI (Trusted Publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/invoance
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ github.ref_name }}
+          generate_release_notes: true
+          body: |
+            See [CHANGELOG](CHANGELOG.md) for details.
+
+            ```bash
+            pip install invoance==${{ github.ref_name }}
+            ```

invoance-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Bytecode / cache
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Distribution
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual env
+.venv/
+venv/
+
+# Environment
+.env
+.env.local
+.env.*.local
+# Keep .env.example committed — it's the template
+
+# IDE / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Coverage
+.coverage
+htmlcov/

invoance-0.1.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to the Invoance Python SDK are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+While the SDK is pre-1.0, breaking changes are only introduced in MINOR releases
+(0.x → 0.x+1) and always documented here. Once 1.0.0 ships, the standard SemVer
+contract applies.
+
+---
+
+## [Unreleased]
+
+_Nothing yet._
+
+---
+
+## [0.1.0] — 2026-04-26
+
+Initial public release.
+
+### Added
+
+- **Events** — `client.events.ingest()`, `get()`, `list()`, `verify()` for
+  signing-and-anchoring arbitrary compliance events with hex-SHA-256 payload
+  hashes.
+- **Documents** — `client.documents.anchor()` (hash-only) and `anchor_file()`
+  (hashes + uploads in one call), plus `get()`, `list()`, `verify()`, and
+  `get_document_original()` for retrieving stored payloads.
+- **AI attestations** — `client.attestations.ingest()`, `get()`, `list()`,
+  `verify()`, `verify_signature()` for cryptographically attesting model
+  inputs/outputs/decisions.
+- **Traces** — full lifecycle: `create()`, `add_event()`, `seal()`,
+  `get_proof()`, `export_proof_pdf()` for grouping items into sealed bundles
+  with composite hashes.
+- **`client.validate()`** — fast credential probe that never raises; returns
+  `ValidationResult(valid, reason, base_url)`. Use in health checks and CI
+  guards.
+- **Typed error hierarchy** — `InvoanceError` base with `AuthenticationError`,
+  `ForbiddenError`, `NotFoundError`, `ValidationError`, `ConflictError`,
+  `QuotaExceededError`, `ServerError`, `NetworkError`, `TimeoutError`. Every
+  raised exception inherits from `InvoanceError` so consumers can catch the
+  base type.
+- **Client-side validation** — `document_hash`, `payload_hash`, `content_hash`
+  must be valid 64-char hex SHA-256 before a request leaves the client.
+- **Env-var configuration** — `INVOANCE_API_KEY` (required) and
+  `INVOANCE_BASE_URL` (default: `https://api.invoance.com`) auto-loaded by
+  `InvoanceClient()`. Explicit constructor args or a `ClientConfig` override.
+- **`ClientConfig.load(...)` factory** — explicit env-var resolution for
+  callers that want to construct a `ClientConfig` programmatically with
+  fallback to environment variables.
+- **Async-first** — built on `httpx.AsyncClient`, used as
+  `async with InvoanceClient() as client: ...`.
+- **PEP 561 typed package** — `py.typed` marker shipped so `mypy` and
+  `pyright` pick up the bundled type hints with no extra stub install.
+- **Examples** — full working scripts under `examples/` for events,
+  documents, attestations, and the full trace workflow.
+
+### Notes
+
+- Requires Python 3.9+.
+- Runtime deps: `httpx>=0.27,<1`, `pydantic>=2.0,<3`, `PyNaCl>=1.5,<2`.
+
+[Unreleased]: https://github.com/Invoance/invoance-python/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Invoance/invoance-python/releases/tag/v0.1.0

invoance-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Invoance, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

invoance-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: invoance
+Version: 0.1.0
+Summary: Official Python SDK for the Invoance compliance API
+Project-URL: Homepage, https://invoance.com
+Project-URL: Documentation, https://invoance.com/docs
+Project-URL: Repository, https://github.com/Invoance/invoance-python
+Project-URL: Issues, https://github.com/Invoance/invoance-python/issues
+Project-URL: Changelog, https://github.com/Invoance/invoance-python/blob/main/CHANGELOG.md
+Author-email: "Invoance, Inc." <sdk@invoance.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: attestation,audit,audit-trail,compliance,cryptographic-proof,ed25519,hipaa,invoance,soc2,tamper-evident
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: pynacl<2,>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: python-dotenv>=1.0; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# Invoance Python SDK
+
+Official Python SDK for the [Invoance](https://invoance.com) compliance API — cryptographic proof, document anchoring, and AI attestation.
+
+## Install
+
+```bash
+pip install invoance
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+Set your API key:
+
+```bash
+export INVOANCE_API_KEY=invoance_live_...
+```
+
+```python
+import asyncio
+import hashlib
+from invoance import InvoanceClient
+
+async def main():
+    async with InvoanceClient() as client:
+
+        # Ingest a compliance event
+        event = await client.events.ingest(
+            event_type="policy.approval",
+            payload={"policy_id": "pol_001", "decision": "approved"},
+        )
+        print(event.event_id)
+
+        # Anchor a document by hash
+        doc_bytes = b"...your document bytes..."
+        doc = await client.documents.anchor(
+            document_hash=hashlib.sha256(doc_bytes).hexdigest(),
+            document_ref="Invoice #1042",
+        )
+        print(doc.event_id)
+
+        # Or use the file helper (hashes + uploads in one call)
+        doc = await client.documents.anchor_file(
+            file="./invoice.pdf",
+            document_ref="Invoice #1042",
+        )
+
+        # Ingest an AI attestation
+        att = await client.attestations.ingest(
+            attestation_type="output",
+            input="Summarize this contract",
+            output="The contract states...",
+            model_provider="openai",
+            model_name="gpt-4o",
+            model_version="2025-01-01",
+            subject={"user_id": "u_42", "session_id": "sess_4f9a"},
+        )
+        print(att.attestation_id)
+
+asyncio.run(main())
+```
+
+## Quick validation
+
+Sanity-check that your API key works before wiring the SDK into a larger app:
+
+```python
+async with InvoanceClient() as client:
+    result = await client.validate()
+    if not result.valid:
+        raise RuntimeError(f"Invoance: {result.reason} (base: {result.base_url})")
+```
+
+`validate()` probes `GET /v1/events?limit=1`, never raises, and returns a `ValidationResult(valid, reason, base_url)` — use it in health checks, startup scripts, or CI guards.
+
+One-liner for a terminal sanity check, no SDK install required:
+
+```bash
+curl -sS -o /dev/null -w "%{http_code}\n" \
+  -H "Authorization: Bearer $INVOANCE_API_KEY" \
+  "${INVOANCE_BASE_URL:-https://api.invoance.com}/v1/events?limit=1"
+# 200 = key valid · 401 = bad key · anything else = investigate
+```
+
+## Configuration
+
+The client reads from environment variables automatically:
+
+| Variable | Required | Default |
+|---|---|---|
+| `INVOANCE_API_KEY` | Yes | — |
+| `INVOANCE_BASE_URL` | No | `https://api.invoance.com` |
+
+You can also pass them explicitly:
+
+```python
+client = InvoanceClient(
+    api_key="invoance_live_...",
+    timeout=60.0,
+)
+```
+
+`api_key`, `base_url`, and `timeout` are mutually exclusive with the `config=` argument — pass either individual overrides or a full `ClientConfig`, not both.
+
+For env-var fallback when constructing a config manually, use the factory:
+
+```python
+from invoance import ClientConfig
+
+config = ClientConfig.load(timeout=60.0)  # reads INVOANCE_API_KEY / INVOANCE_BASE_URL from env
+client = InvoanceClient(config=config)
+```
+
+## Error handling
+
+Every error the SDK raises — API responses, network failures, client-side validation — inherits from `InvoanceError`:
+
+```python
+from invoance import (
+    InvoanceClient,
+    InvoanceError,
+    AuthenticationError,
+    QuotaExceededError,
+    ValidationError,
+    TimeoutError,
+    NetworkError,
+)
+
+try:
+    await client.events.ingest(event_type="user.login", payload={...})
+except AuthenticationError:
+    ...  # 401 — bad API key
+except QuotaExceededError as e:
+    print(f"rate limited, retry in {e.retry_after_seconds}s")
+except ValidationError:
+    ...  # 400 from server, or client-side input validation failure
+except TimeoutError:
+    ...  # request exceeded configured timeout
+except NetworkError:
+    ...  # DNS/connection/TLS failure before a response
+except InvoanceError:
+    ...  # any other API or transport failure
+```
+
+Common hex-SHA-256 fields (`document_hash`, `payload_hash`, `content_hash`) are validated client-side — passing a malformed hash raises `ValidationError` before a request is sent.
+
+## Examples
+
+```bash
+pip install invoance[examples]
+python examples/quickstart.py
+```
+
+See the `examples/` directory for complete working examples covering events, documents, AI attestations, and traces.
+
+## License
+
+MIT

invoance-0.1.0/README.md

@@ -0,0 +1,160 @@
+# Invoance Python SDK
+
+Official Python SDK for the [Invoance](https://invoance.com) compliance API — cryptographic proof, document anchoring, and AI attestation.
+
+## Install
+
+```bash
+pip install invoance
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+Set your API key:
+
+```bash
+export INVOANCE_API_KEY=invoance_live_...
+```
+
+```python
+import asyncio
+import hashlib
+from invoance import InvoanceClient
+
+async def main():
+    async with InvoanceClient() as client:
+
+        # Ingest a compliance event
+        event = await client.events.ingest(
+            event_type="policy.approval",
+            payload={"policy_id": "pol_001", "decision": "approved"},
+        )
+        print(event.event_id)
+
+        # Anchor a document by hash
+        doc_bytes = b"...your document bytes..."
+        doc = await client.documents.anchor(
+            document_hash=hashlib.sha256(doc_bytes).hexdigest(),
+            document_ref="Invoice #1042",
+        )
+        print(doc.event_id)
+
+        # Or use the file helper (hashes + uploads in one call)
+        doc = await client.documents.anchor_file(
+            file="./invoice.pdf",
+            document_ref="Invoice #1042",
+        )
+
+        # Ingest an AI attestation
+        att = await client.attestations.ingest(
+            attestation_type="output",
+            input="Summarize this contract",
+            output="The contract states...",
+            model_provider="openai",
+            model_name="gpt-4o",
+            model_version="2025-01-01",
+            subject={"user_id": "u_42", "session_id": "sess_4f9a"},
+        )
+        print(att.attestation_id)
+
+asyncio.run(main())
+```
+
+## Quick validation
+
+Sanity-check that your API key works before wiring the SDK into a larger app:
+
+```python
+async with InvoanceClient() as client:
+    result = await client.validate()
+    if not result.valid:
+        raise RuntimeError(f"Invoance: {result.reason} (base: {result.base_url})")
+```
+
+`validate()` probes `GET /v1/events?limit=1`, never raises, and returns a `ValidationResult(valid, reason, base_url)` — use it in health checks, startup scripts, or CI guards.
+
+One-liner for a terminal sanity check, no SDK install required:
+
+```bash
+curl -sS -o /dev/null -w "%{http_code}\n" \
+  -H "Authorization: Bearer $INVOANCE_API_KEY" \
+  "${INVOANCE_BASE_URL:-https://api.invoance.com}/v1/events?limit=1"
+# 200 = key valid · 401 = bad key · anything else = investigate
+```
+
+## Configuration
+
+The client reads from environment variables automatically:
+
+| Variable | Required | Default |
+|---|---|---|
+| `INVOANCE_API_KEY` | Yes | — |
+| `INVOANCE_BASE_URL` | No | `https://api.invoance.com` |
+
+You can also pass them explicitly:
+
+```python
+client = InvoanceClient(
+    api_key="invoance_live_...",
+    timeout=60.0,
+)
+```
+
+`api_key`, `base_url`, and `timeout` are mutually exclusive with the `config=` argument — pass either individual overrides or a full `ClientConfig`, not both.
+
+For env-var fallback when constructing a config manually, use the factory:
+
+```python
+from invoance import ClientConfig
+
+config = ClientConfig.load(timeout=60.0)  # reads INVOANCE_API_KEY / INVOANCE_BASE_URL from env
+client = InvoanceClient(config=config)
+```
+
+## Error handling
+
+Every error the SDK raises — API responses, network failures, client-side validation — inherits from `InvoanceError`:
+
+```python
+from invoance import (
+    InvoanceClient,
+    InvoanceError,
+    AuthenticationError,
+    QuotaExceededError,
+    ValidationError,
+    TimeoutError,
+    NetworkError,
+)
+
+try:
+    await client.events.ingest(event_type="user.login", payload={...})
+except AuthenticationError:
+    ...  # 401 — bad API key
+except QuotaExceededError as e:
+    print(f"rate limited, retry in {e.retry_after_seconds}s")
+except ValidationError:
+    ...  # 400 from server, or client-side input validation failure
+except TimeoutError:
+    ...  # request exceeded configured timeout
+except NetworkError:
+    ...  # DNS/connection/TLS failure before a response
+except InvoanceError:
+    ...  # any other API or transport failure
+```
+
+Common hex-SHA-256 fields (`document_hash`, `payload_hash`, `content_hash`) are validated client-side — passing a malformed hash raises `ValidationError` before a request is sent.
+
+## Examples
+
+```bash
+pip install invoance[examples]
+python examples/quickstart.py
+```
+
+See the `examples/` directory for complete working examples covering events, documents, AI attestations, and traces.
+
+## License
+
+MIT

invoance-0.1.0/examples/ai_attestations/get_attestation.py

@@ -0,0 +1,56 @@
+"""Fetch a single AI attestation by ID and print it.
+
+Usage
+-----
+    python examples/ai_attestations/get_attestation.py <attestation_id>
+"""
+
+import asyncio
+import sys
+
+from dotenv import load_dotenv
+from invoance import InvoanceClient
+from invoance.errors import InvoanceError
+
+load_dotenv()
+
+
+async def main():
+    if len(sys.argv) < 2:
+        print("Usage: python get_attestation.py <attestation_id>")
+        sys.exit(1)
+
+    attestation_id = sys.argv[1]
+
+    async with InvoanceClient() as client:
+        att = await client.attestations.get(attestation_id)
+        print(f"attestation_id:   {att.attestation_id}")
+        print(f"tenant_id:        {att.tenant_id}")
+        print(f"type:             {att.attestation_type}")
+        print(f"attestation_hash: {att.attestation_hash}")
+        print(f"input_hash:       {att.input_hash}")
+        print(f"output_hash:      {att.output_hash}")
+        print(f"signature:        {att.signature[:40]}...")
+        print(f"public_key:       {att.public_key[:40]}...")
+        print(f"signature_alg:    {att.signature_alg}")
+        print(f"model_provider:   {att.model_provider}")
+        print(f"model_name:       {att.model_name}")
+        print(f"model_version:    {att.model_version}")
+        print(f"retention_policy: {att.retention_policy}")
+        print(f"created_at:       {att.created_at}")
+
+        if att.organization:
+            org = att.organization
+            print(f"\n── Issuer ──")
+            print(f"  name:            {org.name}")
+            print(f"  issuer_name:     {org.issuer_name}")
+            print(f"  domain:          {org.primary_domain}")
+            print(f"  domain_verified: {org.domain_verified}")
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except InvoanceError as e:
+        print(f"\n✗ {type(e).__name__}: {e}")
+        sys.exit(1)