Migrating to v1.0

July 20, 2026 · View on GitHub

v1.0 is a major refactor focused on async-first architecture, strict type safety, and cleaner internals. If you are upgrading from a previous version, you'll need to make a few adjustments.

Setup

v1.0 introduces a CLI setup wizard. Run it to configure your account, organization, database, and environment in one step:

sourcerykit init

The wizard replaces manual environment variable configuration. See docs/onboarding.md for the full walkthrough.

Package Rename

Update all project imports to use the new package name:

# Previous Version
import provably

# New Version
import sourcerykit

Async Migration

Warning

All public SDK calls are now async. Every function that talks to the database or the Provably API requires await.

The HTTP client has been migrated from requests to httpx (async), and the database layer uses async SQLAlchemy. You will need to:

Wrap your agent entry point in an async def and call it with asyncio.run().
await every sourcerykit.* call (bootstrap_system, async_intercept_context, build_handoff_payload, evaluate_handoff, insert_trusted_endpoint).

# Previous Version (sync)
sourcerykit.configure_indexing()

# New Version (async)
await sourcerykit.bootstrap_system()

Environment Variables

All configuration environment variable prefixes have been standardized to match the new engine scope:

Previous Version	New Version	Notes
`PROVABLY_ORG_ID`	`SOURCERYKIT_ORG_ID`	System-wide prefix change
`POSTGRES_URL`	`SOURCERYKIT_POSTGRES_URL`	System-wide prefix change

Note

PROVABLY_RUST_BE_URL and PROVABLY_MCP_URL are now handled automatically by the runtime configuration loader and are no longer required in your local environment files.

Breaking Change: The core data types of the internal tables have shifted from SERIAL integers to UUID identifiers. The provably_intercepts table has been renamed to intercepts. Upgrading directly from a previous version will cause a structural conflict.

To handle this smoothly, an automated purge script has been integrated directly into the migration sequence. Running the update command will automatically drop the previous tables and initialize the fresh new schemas in a single safe step.

Run the migration engine to update your environment automatically:

sourcerykit upgrade

Or, if running from a repo clone:

alembic upgrade head

Code & API Changes

Core engine methods have been renamed, removed, or restructured:

Previous Version	New Version	Notes
`intercept_context(..)`	`async_intercept_context(..)`	Migrated to an async context manager
`set_interceptor_context(..)`	`async_intercept_context(..)`	Function-style API removed; use the context manager
`configure_indexing()`	`bootstrap_system()`	Renamed for architectural clarity
`take_last_intercept_row_id`	`call_ref`	Old fallback removed; `call_ref` / `sourcerykit_ref` is now the sole intercept resolution mechanism
Not Provided	`insert_trusted_endpoint()`	New method to add trusted endpoints
Not Provided	`SourceryKitAgentResponse`	Pydantic model for structured agent output with `claimed_values` and `answer`

`sourcerykit_ref` on claims

v1.0 introduces multi-tool-call support. Each intercepted tool call now returns a unique sourcerykit_ref. Your agent must copy this reference into every ClaimedValue it produces:

class ClaimedValue(BaseModel):
    path: str
    value: str
    sourcerykit_ref: str  # NEW — copied from tool output, mandatory

Claims without a sourcerykit_ref (or call_ref) will raise at evaluation time.

Setup

Package Rename

Async Migration

Environment Variables

Database Schema Migration

Code & API Changes

sourcerykit_ref on claims

`sourcerykit_ref` on claims