diff --git a/README.md b/README.md index cf9c247..9efc5e9 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,12 @@
- SourceryKit + SourceryKit
- [![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) + [![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: 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)
@@ -17,15 +15,15 @@ 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). -## How Does It Work? +## Features -SourceryKit handles policy enforcement and logging right inside your agent's normal workflow: +- **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. -
- architecture -
- -### 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. @@ -36,57 +34,23 @@ 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 -``` +## Quickstart -Or install it directly via pip: +Requires **Python 3.12+**. ```bash pip install sourcerykit +sourcerykit init # one-time setup: account, database, credentials ``` - -## 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: +Prefer installing from source? ```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 +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: +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 @@ -150,6 +114,40 @@ async def run_verifiable_agent(): ``` +## 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 6487035..ed758ca 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -15,14 +15,29 @@ 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.12", "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: Implementation :: CPython", "Operating System :: OS Independent", + "Typing :: Typed", ] dependencies = [ "alembic>=1.13", @@ -159,11 +174,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