Remember stores text durably and returns it with a content-addressed id. Remembering identical current text twice is idempotent (same id, stored once)

SanitizeAndMapHeaders maps the inbound headers to the upstream header set and applies any provider auth/signing. upstream is the ALREADY-RESOLVED forw

BuildLearnPlanWithRetro is BuildLearnPlan plus the opt-in retrospective pass. With retro disabled the two are the same code path and the same output b

Create a one-call OTel exporter bound to this Cave's gateway config. The exporter ships spans to the gateway's OTLP endpoint (``POST

BuildLearnPlan is the front-door analyzer: scan config + real history, compute the detectors, the Cave Score, rank by daily-equivalent magnitude, and

A local runtime-policy client for this project. The client pulls the project's published policy bundle (``GET /sdk/v1/runtime-policy`

Credentials returns credentials for signing, refreshing them when they are within five minutes of expiry.

Default returns the engine's shared default counter: the o200k_base BPE tokenizer (the GPT-4o-family encoding), used across every content type. If the

Async view of either runtime type. Other objects pass through.

run drives the server with the given JSON-RPC request lines and returns the decoded responses plus whatever the server logged (which must be empty on

NewRepetition returns the default repetition (run-length) compressor.

Put stores a recovery and returns its content-addressed handle (idempotent).

eachMiddlewareBackend runs test on SQLite, and on Postgres when CAVEMAN_TEST_POSTGRES_URL names a database the test may create schemas in. Each Postgr

Sync view of either runtime type, so sync code paths never receive coroutines. Other objects pass through.

Search the full catalog via the gateway's ``/sdk/v1/tool-search`` endpoint. Returns a :class:`ToolSearchResult` with the reduced tool list

NewLog returns the default log/build-output compressor.

ResidualRisk reports which residual-risk classes a body still exhibits AFTER a Payload pass. An empty result means the body cleared the screen; it doe

A ``caveman_retrieve`` call the runtime refused (unknown or expired handle, 404/410/503) becomes the ``{"error": code}`` tool result the model rea

What the client holds right now.

estimateTokens is the project's inferred token heuristic (bytes/4), matching the usage importer's roughJSONSize/4 convention. Conservative, determinis

Buffer a span, mapping GenAI fields to ``gen_ai.*`` attributes. Returns the :class:`OTelSpan` (with generated ids) so callers can chain

CandidateActionID is a delimiter-safe, stable identity for the complete provider/model/effort tuple. Sixteen digest bytes are enough for compact telem

Detect classifies a payload into a content type. It is deterministic and fail-open: anything it is not confident about is "text", which routes to a co

EngineTools returns the five Caveman compression tools bound to eng. log may be nil. This is the tool set the caveman-mcp binary serves.

EstimateUSD prices already-classified billable token buckets. Token counts must be disjoint: InputTokens is uncached input; CachedInputTokens is cache

Identify resolves the request's principal from its credential alone: a bearer (Authorization: Bearer, or x-cave-api-key for static tokens) decides whe

A schema or a look-alike object cannot create this executable binding. The scope is normalized (spec §9); an * invalid scope returns null, or raise

New builds a Provider from opts.

NewToolSchema returns the tool-schema / tool-catalog compressor. It is selected by forcing the "toolschema" content type (engine.Options.Type); Detect

Simulate runs the same detect → route → compress → count pipeline as Compress but stores NOTHING (no CCR Put) and makes no network call: a pure dry-ru

ToolError is a fail-closed tool error: isError=true with a cave_snake_code, so a host never mistakes it for a successful payload.

configTokenCount uses the engine's offline o200k tokenizer when available. The byte estimate remains an explicit deterministic fallback; callers alway