context_core

Most users should not start here. Start with Getting Started or the supported stateplane SDK surface first.

context_core is the provider-neutral heart of the repository. It is the implementation layer that powers the onboarding imports re-exported by stateplane.

How It Relates To The User-Facing Flow

When a user follows the copy-paste example:

• SourceRef and the normalization helpers build typed context items
• required=True marks any non-negotiable item generically before provider rendering
• validation checks ids, provenance, and budget invariants
• the compiler decides what fits and what gets dropped
• the report layer joins those decisions back to source items

That entire provider-neutral part happens here, before provider_openai renders the final payload.

Responsibilities

• strict Pydantic base models
• source and context schemas
• deterministic JSON serialization and hashing
• normalization helpers
• validation helpers
• deterministic selection
• typed compilation reports

Key Modules

• models.py: strict model base and JSON container helpers
• schemas.py: provider-neutral V1 models
• normalization.py: draft-to-context-item normalization
• validation.py: request and item validation
• compiler.py: deterministic selection and reports
• hashing.py, ids.py, time.py: low-level deterministic utilities

Current Boundary

context_core should stay provider-neutral.

Provider-specific request rendering, payload schemas, and SDK integrations belong in adapter packages such as provider_openai. Most users should consume this indirectly through stateplane.

system and policy items are still optional by default. If one of them must survive selection, mark it required=True during normalization.

Current Gaps

The current package does not yet include:

• compression
• redaction
• replay execution
• storage backends
• provider-specific rendering
• advanced scoring or retrieval

For the broader architecture direction, see the V1 and V2 briefs in the Architecture section.