From b2ba923526ff2ed01b21d71414fde935c42e2d84 Mon Sep 17 00:00:00 2001 From: rimkusaurimas Date: Thu, 16 Jul 2026 19:21:40 +0200 Subject: [PATCH 1/8] chore: improve PyPI/GitHub discoverability (keywords, classifiers, badges, py.typed) --- README.md | 11 +++++------ pyproject.toml | 21 ++++++++++++++++----- src/sourcerykit/py.typed | 0 3 files changed, 21 insertions(+), 11 deletions(-) create mode 100644 src/sourcerykit/py.typed diff --git a/README.md b/README.md index cf9c247..6acfc44 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,11 @@
- [![PyPI Version](https://img.shields.io/pypi/v/sourcerykit.svg?color=blue)](https://pypi.org/project/sourcerykit/) - [![status: v1.0.1](https://img.shields.io/badge/status-v1.0.1-blue)](https://github.com/ProvablyAI/sourcerykit/blob/main/CHANGELOG.md) - [![python: 3.12+](https://img.shields.io/badge/python-3.12+-slate)](https://github.com/ProvablyAI/sourcerykit/blob/main/pyproject.toml) - [![license: BSL 1.1](https://img.shields.io/badge/license-BSL%201.1-crimson)](https://github.com/ProvablyAI/sourcerykit/blob/main/LICENSE.md) - [![CI Build](https://github.com/ProvablyAI/sourcerykit/actions/workflows/ci.yml/badge.svg)](https://github.com/ProvablyAI/sourcerykit/actions) - [![Coverage](https://img.shields.io/badge/coverage-60%25-success)](https://github.com/ProvablyAI/sourcerykit) + [![CI](https://github.com/ProvablyAI/sourcerykit/actions/workflows/ci.yml/badge.svg)](https://github.com/ProvablyAI/sourcerykit/actions/workflows/ci.yml) + [![PyPI version](https://img.shields.io/pypi/v/sourcerykit)](https://pypi.org/project/sourcerykit/) + [![Python versions](https://img.shields.io/pypi/pyversions/sourcerykit)](https://pypi.org/project/sourcerykit/) + [![License](https://img.shields.io/pypi/l/sourcerykit)](https://github.com/ProvablyAI/sourcerykit/blob/main/LICENSE.md) + [![Types: Mypy](https://img.shields.io/badge/types-mypy-blue)](https://mypy-lang.org/) diff --git a/pyproject.toml b/pyproject.toml index 6487035..e395ee4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -15,14 +15,30 @@ keywords = [ "provably", "verifiable", "agent", + "ai-agents", + "llm", + "guardrails", + "llm-security", + "observability", + "hallucination", "handoff", "interceptor", ] classifiers = [ + "Development Status :: 5 - Production/Stable", + "Intended Audience :: Developers", + "Intended Audience :: Information Technology", + "Topic :: Security", + "Topic :: Internet :: WWW/HTTP", + "Topic :: System :: Monitoring", + "Topic :: Software Development :: Libraries :: Python Modules", "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: Implementation :: CPython", "Operating System :: OS Independent", + "Typing :: Typed", ] dependencies = [ "alembic>=1.13", @@ -159,11 +175,6 @@ filename = "pyproject.toml" search = 'version = "{current_version}"' replace = 'version = "{new_version}"' -[[tool.bumpversion.files]] -filename = "README.md" -search = "v{current_version}" -replace = "v{new_version}" - [[tool.bumpversion.files]] filename = "CHANGELOG.md" search = "## Unreleased" diff --git a/src/sourcerykit/py.typed b/src/sourcerykit/py.typed new file mode 100644 index 0000000..e69de29 From 73d40c242c18fa2f5b480390270a84a30b2a2bdb Mon Sep 17 00:00:00 2001 From: rimkusaurimas Date: Thu, 16 Jul 2026 20:50:45 +0200 Subject: [PATCH 2/8] docs: move quickstart above the fold (pip install + snippet before How It Works) --- README.md | 42 ++++++++++++++++++++++++++---------------- 1 file changed, 26 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 6acfc44..811c44d 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,32 @@ SourceryKit is the Python SDK for [Provably](https://provably.ai). It provides v > ⚠️ **IMPORTANT:** Upgrading the SDK from v0.2 to v1.0? See the [v1.0 migration guide](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/migrations/v1_0/v1_0.md). +## Quickstart + +Requires **Python 3.12+**. + +```bash +pip install sourcerykit +sourcerykit init # one-time setup: account, database, credentials +``` + +Give your agent `SourceryKitAgentResponse` as its output type, then verify its claims against the recorded calls before you trust them: + +```python +import sourcerykit +from sourcerykit import SourceryKitAgentResponse # your agent's output_type + +await sourcerykit.bootstrap_system() +await sourcerykit.insert_trusted_endpoint(url="https://api.example.com/data") + +# ... run your agent inside an intercept context, then build the payload ... +result = await sourcerykit.evaluate_handoff(payload=payload) +print(result["outcome"]) # PASS | CAUGHT | ERROR +``` + +See the [full runnable example](#quick-example) below. + + ## How Does It Work? SourceryKit handles policy enforcement and logging right inside your agent's normal workflow: @@ -35,22 +61,6 @@ SourceryKit handles policy enforcement and logging right inside your agent's nor - **Provably Backend**: The source of truth that turns your local intercepts into anchored verification proofs. -## Installation - -SourceryKit requires **Python 3.12+**. You can grab it directly from source: - -```bash -git clone git@github.com:ProvablyAI/sourcerykit.git -pip install -e ./sourcerykit -``` - -Or install it directly via pip: - -```bash -pip install sourcerykit -``` - - ## Configuration To get things running, SourceryKit must be configured with your project variables. The interactive CLI handles account provisioning, organization workspace initialization, database validation, and persists credentials globally (OS application folder) and locally (project `.env`). From f040afb7695763d3240108701ea5de19f1d57ffd Mon Sep 17 00:00:00 2001 From: rimkusaurimas Date: Fri, 17 Jul 2026 09:48:57 +0200 Subject: [PATCH 3/8] =?UTF-8?q?docs:=20address=20review=20=E2=80=94=20badg?= =?UTF-8?q?es=20(CI=20last,=20short=20license,=20drop=20types),=20single?= =?UTF-8?q?=20example=20in=20quickstart,=20restore=20source=20install;=20d?= =?UTF-8?q?rop=20redundant=20classifier?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 129 ++++++++++++++++++++++--------------------------- pyproject.toml | 1 - 2 files changed, 59 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index 811c44d..cfe678e 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,10 @@
- [![CI](https://github.com/ProvablyAI/sourcerykit/actions/workflows/ci.yml/badge.svg)](https://github.com/ProvablyAI/sourcerykit/actions/workflows/ci.yml) [![PyPI version](https://img.shields.io/pypi/v/sourcerykit)](https://pypi.org/project/sourcerykit/) [![Python versions](https://img.shields.io/pypi/pyversions/sourcerykit)](https://pypi.org/project/sourcerykit/) - [![License](https://img.shields.io/pypi/l/sourcerykit)](https://github.com/ProvablyAI/sourcerykit/blob/main/LICENSE.md) - [![Types: Mypy](https://img.shields.io/badge/types-mypy-blue)](https://mypy-lang.org/) + [![License: BSL 1.1](https://img.shields.io/badge/license-BSL%201.1-blue)](https://github.com/ProvablyAI/sourcerykit/blob/main/LICENSE.md) + [![CI](https://github.com/ProvablyAI/sourcerykit/actions/workflows/ci.yml/badge.svg)](https://github.com/ProvablyAI/sourcerykit/actions/workflows/ci.yml) @@ -25,77 +24,14 @@ pip install sourcerykit sourcerykit init # one-time setup: account, database, credentials ``` -Give your agent `SourceryKitAgentResponse` as its output type, then verify its claims against the recorded calls before you trust them: - -```python -import sourcerykit -from sourcerykit import SourceryKitAgentResponse # your agent's output_type - -await sourcerykit.bootstrap_system() -await sourcerykit.insert_trusted_endpoint(url="https://api.example.com/data") - -# ... run your agent inside an intercept context, then build the payload ... -result = await sourcerykit.evaluate_handoff(payload=payload) -print(result["outcome"]) # PASS | CAUGHT | ERROR -``` - -See the [full runnable example](#quick-example) below. - - -## How Does It Work? - -SourceryKit handles policy enforcement and logging right inside your agent's normal workflow: - -
- architecture -
- -### The Pieces - -- **HTTP Interceptor**: Patches your HTTP libraries to watch and log outbound calls, blocking untrusted requests on the spot. -- **Trusted Endpoints**: A database allow-list of approved destinations for your agent. -- **Intercepts Table**: An append-only DB table that logs every request and response for auditing. -- **SourceryKitAgentResponse**: A Pydantic model used as the structured response_format for your agent. Enforces a typed response contract with a `claimed_values` list of extracted values. -- **Handoff Payload**: A clean data bundle containing the claims your agent is making about its external actions. -- **Evaluator**: Compares the handoff payload against records in the Provably backend to give you a clear verdict. -- **Provably Backend**: The source of truth that turns your local intercepts into anchored verification proofs. - - -## Configuration -To get things running, SourceryKit must be configured with your project variables. The interactive CLI handles account provisioning, organization workspace initialization, database validation, and persists credentials globally (OS application folder) and locally (project `.env`). - -```bash -sourcerykit init -``` - -The wizard will guide you through: -- **Account Setup & Authorization**: Create a new account or log into an existing one, and select your organization workspace. -- **API Key Generation**: Automatically fetch your SDK API-KEY from your account profile. -- **Database Handshake**: Enter your database details, test the connection, and ensure it's accessible. -- **Save Config**: Automatically write your credentials and tokens straight to a local .env file. - -> ⚠️ **IMPORTANT:** The wizard only configures **SOURCERYKIT_*** variables. It does **not** handle third-party LLM provider infrastructure keys, which must still be exported separately. - -### Manual configuration (fallback) - -Already have credentials, or need to bypass the wizard (CI, containers, debugging)? Environment -variables override the stored config: - -```bash -export PROVABLY_API_KEY="..." -export SOURCERYKIT_ORG_ID="..." -export SOURCERYKIT_POSTGRES_URL="postgresql://user:password@host:5432/db" -``` +Or install from source: -For a full list of CLI commands, check out the [CLI Documentation](https://provably.ai/docs/getting_started/cli) file, or simply run: ```bash -sourcerykit --help +git clone git@github.com:ProvablyAI/sourcerykit.git +pip install -e ./sourcerykit ``` -For a full list of environment variables, see [.env.example](https://github.com/ProvablyAI/sourcerykit/blob/main/.env.example). - -## Quick Example -Here is how to bootstrap the system, run an intercepted request, build a payload, and check if everything passes validation: +Bootstrap the system, run an intercepted request, build the payload, and check the verdict: ```python import uuid @@ -159,6 +95,59 @@ async def run_verifiable_agent(): ``` +## How Does It Work? + +SourceryKit handles policy enforcement and logging right inside your agent's normal workflow: + +
+ architecture +
+ +### The Pieces + +- **HTTP Interceptor**: Patches your HTTP libraries to watch and log outbound calls, blocking untrusted requests on the spot. +- **Trusted Endpoints**: A database allow-list of approved destinations for your agent. +- **Intercepts Table**: An append-only DB table that logs every request and response for auditing. +- **SourceryKitAgentResponse**: A Pydantic model used as the structured response_format for your agent. Enforces a typed response contract with a `claimed_values` list of extracted values. +- **Handoff Payload**: A clean data bundle containing the claims your agent is making about its external actions. +- **Evaluator**: Compares the handoff payload against records in the Provably backend to give you a clear verdict. +- **Provably Backend**: The source of truth that turns your local intercepts into anchored verification proofs. + + +## Configuration +To get things running, SourceryKit must be configured with your project variables. The interactive CLI handles account provisioning, organization workspace initialization, database validation, and persists credentials globally (OS application folder) and locally (project `.env`). + +```bash +sourcerykit init +``` + +The wizard will guide you through: +- **Account Setup & Authorization**: Create a new account or log into an existing one, and select your organization workspace. +- **API Key Generation**: Automatically fetch your SDK API-KEY from your account profile. +- **Database Handshake**: Enter your database details, test the connection, and ensure it's accessible. +- **Save Config**: Automatically write your credentials and tokens straight to a local .env file. + +> ⚠️ **IMPORTANT:** The wizard only configures **SOURCERYKIT_*** variables. It does **not** handle third-party LLM provider infrastructure keys, which must still be exported separately. + +### Manual configuration (fallback) + +Already have credentials, or need to bypass the wizard (CI, containers, debugging)? Environment +variables override the stored config: + +```bash +export PROVABLY_API_KEY="..." +export SOURCERYKIT_ORG_ID="..." +export SOURCERYKIT_POSTGRES_URL="postgresql://user:password@host:5432/db" +``` + +For a full list of CLI commands, check out the [CLI Documentation](https://provably.ai/docs/getting_started/cli) file, or simply run: +```bash +sourcerykit --help +``` + +For a full list of environment variables, see [.env.example](https://github.com/ProvablyAI/sourcerykit/blob/main/.env.example). + + ## More Docs Want to dig into the details? Check out our documentation and specific guides: diff --git a/pyproject.toml b/pyproject.toml index e395ee4..ed758ca 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -33,7 +33,6 @@ classifiers = [ "Topic :: System :: Monitoring", "Topic :: Software Development :: Libraries :: Python Modules", "Programming Language :: Python :: 3", - "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Programming Language :: Python :: Implementation :: CPython", From ac71106aa79f28f77b5532ff611e056db242ba63 Mon Sep 17 00:00:00 2001 From: rimkusaurimas Date: Fri, 17 Jul 2026 10:32:51 +0200 Subject: [PATCH 4/8] docs: shrink logo, split quickstart into a short teaser + full Example section --- README.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cfe678e..33671aa 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@
- SourceryKit + SourceryKit
@@ -24,13 +24,30 @@ pip install sourcerykit sourcerykit init # one-time setup: account, database, credentials ``` -Or install from source: +Give your agent `SourceryKitAgentResponse` as its output type, then verify its claims before you trust them: + +```python +import sourcerykit +from sourcerykit import SourceryKitAgentResponse # your agent's output_type + +await sourcerykit.bootstrap_system() +await sourcerykit.insert_trusted_endpoint(url="https://api.example.com/data") + +# ... run your agent inside an intercept context, then build the payload ... +result = await sourcerykit.evaluate_handoff(payload=payload) +print(result["outcome"]) # PASS | CAUGHT | ERROR +``` + +Prefer installing from source? ```bash git clone git@github.com:ProvablyAI/sourcerykit.git pip install -e ./sourcerykit ``` + +## Example + Bootstrap the system, run an intercepted request, build the payload, and check the verdict: ```python From 7e4a2b803076b06f91157dfd1037082198eeedba Mon Sep 17 00:00:00 2001 From: rimkusaurimas Date: Fri, 17 Jul 2026 14:21:01 +0200 Subject: [PATCH 5/8] docs: collapse duplicate quickstart/example into one, drop architecture image from How Does It Work --- README.md | 23 +---------------------- 1 file changed, 1 insertion(+), 22 deletions(-) diff --git a/README.md b/README.md index 33671aa..e6afd24 100644 --- a/README.md +++ b/README.md @@ -24,20 +24,6 @@ pip install sourcerykit sourcerykit init # one-time setup: account, database, credentials ``` -Give your agent `SourceryKitAgentResponse` as its output type, then verify its claims before you trust them: - -```python -import sourcerykit -from sourcerykit import SourceryKitAgentResponse # your agent's output_type - -await sourcerykit.bootstrap_system() -await sourcerykit.insert_trusted_endpoint(url="https://api.example.com/data") - -# ... run your agent inside an intercept context, then build the payload ... -result = await sourcerykit.evaluate_handoff(payload=payload) -print(result["outcome"]) # PASS | CAUGHT | ERROR -``` - Prefer installing from source? ```bash @@ -45,10 +31,7 @@ git clone git@github.com:ProvablyAI/sourcerykit.git pip install -e ./sourcerykit ``` - -## Example - -Bootstrap the system, run an intercepted request, build the payload, and check the verdict: +Give your agent `SourceryKitAgentResponse` as its output type, run it inside an intercept context, then check the verdict before you trust its claims: ```python import uuid @@ -116,10 +99,6 @@ async def run_verifiable_agent(): SourceryKit handles policy enforcement and logging right inside your agent's normal workflow: -
- architecture -
- ### The Pieces - **HTTP Interceptor**: Patches your HTTP libraries to watch and log outbound calls, blocking untrusted requests on the spot. From e79d33814f625b04679e5bb742463126852a4ef0 Mon Sep 17 00:00:00 2001 From: rimkusaurimas Date: Fri, 17 Jul 2026 14:23:42 +0200 Subject: [PATCH 6/8] docs: bump logo width 180->220 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e6afd24..8766237 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@
- SourceryKit + SourceryKit
From 36343272bbbf4c42d43dd42474ff42cbc198a3ed Mon Sep 17 00:00:00 2001 From: rimkusaurimas Date: Fri, 17 Jul 2026 14:26:45 +0200 Subject: [PATCH 7/8] docs: add Features section up top, move Quickstart below How Does It Work (Simone review) --- README.md | 39 ++++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 8766237..f0e7e6b 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,30 @@ SourceryKit is the Python SDK for [Provably](https://provably.ai). It provides v > ⚠️ **IMPORTANT:** Upgrading the SDK from v0.2 to v1.0? See the [v1.0 migration guide](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/migrations/v1_0/v1_0.md). +## Features + +- **Verifiable guardrails** — checks your agent's claims against recorded ground truth, so a hallucinated value is caught before it ships. +- **Automatic HTTP interception** — records every outbound call (`httpx`, `aiohttp`, `requests`) with no changes to your agent code. +- **Endpoint allow-listing** — blocks requests to untrusted destinations at the source. +- **Deterministic verdicts** — every run resolves to `PASS`, `CAUGHT`, or `ERROR` against cryptographically anchored records. +- **Framework-agnostic** — drops into OpenAI Agents SDK, LangChain, Claude Agent SDK, CrewAI, and LangGraph. + + +## How Does It Work? + +SourceryKit handles policy enforcement and logging right inside your agent's normal workflow: + +### The Pieces + +- **HTTP Interceptor**: Patches your HTTP libraries to watch and log outbound calls, blocking untrusted requests on the spot. +- **Trusted Endpoints**: A database allow-list of approved destinations for your agent. +- **Intercepts Table**: An append-only DB table that logs every request and response for auditing. +- **SourceryKitAgentResponse**: A Pydantic model used as the structured response_format for your agent. Enforces a typed response contract with a `claimed_values` list of extracted values. +- **Handoff Payload**: A clean data bundle containing the claims your agent is making about its external actions. +- **Evaluator**: Compares the handoff payload against records in the Provably backend to give you a clear verdict. +- **Provably Backend**: The source of truth that turns your local intercepts into anchored verification proofs. + + ## Quickstart Requires **Python 3.12+**. @@ -95,21 +119,6 @@ async def run_verifiable_agent(): ``` -## How Does It Work? - -SourceryKit handles policy enforcement and logging right inside your agent's normal workflow: - -### The Pieces - -- **HTTP Interceptor**: Patches your HTTP libraries to watch and log outbound calls, blocking untrusted requests on the spot. -- **Trusted Endpoints**: A database allow-list of approved destinations for your agent. -- **Intercepts Table**: An append-only DB table that logs every request and response for auditing. -- **SourceryKitAgentResponse**: A Pydantic model used as the structured response_format for your agent. Enforces a typed response contract with a `claimed_values` list of extracted values. -- **Handoff Payload**: A clean data bundle containing the claims your agent is making about its external actions. -- **Evaluator**: Compares the handoff payload against records in the Provably backend to give you a clear verdict. -- **Provably Backend**: The source of truth that turns your local intercepts into anchored verification proofs. - - ## Configuration To get things running, SourceryKit must be configured with your project variables. The interactive CLI handles account provisioning, organization workspace initialization, database validation, and persists credentials globally (OS application folder) and locally (project `.env`). From d572af16b6e7649233cd46fcc4a9179e84f0122c Mon Sep 17 00:00:00 2001 From: aural-psynapse Date: Fri, 17 Jul 2026 15:38:09 +0200 Subject: [PATCH 8/8] docs: merge How Does It Work into a single Features section (Simone review) --- README.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/README.md b/README.md index f0e7e6b..9efc5e9 100644 --- a/README.md +++ b/README.md @@ -23,12 +23,7 @@ SourceryKit is the Python SDK for [Provably](https://provably.ai). It provides v - **Deterministic verdicts** — every run resolves to `PASS`, `CAUGHT`, or `ERROR` against cryptographically anchored records. - **Framework-agnostic** — drops into OpenAI Agents SDK, LangChain, Claude Agent SDK, CrewAI, and LangGraph. - -## How Does It Work? - -SourceryKit handles policy enforcement and logging right inside your agent's normal workflow: - -### The Pieces +Under the hood, these are the pieces doing the work: - **HTTP Interceptor**: Patches your HTTP libraries to watch and log outbound calls, blocking untrusted requests on the spot. - **Trusted Endpoints**: A database allow-list of approved destinations for your agent.