Query layer

Scull's query layer reads a local schemaset and its compatible index. It has no account, hosted service, or remote-provider dependency.

from scull.query import get_schema_provider

provider = get_schema_provider()
field = provider.get("schema", "schema_version")
context = provider.context("schema", ["schema_version"])
concepts = provider.list_concepts()

get_schema_provider() returns a FileSchemaProvider. Set SCULL_SCHEMA_PATH to select a schema directory; otherwise Scull discovers schemas/ from conventional local locations. CLI and Python readers use the same loader and fail closed on malformed YAML, unsupported versions, invalid schema structure or attachments, and duplicate concepts; invalid files are not silently skipped.

Operations

get(concept, field=None)

Returns a complete schema or one field definition. This is a local YAML lookup.

context(concept, fields, situations=None, *, detailed=False)

Returns selected field definitions plus attached and concept-wide caveats. Situation tags are explicit lowercase dot-delimited metadata—not semantic matching. Omitting them conservatively returns all applicable attached and general caveats.

The default is compact for agent use. JSON Schema fields retain qualified names, types, descriptions, required scopes, concise constraint strings, examples/default annotations, completeness, and rule links without complete interpretation records. Pass detailed=True for those records, or follow a rule link with inspect_schema() for bounded original evidence. Artifact warnings are likewise grouped by kind and count in compact mode; detailed mode retains the complete warning objects.

The bundle also exposes needs_review, warnings, conflicts, and release_ready alongside the schema hash and version. release_ready reflects the mechanical release contract, including a current approval fingerprint; it is not a claim that the documentation is factually correct.

provider.context(
    "deployment_config",
    ["values"],
    situations=["payload.size"],
)

list_concepts() and list_fields(concept)

Return local schemaset inventory. No index or network is required.

search(query, top_k=5, concepts=None)

Search uses a snapshot-pinned SearchEngine shared by the CLI, schemafier search command, and local server. It combines cosine similarity with deterministic lexical overlap:

score = cosine_similarity + provider_lexical_weight × lexical_overlap

The document vectors are pre-baked into the index. Each uncached query is embedded by the configured provider to produce a compatible query vector. Voyage and OpenAI make a network call; the opt-in local providers run on-device. Exact provider identity and vector dimensions must match the index manifest unless both sides declare the reviewed voyage-4 compatibility family. That family permits Large-built indexes to use hosted Lite or explicitly selected pinned Nano queries at the same dimension. Unknown families and Voyage Code 4 remain exact-identity only, so equal-width vectors from unrelated models cannot be mixed accidentally. Search also recomputes actual schema content hashes and compares them with the pinned manifest before embedding a query. A separately edited or deployed schemaset therefore fails with a rebuild message before any hosted query text is sent. If a compatible provider cannot embed the query, search returns lexical matches only rather than blocking. Those results have degraded: true, degraded_reason: "query_embedding_failed", and cosine_score: null; a query with no lexical match returns an empty list. This fallback does not hide index/provider incompatibility, which remains a hard error.

Use concepts to restrict ranking to an explicit domain:

provider.search("how does retry backoff work?", concepts=["job_runtime"])

Programmatic callers can inspect provider.search_degraded after each search. The CLI also writes a degraded-mode warning to stderr.

FileSchemaProvider and SearchEngine pin their loaded artifacts. Recreate or reload long-lived instances after deploying a matching schemaset/index pair.

Agent tool adapter

scull.agent.SCULL_CONTEXT_TOOL is an SDK-neutral function-tool definition for field-triggered context lookup. invoke_context_tool(provider, arguments) validates its arguments and returns the same compact deterministic JSON bundle as provider.context(). Register the separate SCULL_INSPECT_SCHEMA_TOOL when an agent needs bounded access to complete mechanical evidence.

The public tool name is scull_context. Related integrations use scull_search, scull_get, and scull_caveats.

Environment

Voyage and OpenAI use a lexical weight of 0.3. The benchmarked local MiniLM provider uses 0.1; the lower value preserved semantic ordering better in its fixed development sweep.

There is intentionally no remote SchemaProvider in v0.1. Schemasets remain portable local artifacts, and a future managed build service would deliver artifacts rather than become a query runtime dependency.