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.
v1.0 introduces a CLI setup wizard. Run it to configure your account, organization, database, and environment in one step:
sourcerykit initThe wizard replaces manual environment variable configuration. See docs/onboarding.md for the full walkthrough.
Update all project imports to use the new package name:
# Previous Version
import provably
# New Version
import sourcerykitWARNING
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:
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()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.
WARNING
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 upgradeOr, if running from a repo clone:
alembic upgrade headCore 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 claimsv1.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, mandatoryClaims without a sourcerykit_ref (or call_ref) will raise at evaluation time.