PermutiveAPI
PermutiveAPI is a typed, governed Python SDK and AI-agent platform for the Permutive API. It supports Python 3.9 through 3.13 and provides synchronous and asynchronous clients, typed queries, a safe Codex plugin, deterministic evaluations and scenarios, executable recipes, capability negotiation, generated API contracts, sanitized replay, coordinated runtime resilience, and immutable release evidence.
Install
python -m pip install --upgrade PermutiveAPI
Optional integrations:
python -m pip install --upgrade "PermutiveAPI[async]"
python -m pip install --upgrade "PermutiveAPI[dataframe]"
The core package does not require HTTPX or pandas.
Configure safely
permutiveapi configure
permutiveapi doctor
permutiveapi validate
permutiveapi eval
configure writes only PERMUTIVE_API_KEY to a local .env file without echoing it. doctor verifies the variable, permissions, and Git ignore policy. validate and eval are credential-free and network-free.
Credential lookup order is explicit input, process environment, project .env, then ~/.config/permutive/.env. Credentials are never uploaded, logged, or included in object representations.
Canonical client
from PermutiveAPI import PermutiveClient
with PermutiveClient("api-key") as client:
cohort = client.cohorts.get("cohort-id")
page = client.segments.list(page_size=50)
Canonical resource namespaces are cohorts, imports, segments, sources, and workspaces. Their 25 CRUD/list operations and structural response fingerprints are generated in API_COVERAGE.md.
Async client
Install PermutiveAPI[async]:
import asyncio
from PermutiveAPI import AsyncPermutiveClient
async def main() -> None:
async with AsyncPermutiveClient("api-key") as client:
result = await client.request("GET", "cohorts-api/v2/cohorts")
print(result)
asyncio.run(main())
The async client shares typed JSON, errors, retries, pagination, and bounded-batch semantics with the synchronous SDK.
Typed queries
from PermutiveAPI import all_of, event, in_segment
query = all_of((event("pageview"), in_segment("high-intent")))
payload = query.to_json()
Governed agent platform
The Codex plugin and Python integration reuse the canonical SDK:
from PermutiveAPI.plugins.codex import CodexPlugin
plugin = CodexPlugin.from_env()
tools = plugin.tools().as_openai_tools()
agent_kit = plugin.agent_kit()
Read-only is the default. Write tools require explicit read-write mode and confirmation. Adaptive integrations negotiate capabilities before execution. CodexPlugin.invoke_safe() returns stable secret-safe error codes, retryability, recommended actions, and safe context.
Run deterministic platform proof:
permutiveapi eval
permutiveapi examples
permutiveapi examples --name reviewed-cohort-write
The scorecard covers tool selection, unsupported capabilities, approvals, allow and deny policy, redaction, idempotency, workflow bounds, partial failures, and audit completeness. Seven credential-free recipes cover SDK, async, queries, plugin, and governed workflows. A fresh installed interpreter must complete the canonical recipe within five seconds.
Operational reliability
API drift and replay
python scripts/generate_api_contracts.py --check
python scripts/validate_recordings.py
Versioned samples generate the machine contract and API_COVERAGE.md. Additive fields remain compatible; removals and type changes fail validation. Recordings exclude request payloads, query strings, credentials, authorization headers, cookies, and sensitive response values.
Coordinated limits and rotation
import requests
from PermutiveAPI import (
AtomicCredentials,
CoordinatedTransport,
PermutiveClient,
RateLimitCoordinator,
)
credentials = AtomicCredentials("initial-key")
coordinator = RateLimitCoordinator(requests_per_second=10)
transport = CoordinatedTransport(requests.Session(), credentials, coordinator)
client = PermutiveClient("managed-placeholder", transport=transport)
client.request("GET", "cohorts-api/v2/cohorts")
credentials.rotate("rotated-key")
One coordinator can be shared by synchronous and asynchronous transports. Every request attempt receives one immutable credential generation, Retry-After deferrals apply across all callers, and transport exceptions redact the real rotating key before reaching the client.
Performance and releases
python scripts/validate_performance.py
Performance budgets detect material local regressions. The release workflow builds once, generates an SBOM and SHA-256 manifest, attests the artifacts, and verifies the exact candidate before PyPI Trusted Publishing and GitHub Release creation.
See docs/OPERATIONAL_RELIABILITY.md for the complete contract.
CLI
| Command | Purpose |
|---|---|
permutiveapi configure |
Create a protected local credential file. |
permutiveapi doctor |
Check credential safety without showing values. |
permutiveapi validate |
Validate the installed product surface. |
permutiveapi test |
Run deterministic installed-package checks. |
permutiveapi eval |
Print governed-platform scorecard JSON. |
permutiveapi docs |
Print canonical documentation paths. |
permutiveapi examples |
Discover or print executable recipes. |
permutiveapi upgrade |
Print the explicit upgrade command. |
permutiveapi uninstall |
Print the explicit removal command. |
Development
git clone https://github.com/fatmambot33/PermutiveAPI.git
cd PermutiveAPI
python -m pip install -e ".[dev]"
python scripts/validate_release_metadata.py
python scripts/validate_typing_scope.py
python scripts/generate_api_contracts.py --check
python scripts/validate_recordings.py
python scripts/validate_performance.py
python scripts/generate_evaluation_scorecard.py --check evals/scorecard.json
black --check --diff src tests typing_examples scripts
pydocstyle src/PermutiveAPI
pyright
pytest -q
python -m build
python -m twine check dist/*
Supported changes require NumPy-style docstrings, strict typing, deterministic network-free tests, secret redaction, clean installation, and machine-readable evidence.
Project contracts
- PRODUCT.md — mission and decision rules.
- PUBLIC_API.md — canonical and compatibility surfaces.
- API_COVERAGE.md — generated endpoint coverage.
- MIGRATION.md — supported migration paths.
- docs/AI_NATIVE.md — governed platform architecture.
- docs/EVALUATIONS.md — deterministic evidence.
- docs/OPERATIONAL_RELIABILITY.md — drift, replay, resilience, budgets, and releases.
- ROADMAP.md — completed roadmap and non-goals.
- SECURITY.md — reporting and guarantees.
- RELEASING.md — immutable publication process.
- CHANGELOG.md — released behavior.
Compatibility
PUBLIC_API.md is the source of truth. Legacy resource classes remain supported as compatibility APIs, but new code should prefer PermutiveClient, AsyncPermutiveClient, typed queries, and canonical tool surfaces. Review MIGRATION.md before replacing older call patterns.
License
MIT. See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for PermutiveAPI 6.8.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| permutiveapi-6.8.2.tar.gz | 172.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| permutiveapi-6.8.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 293.1 kB
Release files / permutiveapi-6.8.2.tar.gz
| Download URL | permutiveapi-6.8.2.tar.gz |
|---|---|
| Size | 172.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9691eec661287142afa84526f66540a7a63068588f03689c78bc0d6fa177ab4c
|
|
BLAKE2b-256 checksum How to use checksums |
13e336f0b95d95d8488acd1edf9b537e04fd9c4cd9b1175fd1aeb2aaaa2b626a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency logRelease files / permutiveapi-6.8.2-py3-none-any.whl
| Download URL | permutiveapi-6.8.2-py3-none-any.whl |
|---|---|
| Size | 120.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f16338258364e2aaf745192591c128d9412fc1f1a1274e06d8fdb57538c22e9f
|
|
BLAKE2b-256 checksum How to use checksums |
19d1dfb8ad6852ea5046873165a70a702c42d42ea3209fa0352cfea9f99d3277
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 26, 2026.
Transparency log
