sourcerykit 1.0.0b1__tar.gz

sourcerykit-1.0.0b1/.gitignore

@@ -0,0 +1,65 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Pre-commit hook environments (local cache)
+.cache/
+
+# Cursor IDE / debug session artifacts
+.cursor/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Documentation
+docs/_build/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.hypothesis/
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+.pytype/
+
+# IDEs
+.claude/
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets
+.env
+.env.*
+!.env.example

sourcerykit-1.0.0b1/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 1.0.0
+
+Major release following a full repository refactor. The package is now published as **`sourcerykit`**.
+
+### Breaking changes
+
+- **Package renamed** — all imports change from `provably` to `sourcerykit`. (#44)
+- **`set_interceptor_context` removed** — replaced by the `intercept_context()` context manager, which correctly scopes the `ContextVar` and prevents leaks across requests. (#44)
+- **Database schema redesigned** — `provably_intercepts` and `trusted_endpoints` now use `UUID` primary keys (was `SERIAL`) with updated column types (e.g. `indexed_average` stored as `TEXT`). Run `alembic upgrade head` (migration `000` drops old tables, `001`/`002` recreate them). (#44)
+
+### Architecture & tooling
+
+- **Async architecture** — HTTP client migrated to `httpx` async; database layer upgraded to async SQLAlchemy. (#44)
+- **Alembic migrations** — schema changes are managed via versioned Alembic scripts. (#44)
+- **Authentication service** — `SourceryKitAuthService` handles account and organisation management against the Provably API. (#44)
+- **CLI setup wizard** — interactive `sourcerykit init` command for first-time account, org, and database configuration. (#44)
+- **Test coverage gate** — `pytest-cov` enforces a 60 % floor on the unit suite in CI. (#44)
+
+### Examples & onboarding
+
+- **Cookbooks** — runnable examples using Claude Agent SDK, OpenAI Agents SDK and Langchain Agent SDK. (#44)
+- **Skill** (`init-sourcerykit`) — step-by-step guided onboarding skill for adding SourceryKit to an existing agent project. (#44)
+- **SDK documentation** — full developer docs (Sphinx) covering interception, handoffs, trusted endpoints, and verification modes. (#44)
+
+## 0.2.0
+
+- Added `configure_indexing(enable_indexing)`: one-call bootstrap (`initialize_runtime` + `init_interceptor` + enable/disable) for sender agents.
+- Added `outcome_from_trace(trace)` and `aggregate_outcome(payload)` helpers for extracting and rolling up verdicts.
+- Added `set_intercept_url_allowlist(urls)` to top-level namespace; scopes the simulation body hook to an explicit set of URLs.
+- `Outcome` now includes `"ERROR"` alongside `"PASS"` and `"CAUGHT"`.
+- Logging migrated from `print()` to structured `structlog` output.
+
+## 0.1.0
+
+Init.
+
+- `initialize_runtime` for one-time bootstrap.
+- `intercept` module: monkey-patches `requests` and `httpx`, records rows in `provably_intercepts`, enforces trusted-endpoint allow-list.
+- `handoff` module: `HandoffPayload`, `HandoffClaim`, `post_handoff`, and `evaluate_handoff` with per-claim verification modes (`verbatim`, `field_extraction`, `schema_type`, `range_threshold`).
+- `claim_contract` builder: generates the LLM-facing JSON contract from `HandoffClaim` + `VerificationMode`.
+- `trusted_endpoints`: `is_trusted_endpoint`, `list_trusted_endpoints`, `check_claim_endpoints_are_trusted`.

sourcerykit-1.0.0b1/LICENSE.md

@@ -0,0 +1,101 @@
+# License
+
+Business Source License 1.1
+
+Copyright © 2026 Provably Technologies LTD
+
+Use Limitation:  You may not offer the Software as a commercial hosted
+service without purchasing a commercial license from Provably Technologies Ltd.
+
+Change Date:     2029-05-07
+Change License:  GPL-3.0-or-later
+
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+
+1. Definitions
+   The "Licensed Work" is the software and documentation made available
+   under this License.
+   The "Licensor" is the entity offering the Licensed Work under this
+   License.
+   "You" refers to the licensee of the Licensed Work.
+   "Use Limitation" means the restrictions (if any) placed on your use of
+   the Licensed Work before the Change Date, as listed in the license
+   parameters at the top of this License.
+   "Additional Use Grant" means additional rights (if any) the Licensor
+   grants to you before the Change Date, as listed in the license parameters
+   at the top of this License.
+   The "Change License" is the license selected by the Licensor to replace
+   this License, as listed in the license parameters at the top of this
+   License.
+   The "Change Date" is the date when the license automatically changes
+   from this License to the Change License, as listed in the license
+   parameters at the top of this License.
+   "Distribution" and "Use" have the same meaning as under copyright law.
+
+
+2. License Grant
+   From the Effective Date until the Change Date, the Licensor hereby grants
+   you the following rights:
+   a)  The right to copy, modify, create derivative works, redistribute, and
+       make non-production Use of the Licensed Work, solely in compliance
+       with the Use Limitation and Additional Use Grant.
+   b)  The right to sublicense the foregoing rights to third parties acting
+       on your behalf (for example, cloud service providers or contractors),
+       subject to the same Use Limitation.
+
+   All other rights are expressly reserved by the Licensor.
+
+
+3. Change Date
+   On the Change Date, the rights granted in Section 2 terminate, and you
+   may thereafter exercise the rights granted to you under the Change
+   License.  The Licensor will publish the Change License in the same
+   repository or source as the Licensed Work or in any successor location.
+
+
+4. Compliance and Termination
+   Any Use of the Licensed Work not expressly permitted under this License
+   (including violating the Use Limitation) is **prohibited**.
+
+   If you violate this License, your rights will terminate automatically,
+   and you must cease all Use and Distribution of the Licensed Work as soon
+   as possible.  Your licenses from anyone else remain in force.
+
+
+5. Disclaimer of Warranty
+   THE LICENSED WORK IS PROVIDED "AS IS". TO THE MAXIMUM EXTENT PERMITTED
+   BY APPLICABLE LAW, THE LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
+   NON-INFRINGEMENT.
+
+
+6. Limitation of Liability
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL THE
+   LICENSOR BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR
+   CONSEQUENTIAL DAMAGES ARISING OUT OF OR IN CONNECTION WITH THE LICENSED
+   WORK OR THIS LICENSE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+
+7. Trademarks
+   This License does not grant permission to use the Licensor's trademarks
+   or trade names, except to the extent required for reasonable and
+   customary use in describing the origin of the Licensed Work.
+
+
+8. Severability
+   If any provision of this License is held unenforceable or invalid under
+   applicable law, such provision shall be interpreted to accomplish the
+   objectives of such provision to the greatest extent possible and the
+   remaining provisions shall continue in full force and effect.
+
+
+9. Governing Law
+   This License shall be governed by and construed in accordance with the
+   laws of the jurisdiction specified by the Licensor, excluding its
+   conflicts-of-law principles.  If no jurisdiction is specified, the laws
+   of Finland apply (excluding conflict-of-law rules).

sourcerykit-1.0.0b1/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: sourcerykit
+Version: 1.0.0b1
+Summary: SourceryKit
+Project-URL: Homepage, https://github.com/ProvablyAI/sourcerykit
+Project-URL: Issues, https://github.com/ProvablyAI/sourcerykit/issues
+Author: Provably Technologies Ltd
+License: Proprietary
+License-File: LICENSE.md
+Keywords: agent,handoff,interceptor,provably,sourcerykit,verifiable
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: alembic>=1.13
+Requires-Dist: greenlet>=3.0
+Requires-Dist: httpx>=0.26
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: msgspec>=0.18.0
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: pydantic>=2.6
+Requires-Dist: python-dotenv>=1.2
+Requires-Dist: questionary>=2.1
+Requires-Dist: requests>=2.31
+Requires-Dist: requests>=2.34
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: structlog>=24.1
+Requires-Dist: typer>=0.26
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: coverage[toml]>=7.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: myst-parser>=5.1; extra == 'dev'
+Requires-Dist: openai-agents>=0.0.3; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Requires-Dist: sphinx-rtd-theme>=3.1; extra == 'dev'
+Requires-Dist: sphinx>=9.1; extra == 'dev'
+Requires-Dist: sphinxcontrib-mermaid>=2.0; extra == 'dev'
+Requires-Dist: types-jsonschema>=4.0; extra == 'dev'
+Requires-Dist: types-requests>=2.31; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="https://github.com/ProvablyAI/sourcerykit/blob/main/docs/logo.svg" alt="SourceryKit" width="280" />
+</div>
+
+<div align="center">
+
+[![status: v1.0.0b1](https://img.shields.io/badge/status-v1.0.0b1-blue)](https://github.com/ProvablyAI/sourcerykit/blob/main/CHANGELOG.md)
+[![python: 3.12+](https://img.shields.io/badge/python-3.12+-blue)](https://github.com/ProvablyAI/sourcerykit/blob/main/pyproject.toml)
+[![license: Proprietary](https://img.shields.io/badge/license-Proprietary-red)](https://github.com/ProvablyAI/sourcerykit/blob/main/LICENSE.md)
+
+</div>
+
+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.
+
+---
+
+> [!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?
+
+SourceryKit handles policy enforcement and logging right inside your agent's normal workflow:
+
+
+```mermaid
+flowchart TD
+  Agent([Agent]) -->|Initializes| Bootstrap[Bootstrap System]
+  Bootstrap -->|Configures| Interceptor[HTTP Interceptor]
+  Bootstrap -->|Registers| TrustedEndpoints[(Trusted Endpoints)]
+
+  Agent -->|Outbound HTTP| Interceptor
+  Interceptor -->|Validates against| TrustedEndpoints
+  Interceptor -->|Logs to| Intercepts[(Intercepts Table)]
+
+  Agent -->|Submits| Handoff[Handoff Payload]
+  Handoff -->|Verified by| Evaluator[Evaluator]
+  Evaluator -->|Queries records| Provably[Provably Backend]
+  Provably -->|Generates proofs from| Intercepts
+  Evaluator -->|Returns Verdict| Agent
+```
+
+### 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.
+
+
+## Quick Example
+Here is how to bootstrap the system, run an intercepted request, build a payload, and check if everything passes validation:
+
+```python
+import uuid
+import httpx
+import sourcerykit
+from agents import Agent, Runner
+from sourcerykit import SourceryKitAgentResponse
+
+async def run_verifiable_agent():
+    # 1. Fire up the system
+    await sourcerykit.bootstrap_system()
+
+    # 2. Tell the registry which URL is allowed
+    await sourcerykit.insert_trusted_endpoint(url="https://api.example.com/data")
+
+    # 3. Make a network call inside an intercept context
+    async with sourcerykit.async_intercept_context(agent_id="demo-agent", action_name="get_data"):
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                "https://api.example.com/data",
+                params={"query": "example_parameter"}
+            )
+            response.raise_for_status()
+
+    # 4. Configure your agent with SourceryKitAgentResponse as the structured output type
+    #    and run it. Each framework exposes the typed result differently, but the output
+    #    is always a SourceryKitAgentResponse with `claimed_values`.
+    #    Pass the keyword argument supported by your framework, e.g.:
+    #      output_type=SourceryKitAgentResponse   (OpenAI Agents SDK)
+    #      response_format=SourceryKitAgentResponse  (LangChain)
+    prompt = You are a helpful assistant.
+    agent = Agent(
+        name="demo-agent",
+        instructions=prompt,
+        tools=[...],
+        model=MODEL_NAME,
+        output_type=SourceryKitAgentResponse,
+    )
+    result = await Runner.run(agent, prompt)
+    final_output: SourceryKitAgentResponse = result.final_output
+
+    # 5. Build the handoff payload from the agent's structured output
+    payload_data = {
+        "reasoning": final_output.reasoning,
+        "claims": [
+            {
+                "action_name": "get_data",
+                "claimed_value": final_output.claimed_values,
+                "verification_mode": "field_extraction",
+            }
+        ],
+    }
+
+    payload = await sourcerykit.build_handoff_payload(
+        payload_data,
+        run_id=uuid.uuid4(),
+        prompt=prompt,
+        intercept_agent_id="demo-agent",
+    )
+
+    # 6. Ask the evaluator for a verdict
+    result = await sourcerykit.evaluate_handoff(payload=payload)
+    print(f"Evaluation Outcome: {result.get('outcome')}") # PASS, CAUGHT, or ERROR
+```
+
+## 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`).
+
+```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.
+
+For a full list of environment variables, see [.env.example](https://github.com/ProvablyAI/sourcerykit/blob/main/.env.example).
+
+For a full list of CLI commands, run:
+```bash
+sourcerykit --help
+```
+
+## More Docs
+Want to dig into the details? Check out the specific guides:
+
+- [Architecture Overview](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/architecture.md)
+- [HTTP Interception](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/intercept.md)
+- [Managing Trusted Endpoints](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/trusted-endpoints.md)
+- [Handoff Contracts & Evaluation](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/handoff.md)
+
+
+## Contributing
+We welcome fixes, features, and doc updates! Check out [CONTRIBUTING.md](https://github.com/ProvablyAI/sourcerykit/blob/main/CONTRIBUTING.md) to see how to run tests and open up a pull request.
+
+## License
+
+This project is licensed under the [Business Source License 1.1](https://github.com/ProvablyAI/sourcerykit/blob/main/LICENSE.md).
+
+- Copyright © 2026 Provably Technologies LTD
+- You may not offer the Software as a commercial hosted service without purchasing a commercial license from [Provably Technologies Ltd](https://provably.ai).
+- On 2029-05-07, the license will automatically convert to GPL-3.0-or-later.
+
+See the [LICENSE](https://github.com/ProvablyAI/sourcerykit/blob/main/LICENSE.md) file for full terms and details.

sourcerykit-1.0.0b1/README.md

@@ -0,0 +1,180 @@
+<div align="center">
+  <img src="https://github.com/ProvablyAI/sourcerykit/blob/main/docs/logo.svg" alt="SourceryKit" width="280" />
+</div>
+
+<div align="center">
+
+[![status: v1.0.0b1](https://img.shields.io/badge/status-v1.0.0b1-blue)](https://github.com/ProvablyAI/sourcerykit/blob/main/CHANGELOG.md)
+[![python: 3.12+](https://img.shields.io/badge/python-3.12+-blue)](https://github.com/ProvablyAI/sourcerykit/blob/main/pyproject.toml)
+[![license: Proprietary](https://img.shields.io/badge/license-Proprietary-red)](https://github.com/ProvablyAI/sourcerykit/blob/main/LICENSE.md)
+
+</div>
+
+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.
+
+---
+
+> [!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?
+
+SourceryKit handles policy enforcement and logging right inside your agent's normal workflow:
+
+
+```mermaid
+flowchart TD
+  Agent([Agent]) -->|Initializes| Bootstrap[Bootstrap System]
+  Bootstrap -->|Configures| Interceptor[HTTP Interceptor]
+  Bootstrap -->|Registers| TrustedEndpoints[(Trusted Endpoints)]
+
+  Agent -->|Outbound HTTP| Interceptor
+  Interceptor -->|Validates against| TrustedEndpoints
+  Interceptor -->|Logs to| Intercepts[(Intercepts Table)]
+
+  Agent -->|Submits| Handoff[Handoff Payload]
+  Handoff -->|Verified by| Evaluator[Evaluator]
+  Evaluator -->|Queries records| Provably[Provably Backend]
+  Provably -->|Generates proofs from| Intercepts
+  Evaluator -->|Returns Verdict| Agent
+```
+
+### 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.
+
+
+## Quick Example
+Here is how to bootstrap the system, run an intercepted request, build a payload, and check if everything passes validation:
+
+```python
+import uuid
+import httpx
+import sourcerykit
+from agents import Agent, Runner
+from sourcerykit import SourceryKitAgentResponse
+
+async def run_verifiable_agent():
+    # 1. Fire up the system
+    await sourcerykit.bootstrap_system()
+
+    # 2. Tell the registry which URL is allowed
+    await sourcerykit.insert_trusted_endpoint(url="https://api.example.com/data")
+
+    # 3. Make a network call inside an intercept context
+    async with sourcerykit.async_intercept_context(agent_id="demo-agent", action_name="get_data"):
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                "https://api.example.com/data",
+                params={"query": "example_parameter"}
+            )
+            response.raise_for_status()
+
+    # 4. Configure your agent with SourceryKitAgentResponse as the structured output type
+    #    and run it. Each framework exposes the typed result differently, but the output
+    #    is always a SourceryKitAgentResponse with `claimed_values`.
+    #    Pass the keyword argument supported by your framework, e.g.:
+    #      output_type=SourceryKitAgentResponse   (OpenAI Agents SDK)
+    #      response_format=SourceryKitAgentResponse  (LangChain)
+    prompt = You are a helpful assistant.
+    agent = Agent(
+        name="demo-agent",
+        instructions=prompt,
+        tools=[...],
+        model=MODEL_NAME,
+        output_type=SourceryKitAgentResponse,
+    )
+    result = await Runner.run(agent, prompt)
+    final_output: SourceryKitAgentResponse = result.final_output
+
+    # 5. Build the handoff payload from the agent's structured output
+    payload_data = {
+        "reasoning": final_output.reasoning,
+        "claims": [
+            {
+                "action_name": "get_data",
+                "claimed_value": final_output.claimed_values,
+                "verification_mode": "field_extraction",
+            }
+        ],
+    }
+
+    payload = await sourcerykit.build_handoff_payload(
+        payload_data,
+        run_id=uuid.uuid4(),
+        prompt=prompt,
+        intercept_agent_id="demo-agent",
+    )
+
+    # 6. Ask the evaluator for a verdict
+    result = await sourcerykit.evaluate_handoff(payload=payload)
+    print(f"Evaluation Outcome: {result.get('outcome')}") # PASS, CAUGHT, or ERROR
+```
+
+## 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`).
+
+```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.
+
+For a full list of environment variables, see [.env.example](https://github.com/ProvablyAI/sourcerykit/blob/main/.env.example).
+
+For a full list of CLI commands, run:
+```bash
+sourcerykit --help
+```
+
+## More Docs
+Want to dig into the details? Check out the specific guides:
+
+- [Architecture Overview](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/architecture.md)
+- [HTTP Interception](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/intercept.md)
+- [Managing Trusted Endpoints](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/trusted-endpoints.md)
+- [Handoff Contracts & Evaluation](https://github.com/ProvablyAI/sourcerykit/blob/main/docs/handoff.md)
+
+
+## Contributing
+We welcome fixes, features, and doc updates! Check out [CONTRIBUTING.md](https://github.com/ProvablyAI/sourcerykit/blob/main/CONTRIBUTING.md) to see how to run tests and open up a pull request.
+
+## License
+
+This project is licensed under the [Business Source License 1.1](https://github.com/ProvablyAI/sourcerykit/blob/main/LICENSE.md).
+
+- Copyright © 2026 Provably Technologies LTD
+- You may not offer the Software as a commercial hosted service without purchasing a commercial license from [Provably Technologies Ltd](https://provably.ai).
+- On 2029-05-07, the license will automatically convert to GPL-3.0-or-later.
+
+See the [LICENSE](https://github.com/ProvablyAI/sourcerykit/blob/main/LICENSE.md) file for full terms and details.

sourcerykit-1.0.0b1/cookbooks/claude_agent/README.md

@@ -0,0 +1,49 @@
+# Claude Agent SDK
+This example demonstrates how to integrate SourceryKit with the [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python). It showcases automated intercept capture, target endpoint allow-list constraints, and runtime evaluation loops inside a structured agent execution flow.
+
+## How It Works
+1. **HTTP Interception**: The `bootstrap_system()` hook dynamically monitors outbound `httpx` calls, ensuring that network operations generated within the agent tool loop (`get_current_temperature_london`) are securely logged to your database intercepts table.
+2. **All-Method Trust Gate**: SourceryKit enforces structural target validation checks against your external network endpoints. The external weather lookup endpoint (`api.open-meteo.com`) is explicitly registered via policy seeds (`insert_trusted_endpoint`) before execution.
+3. **Automated Handoff & Evaluation**: Captured network states are bundled alongside the agent's structured `SourceryKitAgentResponse` output. The agent is configured with `output_format={"type": "json_schema", "schema": SourceryKitAgentResponse.model_json_schema()}`, which enforces a typed contract—the LLM returns a `reasoning` string and a `claimed_values` list of `ClaimedValue` objects (each with a JSONPath `path` and extracted string `value`). These `claimed_values` are passed as the `claimed_value` field in the handoff payload and submitted to `evaluate_handoff` to verify data integrity and catch hallucinations.
+
+
+## Environment Configuration
+Before running the agent, run the interactive setup wizard to configure your SourceryKit project variables automatically:
+
+```bash
+sourcerykit init
+```
+
+> [!IMPORTANT]
+> The wizard only configures **SOURCERYKIT_*** variables. It does **not** configure your LLM provider infrastructure keys (like `MODEL_NAME` or `ANTHROPIC_API_KEY`). Those must still be set up separately in your environment.
+
+You will also need to set these LLM-provider variables manually:
+
+| Variable | Required | Description |
+|---|---|---|
+| `MODEL_NAME` | **yes** | Targeted model architecture identifier string passed to create_agent (e.g., `claude-haiku-4-5`). |
+| `ANTHROPIC_API_KEY` | **yes** | API authentication token. |
+
+---
+
+## Execution
+
+1. Install the SDK package:
+   ```bash
+   pip install sourcerykit claude-agent-sdk python-dotenv httpx pydantic
+   ```
+2. Export your LLM-provider keys into your current shell or place them in a local `.env` file:
+   ```bash
+   export MODEL_NAME="claude-haiku-4-5"
+   export ANTHROPIC_API_KEY="sk-ant-..."
+   ```
+3. Run the example:
+      ```bash
+      # Standard Validation
+      python agent_run.py
+
+      # or
+
+      # Hallucination Simulation
+      python agent_run.py --tamper
+   ```