Skip to content

Commit 95b2457

Browse files
SimoneBottoniSimoneBottoni
authored
docs: update README and bump version to v1.0.0b2 (#52)
Bumping the version to 1.0.0b2 and updating the README to fix rendering bugs on PyPI. ## Key Changes - Fixed broken images: Changed asset links to raw GitHub URLs so logos and architecture diagrams render properly on PyPI. - Fixed alert blocks: Replaced GitHub-specific > [!IMPORTANT] tags with standard markdown emojis so callouts don't break on PyPI. - Updated docs links: Added links to provably.ai/docs, cookbooks, and the end-to-end walkthrough. - Version bump: Set version to 1.0.0b2 in pyproject.toml.
1 parent cc57471 commit 95b2457

7 files changed

Lines changed: 112 additions & 130 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
# Changelog
22

3-
## 1.0.0
3+
## 1.0.0b2
4+
5+
### Documentation & Assets
6+
- **Fixed PyPI asset rendering** — Switched logo and architecture diagram links to absolute raw URLs so they render properly on PyPI.
7+
- **Fixed alert block formatting** — Replaced GitHub-specific `> [!IMPORTANT]` tags with standard markdown emojis to prevent broken rendering on PyPI.
8+
- **Updated documentation links** — Added explicit links to `provably.ai/docs`, hands-on cookbooks, and the end-to-end walkthrough guide.
9+
10+
11+
## 1.0.0b1
412

513
Major release following a full repository refactor. The package is now published as **`sourcerykit`**.
614

‎README.md‎

Lines changed: 60 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,26 @@
11
<div align="center">
2-
<img src="https://github.com/ProvablyAI/sourcerykit/blob/main/docs/logo.svg" alt="SourceryKit" width="280" />
3-
</div>
4-
5-
<div align="center">
2+
<img src="https://raw.githubusercontent.com/ProvablyAI/sourcerykit/refs/heads/main/docs/images/logo.svg" alt="SourceryKit" width="280" />
63

7-
[![status: v1.0.0b1](https://img.shields.io/badge/status-v1.0.0b1-blue)](https://github.com/ProvablyAI/sourcerykit/blob/main/CHANGELOG.md)
8-
[![python: 3.12+](https://img.shields.io/badge/python-3.12+-blue)](https://github.com/ProvablyAI/sourcerykit/blob/main/pyproject.toml)
9-
[![license: Proprietary](https://img.shields.io/badge/license-Proprietary-red)](https://github.com/ProvablyAI/sourcerykit/blob/main/LICENSE.md)
4+
<br />
105

6+
[![status: v1.0.0b2](https://img.shields.io/badge/status-v1.0.0b2-blue)](https://github.com/ProvablyAI/sourcerykit/blob/main/CHANGELOG.md)
7+
[![python: 3.12+](https://img.shields.io/badge/python-3.12+-blue)](https://github.com/ProvablyAI/sourcerykit/blob/main/pyproject.toml)
8+
[![license: Proprietary](https://img.shields.io/badge/license-Proprietary-red)](https://github.com/ProvablyAI/sourcerykit/blob/main/LICENSE.md)
119
</div>
1210

13-
SourceryKit is the Python SDK for [Provably](https://provably.ai). It provides verifiable guardrails for AI agents by automatically recording outbound HTTP calls, enforcing endpoint policies, and checking your agent's claims against a source of truth—all before any request leaves your process.
1411

15-
---
12+
SourceryKit is the Python SDK for [Provably](https://provably.ai). It provides verifiable guardrails for AI agents by automatically recording outbound HTTP calls, enforcing endpoint policies, and checking your agent's claims against a source of truth—all before any request leaves your process.
1613

17-
> [!IMPORTANT]
18-
> 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).
14+
> ⚠️ **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).
1915
2016

2117
## How Does It Work?
2218

2319
SourceryKit handles policy enforcement and logging right inside your agent's normal workflow:
2420

25-
26-
```mermaid
27-
flowchart TD
28-
Agent([Agent]) -->|Initializes| Bootstrap[Bootstrap System]
29-
Bootstrap -->|Configures| Interceptor[HTTP Interceptor]
30-
Bootstrap -->|Registers| TrustedEndpoints[(Trusted Endpoints)]
31-
32-
Agent -->|Outbound HTTP| Interceptor
33-
Interceptor -->|Validates against| TrustedEndpoints
34-
Interceptor -->|Logs to| Intercepts[(Intercepts Table)]
35-
36-
Agent -->|Submits| Handoff[Handoff Payload]
37-
Handoff -->|Verified by| Evaluator[Evaluator]
38-
Evaluator -->|Queries records| Provably[Provably Backend]
39-
Provably -->|Generates proofs from| Intercepts
40-
Evaluator -->|Returns Verdict| Agent
41-
```
21+
<div align="center">
22+
<img src="https://raw.githubusercontent.com/ProvablyAI/sourcerykit/refs/heads/main/docs/images/architecture.svg" alt="architecture" width="550" />
23+
</div>
4224

4325
### The Pieces
4426

@@ -51,6 +33,45 @@ flowchart TD
5133
- **Provably Backend**: The source of truth that turns your local intercepts into anchored verification proofs.
5234

5335

36+
## Installation
37+
38+
SourceryKit requires **Python 3.12+**. You can grab it directly from source:
39+
40+
```bash
41+
git clone git@github.com:ProvablyAI/sourcerykit.git
42+
pip install -e ./sourcerykit
43+
```
44+
45+
Or install it directly via pip:
46+
47+
```bash
48+
pip install sourcerykit
49+
```
50+
51+
52+
## Configuration
53+
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`).
54+
55+
```bash
56+
sourcerykit init
57+
```
58+
59+
The wizard will guide you through:
60+
- **Account Setup & Authorization**: Create a new account or log into an existing one, and select your organization workspace.
61+
- **API Key Generation**: Automatically fetch your SDK API-KEY from your account profile.
62+
- **Database Handshake**: Enter your database details, test the connection, and ensure it's accessible.
63+
- **Save Config**: Automatically write your credentials and tokens straight to a local .env file.
64+
65+
> ⚠️ **IMPORTANT:** The wizard only configures **SOURCERYKIT_*** variables. It does **not** handle third-party LLM provider infrastructure keys, which must still be exported separately.
66+
67+
68+
For a full list of CLI commands, check out the [CLI Documentation](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/cli.md) file, or simply run:
69+
```bash
70+
sourcerykit --help
71+
```
72+
73+
For a full list of environment variables, see [.env.example](https://github.com/ProvablyAI/sourcerykit/blob/main/.env.example).
74+
5475
## Quick Example
5576
Here is how to bootstrap the system, run an intercepted request, build a payload, and check if everything passes validation:
5677

@@ -77,18 +98,15 @@ async def run_verifiable_agent():
7798
)
7899
response.raise_for_status()
79100

80-
# 4. Configure your agent with SourceryKitAgentResponse as the structured output type
81-
# and run it. Each framework exposes the typed result differently, but the output
82-
# is always a SourceryKitAgentResponse with `claimed_values`.
83-
# Pass the keyword argument supported by your framework, e.g.:
84-
# output_type=SourceryKitAgentResponse (OpenAI Agents SDK)
85-
# response_format=SourceryKitAgentResponse (LangChain)
86-
prompt = You are a helpful assistant.
101+
# 4. Run agent with SourceryKitAgentResponse as the output format
102+
# (e.g., output_type=... for OpenAI, response_format=... for LangChain, output_format=... for Claude).
103+
# The output is a structured response containing `claimed_values`.
104+
prompt = "You are a helpful assistant."
87105
agent = Agent(
88106
name="demo-agent",
89107
instructions=prompt,
90108
tools=[...],
91-
model=MODEL_NAME,
109+
model="model-name",
92110
output_type=SourceryKitAgentResponse,
93111
)
94112
result = await Runner.run(agent, prompt)
@@ -118,48 +136,15 @@ async def run_verifiable_agent():
118136
print(f"Evaluation Outcome: {result.get('outcome')}") # PASS, CAUGHT, or ERROR
119137
```
120138

121-
## Installation
122-
123-
SourceryKit requires **Python 3.12+**. You can grab it directly from source:
124-
125-
```bash
126-
git clone git@github.com:ProvablyAI/sourcerykit.git
127-
pip install -e ./sourcerykit
128-
```
129-
130-
Or install it directly via pip:
131-
132-
```bash
133-
pip install sourcerykit
134-
```
135-
136-
137-
## Configuration
138-
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`).
139-
140-
```bash
141-
sourcerykit init
142-
```
143-
144-
The wizard will guide you through:
145-
- **Account Setup & Authorization**: Create a new account or log into an existing one, and select your organization workspace.
146-
- **API Key Generation**: Automatically fetch your SDK API-KEY from your account profile.
147-
- **Database Handshake**: Enter your database details, test the connection, and ensure it's accessible.
148-
- **Save Config**: Automatically write your credentials and tokens straight to a local .env file.
149-
150-
> [!IMPORTANT]
151-
> The wizard only configures **SOURCERYKIT_*** variables. It does **not** handle third-party LLM provider infrastructure keys, which must still be exported separately.
152-
153-
For a full list of environment variables, see [.env.example](https://github.com/ProvablyAI/sourcerykit/blob/main/.env.example).
154-
155-
For a full list of CLI commands, run:
156-
```bash
157-
sourcerykit --help
158-
```
159139

160140
## More Docs
161-
Want to dig into the details? Check out the specific guides:
141+
Want to dig into the details? Check out our documentation and specific guides:
142+
143+
* **Official Documentation:** Visit [provably.ai/docs](https://provably.ai/docs) for the complete reference.
144+
* [End-to-End Walkthrough](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/example.md) — Get up and running from scratch.
145+
* [Cookbooks & Examples](https://github.com/ProvablyAI/sourcerykit/tree/main/cookbooks) — Practical recipes and code samples.
162146

147+
### Technical Guides
163148
- [Architecture Overview](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/architecture.md)
164149
- [HTTP Interception](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/intercept.md)
165150
- [Managing Trusted Endpoints](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/trusted-endpoints.md)

‎docs/architecture.md‎

Lines changed: 3 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,22 +4,9 @@ The SourceryKit SDK adds verifiable guardrails to Python agents by making outbou
44
## Core Flow
55
SourceryKit intercepts an agent’s outbound HTTP calls, enforces endpoint policies, records interactions, and enables deterministic evaluation of claims.
66

7-
```mermaid
8-
flowchart TD
9-
Agent([Agent]) -->|Initializes| Bootstrap[Bootstrap System]
10-
Bootstrap -->|Configures| Interceptor[HTTP Interceptor]
11-
Bootstrap -->|Registers| TrustedEndpoints[(Trusted Endpoints)]
12-
13-
Agent -->|Outbound HTTP| Interceptor
14-
Interceptor -->|Validates against| TrustedEndpoints
15-
Interceptor -->|Logs to| Intercepts[(Intercepts Table)]
16-
17-
Agent -->|Submits| Handoff[Handoff Payload]
18-
Handoff -->|Verified by| Evaluator[Evaluator]
19-
Evaluator -->|Queries records| Provably[Provably Backend]
20-
Provably -->|Generates proofs from| Intercepts
21-
Evaluator -->|Returns Verdict| Agent
22-
```
7+
<div align="center">
8+
<img src="https://raw.githubusercontent.com/ProvablyAI/sourcerykit/refs/heads/main/docs/images/architecture.svg" alt="architecture" width="550" />
9+
</div>
2310

2411
## Component Overview
2512

‎docs/images/architecture.svg‎

Lines changed: 1 addition & 0 deletions
Loading

docs/logo.svg renamed to docs/images/logo.svg

File renamed without changes.

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
44

55
[project]
66
name = "sourcerykit"
7-
version = "1.0.0b1"
7+
version = "1.0.0b2"
88
description = "SourceryKit"
99
readme = "README.md"
1010
requires-python = ">=3.12"

0 commit comments

Comments
 (0)