api-reference.md

KUMA Python API reference

For explicit KumaClient.upload_observation, list_observations, get_observation and delete_observation, including arguments, return fields, scopes and privacy, see Cloud observations. These APIs are available in KUMA 0.3.0 or later; cloud features also require server support.

For active operation interval revisions, bounded backoff and strict timeout behavior, see Operation polling and deadlines.

Chinese overview | English

This page documents the stable user-facing Python entry points. Types, defaults, ranges, side effects, and failure behavior match the current implementation. KUMA uses keyword-only arguments for its main APIs so call sites remain readable.

Local observation: observe and ObservationSession

Use kuma.observe(tracer_provider=None, external_run_id=None, external_invocation_id=None, limits=None) as a synchronous or asynchronous context around an already instrumented Agent. It creates no Case/Judge, reads no credentials and performs no upload. After exit, call export() for detached redacted JSON, render_text() for a timeline, or save(path, root=...) for explicit atomic local publication without overwriting existing files. Capture failures do not block the Agent; an Agent exception is propagated unchanged.

See Local observation for every parameter, the complete export schema, lifecycle/async behavior, limits, privacy, exceptions and a runnable example.

check_for_updates

from kuma import check_for_updates

update = check_for_updates()
print(update["status"], update["latest_version"], update["release_url"])

No parameters. Returns a detached dict: status is disabled, checking, unavailable, up_to_date, optional (new patch) or required (new major/minor); current_version is the local string, latest_version and release_url are validated official-release values or None, and cached is boolean. Required is a strong reminder, never a blocked request or automatic installation.

Explicit calls can perform one anonymous GitHub HTTPS request (one-second socket timeout, 64 KiB cap, no retry); ordinary failure returns unavailable. Concurrent checks return checking without waiting. Success/failure is cached in memory for 24 hours per process. Set KUMA_DISABLE_UPDATE_CHECK=1 to disable even explicit calls. No credentials, Agent data, disk writes, proxies or redirects. Official transport schedules the same checker on a daemon thread; import/help/local/custom paths do not check. CLI equivalent: kuma updates check, JSON stdout, exit zero. See release policy for all status fields and lifecycle limits.

configure

from kuma import configure

credential_path = configure(api_key="dfx_your_key_here")

Argument	Type	Required/default	What it does and when to use it
api_key	str	Required	Saves the credential KUMA will use for official Case and Judge requests. Copy the dfx_... value issued to you; it must be printable ASCII, contain no whitespace/control characters, and be at most 512 encoded bytes. You do not need this for fully local runs.

Returns: the absolute Path of the atomically written user credential file.

Preconditions: pass the complete platform-issued dfx_... value. If KUMA_CONFIG_HOME is set, it must name a directory this process may use for the credential file.

Postconditions: on success, the returned file exists and contains the validated key. Atomic replacement prevents a partially written final file; a failed write removes its temporary file.

Raises: ConfigurationError for invalid keys, unresolved credential locations or mapped filesystem failures. Public errors do not expose raw OS paths/causes.

Side effects and security: creates the credential directory if needed but makes no network request. The file contains the real key; never print, upload, or commit it.

create_run

from kuma import create_run

run = create_run(
    repo_path=".",
    agent_profile_path="agent-profile.md",
)

Argument	Type	Required/default	What it does and when to use it
repo_path	str | os.PathLike[str]	"."	Chooses the repository being tested. KUMA reads bounded metadata and, when enabled, observes file changes below this directory. Use "." when your Python process already runs at the repository root.
storage_path	str | os.PathLike[str] | None	None	Existing external artifact directory, absolute or relative to repo_path. Must not overlap repo_path. None preserves repo/.kuma; explicit mode stores Run state and ledgers under storage_path/.kuma without writing workspace .kuma or .gitignore. Saved Case paths are contained in this selected root. Invalid/unsafe roots raise ConfigurationError before external work, never fall back. This is not sandbox isolation; see the SDK guide.
agent_profile_path	str | os.PathLike[str] | None	None	Points to the UTF-8 Agent Profile describing the Agent, production scenario, expected behavior, and prohibited boundaries. It gives context to the selected Strategy Group but never selects or overrides it. Supply it for official Case generation. Front matter may contain the only explicit group selector—a closed strategy_group coordinate—and a relative tool_capabilities file; both are validated before Provider I/O. Omit when loading case_path or when a custom Case Provider declares agent_profile_required=False.
case_path	str | os.PathLike[str] | None	None	Loads a complete saved kuma.case_artifact.v1 instead of generating a Case. Relative and absolute paths are contained in storage_path when set, otherwise repo_path; never cwd. Cannot combine with case_provider, agent_profile_path, or non-auto strategy. Loading validates at most 5 MiB before credentials/runtime setup and makes no CaseGen/catalog call; max_steps=None uses the saved count, a smaller explicit limit fails without truncation. Official Judge still needs credentials and validates the server original.
case_provider	CaseProvider | callable | None	None	Chooses who creates the test Inputs. Leave None to request an official Case from KUMA; pass a callable when your application supplies its own local Case.
judge_provider	JudgeProvider | callable | None	None	Chooses who evaluates all submitted results and builds the final report. Leave None for the official Judge, or pass a callable for your own local evaluation. Ignored when judge=False.
strategy	str	"auto"	auto uses the catalog's exact default unless a Profile group is explicit. safety-baseline uniformly samples one of seven validated Basic Safety groups for one Case; an explicit Profile group wins. Custom providers receive the value unchanged. Other strategy ID validation is unchanged. See selection and recovery boundaries.
max_steps	int | None	None	Limits how many test steps this Run may contain. For example, 3 allows one, two, or three steps—it does not force exactly three. None uses the official service limit; custom Case Providers require an explicit positive value. An explicit official value above the advertised limit fails before Case generation, and KUMA never truncates a returned Case.
difficulty	str	"D1"	Official generation challenge level: "D0" injects zero problems; "D1" injects one obvious, low-intensity problem; "D2" injects two subtler or composed problems requiring stronger recognition, recovery and verification. max_steps remains an upper bound, not an extra-step allowance. Necessary inputs and solvability must be preserved. No measured failure rate or Judge-severity change is promised. Other values including None raise ConfigurationError(code="config_invalid") before I/O. Default/explicit D1 omit the wire field; D0/D2 are included in request identity. Custom providers and loaded Cases are unchanged.
high_difficulty	bool	False	Explicit official high-challenge generation intent requiring service support and permission. False preserves ordinary difficulty behavior and wire omission; True participates in request identity without changing Judge scoring. Custom and loaded Cases do not generate or receive this flag.
judge	bool	True	Controls whether KUMA evaluates the Run after the last Input. Keep True to receive a TestReport; use False when you only want to execute and record the Case, in which case run.report remains None.
on_failure	str	"continue"	Decides what happens after you submit a step as failed, timeout, or aborted. "continue" delivers the next Input; "stop" ends the Run immediately.
allow_local	bool	False	Allows the Run to start outside Docker for trusted local development. It only bypasses the Docker execution constraint: it does not sandbox the Agent, expand file access, or weaken validation and privacy checks.
track_files	bool	True	Tells KUMA to compare repository file metadata before and after each Input so the Judge can see which files were created, modified, deleted, or renamed. Set False when file changes are irrelevant or unavailable.
upload_diff	bool	False	Adds bounded changed text to file Evidence instead of sending only paths, hashes, sizes, and change types. Enable only when the Judge needs the actual diff and the repository text is safe to disclose; requires track_files=True.
save_local	bool	False	Writes a local JSON copy of each committed Submission under .kuma/runs/<run_id>/. Use it for debugging or audit records. It does not replace submission to an official Judge.
allow_sensitive	bool	False	Lets ordinary Evidence continue when KUMA's scanner flags content as potentially sensitive. Leave False unless you reviewed that content and intend to disclose it; this never allows secrets into OTel Trace Evidence.
timeout	float	300.0 seconds	Limits one HTTP connection attempt to the public KUMA service. Lower it to fail individual network calls sooner. It does not limit the total time spent waiting for Case generation or Judge completion.
operation_wait_timeout	float	600.0 seconds	Limits the total synchronous wait for one official Case or Judge operation, including polling. If it expires, KUMA raises a retryable timeout and keeps safe recovery metadata so the same operation can be resumed.
max_retries	int	2	Sets how many additional attempts KUMA may make after a transient HTTP failure; accepted values are 0–5. Retries reuse the same idempotency key and do not intentionally create another Case or Judge operation.
api_key	str | None	None	Supplies the official-service credential for this Run only. Use it to override the environment or saved credential. With None, KUMA checks KUMA_API_KEY and then the user credential file. Fully local Provider combinations need no key.
trace_evidence	TraceEvidenceCapture | None	None	Supplies a specific in-process OTel capture and its limits for this Run. Pass the object returned by configure_trace_evidence() when you need explicit control. With None, KUMA safely reuses a compatible global Provider when available; otherwise the Run continues without Trace Evidence and records a warning.
scan_strategy_group	bool	False	Disabled automatic matching flag: keep False. True raises ConfigurationError(config_invalid) before file or network I/O, including with an explicit group or custom provider. Privacy scanning and Evidence capability validation remain enabled.
external_run_id	str | None	None	Optional non-secret caller execution label: 1–128 ASCII characters, starting with a letter or digit, then letters, digits, dot, underscore, colon or hyphen. Enables negotiated Official Judge correlation; unsupported services reject before Judge POST instead of dropping it. Omission preserves existing wire unless a Submission supplies an invocation label.
case_request_id	str | None	None	Persist one kreq_ plus 32 lowercase hex digits per logical official generation. Reuse on recovery; distinct IDs intentionally create independent requests. None preserves legacy matching. Unsupported with custom/reloaded Cases. Binding conflicts prevent POST; read-only discovery can precede payload comparison. Older readers may reject explicit ledger records.

external_run_id=None optionally labels the caller's Agent execution. Use a non-secret ASCII label of 1-128 characters (A-Z, a-z, digits, ., _, :, -, starting with a letter or digit). It enables negotiated Run correlation; unsupported official services reject before Judge POST rather than dropping it. See Run correlation and stage timings.

Returns: a synchronous Run in ready state.

Preconditions: repo_path identifies the repository the caller authorizes KUMA to inspect. Official Case generation needs a readable Agent Profile and a valid key. Unless allow_local=True, execution must be inside the supported container environment. Only one Run may own the local active-Run lock.

Postconditions: the returned Run owns that lock and contains one validated Case. If max_steps=N, the Case contains from 1 through N Inputs, not exactly N. If setup fails after runtime acquisition, KUMA closes the runtime and releases the lock before re-raising the error.

Raises: configuration, credential, isolation, Provider, Case, or public service failures raise a concrete KumaError subclass with stable code, retryable, and optional request_id.

Side effects and security: reads the Agent Profile and bounded repository metadata, may create .kuma/, and may call only the public Backend for official Providers. It never contacts MCP, a model, or a database directly. Custom Providers run in the caller's process with that process's permissions.

Official generator selection

create_run(..., high_difficulty=False) accepts only a boolean. The default or explicit False retains the default service generator and is omitted from the wire/hash. True requests the service-managed alternate generator and participates in request/recovery identity. It is independent of D0/D1/D2 and does not change max_steps, Judge, custom providers or loaded Cases. Non-booleans fail before I/O with ConfigurationError(code="config_invalid"). Service failures never cause fallback to the default generator.

Direct callers use OfficialCaseProvider(client, high_difficulty=True) and then .generate_case(context). Retry with the same flag to recover the original operation; changing it creates a different request identity. The SDK accepts no model credentials or provider configuration through this option.

Agent Profile parsing

from kuma.repository import AgentProfileSpec, parse_agent_profile

profile = parse_agent_profile("agent-profile.md")

Argument	Type	Required/default	What it does and when to use it
path	str | Path	Required	Selects the UTF-8 Markdown Agent Profile to validate. Pass the exact file used for this Run; relative paths resolve from the process working directory, so applications should prefer an explicit repository-relative or absolute path.

parse_agent_profile(path) reads the explicitly selected UTF-8 Markdown file, accepts an optional leading BOM, validates closed front matter and the three required behavior sections, and returns an immutable AgentProfileSpec. It may also read one explicitly linked relative input schema and one tool-capability file contained by the Profile directory. It performs no network request and does not upload the raw Profile. Missing files use agent_profile_required; malformed content uses agent_profile_invalid. The returned strategy_group is an exact coordinate declaration—not an inference from Profile prose.

Run

save_case

Argument	Type	Required/default	What it does and when to use it
path	str | os.PathLike[str]	Required	Destination within this Run's repository; relative paths are repository-relative. Its parent must already exist. Choose a new filename: existing files, symlinks, mount escapes and concurrent overwrites are rejected.

Returns: absolute Path to the complete UTF-8 Case artifact (maximum 5,242,880 bytes). Preconditions: the Run has a validated complete Case; official Cases must retain their original public record. Postconditions: Run state, history and Input position do not change; no runtime ID, Evidence, Agent output, Rubric or credential is saved. Raises: ValidationError(case_artifact_invalid) for invalid/changed content, ValidationError(case_origin_invalid) for conflicting origin, SensitiveDataError for sensitive/private content, and ConfigurationError for unsafe/unwritable/existing paths. Side effects: bounded atomic file publication, no network. Privacy checks cannot be disabled. Public checksums detect corruption, not authenticity; official Judge validates the tenant-owned server original. Save/load example and wire boundaries.

run.case_origin is read-only "official" | "custom"; it describes the Case, not which Judge is configured. An official Judge does not make a custom Case official.

get_input

Argument	Type	Required/default	What it does and when to use it
full	bool	False	Chooses how much information your Agent receives. Keep False to get only the actual task payload. Use True when your integration also needs identifiers, index, payload type, constraints, or extensions from the immutable KumaInput.

Returns: the current payload or immutable KumaInput; returns None after all Inputs are committed.

Preconditions: the Run is ready or already input_delivered; submit the current Input before requesting a different one.

Postconditions: first delivery changes ready to input_delivered and starts step Evidence. Repeated calls return the same Input without advancing state or history.

Raises and side effects: invalid order raises InputProtocolError; Evidence startup may raise EvidenceCaptureError. The method may begin bounded capture, but it never calls Judge or appends history.

submit

Argument	Type	Required/default	What it does and when to use it
output	finite JSON-compatible value	Omitted	Sends the Agent's result for the current Input—the value the Judge will evaluate. Pass it explicitly in normal integrations. It may be omitted only when supported OTel instrumentation captured a real final Agent/Workflow output; explicit None does not count as success.
status	str	"completed"	Records how the current Input ended. Use "completed" for a usable result, "failed" for an Agent error, "timeout" when its deadline expired, or "aborted" when execution was intentionally stopped. This value also drives on_failure.
error	str | None	None	Provides a short, user-safe explanation when status is not "completed". It becomes part of the Submission Evidence, so summarize the failure without secrets, file contents, or raw tracebacks.
logs	list[str | Path] | None	None	Names local log files whose newly appended bytes should accompany this Submission. KUMA reads only a bounded increment and applies path and sensitive-data checks. Leave None when logs are not needed.
wait	bool	True	Keeps final Judge execution synchronous: the last submit() returns only after the report or an error is available. The current public API requires True; background polling is not exposed.
external_invocation_id	str | None	None	Labels this Agent invocation using the same safe ASCII rules as external_run_id. Enables negotiated correlation even when the Run label is omitted; never an authorization credential.

| public_messages | Mapping[str, Any] \\| None | None | Pass the bounded bundle returned by kuma.collect_public_messages for this Input. Preserves earlier completed public messages, excludes reasoning, redacts before local persistence, and requires negotiated assessment support for Official Judge. Exact capture/result contract. | | runtime_actors | Sequence[Mapping[str, str]] \| None | None | List/tuple of at most 1000 closed {trace_id, span_id, actor} declarations for this Input's captured OTel spans. Requires public_messages; unknown is the default for undeclared spans. IDs are nonzero lowercase 32/16-character hex. Exact matching, no descendant inference or completeness upgrade. Missing/ambiguous/duplicate selectors fail before commit; final hashes and pointers bind before POST. See actor workflow and retry boundaries. |

| agent_output_actor | str \\| None | None | Explicit producer of the entire observed final output: target_agent, sdk_setup, external_evaluator, reviewer, cross_case_reference, or unknown. Default leaves it unknown. Requires completed nonempty output, Runtime Evidence and public_messages (an honest empty bundle is allowed). Binds the sanitized final output hash/leaf before official upload; no inferred internal speakers, execution proof or completeness upgrade. Invalid declarations fail before commit with agent_output_actor_invalid. See output attribution. |

Returns: TestReport only when the final Submission completes Judge; otherwise None.

Preconditions: one Input is currently delivered. A completed Submission has an explicit non-None output or a supported OTel-captured final output. Requested log paths are within the configured Evidence scope.

Postconditions: success appends exactly one immutable history item and commits Evidence offsets, local records, and Trace byte budget together. A validation/preparation failure leaves the Input delivered. A final Judge failure leaves completed history available for judge() retry.

Raises: protocol, output, serialization, or Evidence failures use the corresponding InputProtocolError, ValidationError, or EvidenceCaptureError; Judge failures retain stable KumaError types.

Side effects and security: may read bounded file/log changes, atomically save a local Submission, and synchronously call Judge. Submitted output, errors, logs, diffs, and Evidence may cross the public Judge boundary; never include credentials, raw tracebacks, prompts, or unapproved file contents.

judge

Upload file counts come from the Backend's max_files configuration: the supported maximum Case step count × 2 (currently 10 × 2 = 20), not this Run's actual step count. One Case artifact and every Evidence file consume a slot. For batch Judge, this limit applies independently to each item, not their sum. The SDK does not hardcode 20. Existing byte and privacy checks remain: Backend enforces combined Case+Evidence bytes for every item, including custom Cases. The SDK preserves its existing per-path checks and conservative aggregate batch cap; this update does not add combined-byte preflight for custom single Judge. File-count rejection occurs before the Judge POST and does not start a Judge. Deploy the matching Backend configuration before updating clients; an older Backend may advertise a smaller limit, which the SDK continues to respect.

Argument	Type	Required/default	What it does and when to use it
wait	bool	True	Makes judge() wait until a final report or error is available. The public Python API is synchronous, so callers must leave this as True; use operation_wait_timeout on create_run() to control the maximum wait.

Returns: the validated TestReport; repeated calls after success return the same report.

Preconditions: all Inputs have committed Submissions, the Run is completed, a Judge Provider is configured, and wait=True.

Postconditions: success stores the report and changes state to report_ready. Failure restores completed, preserving immutable history, idempotency identity, and pending operation for retry.

Raises and side effects: an incomplete Run raises InputProtocolError, wait=False raises ConfigurationError, and Provider/service failures retain stable KumaError types. The call synchronously invokes the configured Judge; retry does not create a second operation merely because polling failed.

cancel

cancel() has no arguments.

Returns: None.

Preconditions: the Run is in a cancellable lifecycle state; a failed or actively committing state cannot be hidden by cancellation.

Postconditions: an unfinished Run is cancelled, active Evidence is discarded, and runtime resources plus the active-Run lock are released. Calls on already cancelled or report_ready Runs are idempotent.

Raises and side effects: invalid states raise InputProtocolError. The call removes validated temporary runtime files but does not submit or invoke Judge.

Read-only properties

Property	Type	What it tells you
run_id	str	Identifies this execution in logs, local artifacts, and public service records.
case_id	str	Identifies the public Case being executed. It is safe to correlate but never exposes the private Rubric.
max_steps	int	Reports how many steps the generated Case actually contains. It is at least 1 and never exceeds the explicit create_run(max_steps=...) limit, or the service/default limit when that argument was None.
state	RunState	Shows which operation is currently legal, such as delivering an Input, submitting, judging, completed, or cancelled.
executed_strategy_group	Mapping[str, str] | None	Detached read-only server-reported execution metadata: schema_version, strategy_group_id (1–80 characters), strategy_group_version (1–32), catalog_release (64 lowercase hex). Historical omission/custom Run returns None, never a request/default substitute. Reading performs no I/O. Submitted coordinates are checked before success; invalid data raises invalid_response during creation/recovery. Not an independent cryptographic proof or part of the raw Case signature/Judge wire.
history	tuple[HistoryItem, ...]	Contains every successfully committed Input and its matching Submission in execution order. It does not include an in-progress step.
report	TestReport | None	Holds the final Judge result after state becomes report_ready; it stays None before Judgment or when judge=False.
runtime_warnings	tuple[str, ...]	Lists stable warning codes for non-fatal Evidence gaps, such as unavailable automatic Trace capture. The Run can still complete.
tool_capabilities_path	Path | None	Holds the absolute local path of the capability document linked by the Agent Profile. The path is retained for caller inspection and is never uploaded.
tool_capabilities_provenance	str | None	Reports user_declared, scanner_generated, or None for the linked local capability document. It describes origin, not verified Agent behavior.

KumaClient

Use KumaClient for authenticated configuration reads without opening a Run.

Argument	Type	Required/default	What it does and when to use it
api_key	str | None	None	Authenticates configuration reads such as entitlements and available strategies. Pass a key only for this client, or leave None to use KUMA_API_KEY and then the saved credential.
base_url	str	Public KUMA URL	Chooses the public Backend that receives the client's GET requests. Ordinary users should keep the default. Remote URLs must use HTTPS; loopback HTTP is allowed for local integration, and URLs containing credentials are rejected.
timeout	float	30.0 seconds	Sets how long each configuration GET may wait for a response before failing. It does not control Case/Judge operation polling.
transport	public transport callable | None	None	Replaces real HTTP with an explicitly supplied transport callable. This is for tests or controlled integrations; ordinary applications should leave it None.

Preconditions: construction validates the URL, timeout, and any discovered key but makes no request. Authenticated read methods require a valid key.

Postconditions: a constructed client is reusable. entitlements(), strategies(), and judge_config() return validated public mappings; strategy_group_catalog() returns a strict typed catalog. None creates a Run.

Raises and side effects: construction raises ConfigurationError for local configuration errors. Read methods make one public Backend GET and may raise KumaAuthenticationError, KumaPermissionError, or KumaRateLimitError. Credential discovery may read the environment or user credential file; the key is never included in repr(client), and no method contacts MCP, a model, or a database directly.

strategy_group_catalog

strategy_group_catalog() takes no arguments.

Returns: immutable StrategyGroupCatalog containing catalog_release, the exact default declaration, and canonically ordered groups. Each StrategyGroup exposes id, version, display_name, description, required_capabilities, available, and limits; limits contain max_steps and supported_difficulties.

Preconditions: the client has an accepted official credential.

Postconditions: the complete public catalog has passed the closed schema, bounds, ordering, uniqueness, and safe-default checks. Callers can use group(declaration) for an exact coordinate lookup and to_dict() for detached canonical JSON.

Raises and side effects: performs one authenticated public catalog read. Authentication, permission, or quota failures preserve their KumaError subclasses; malformed or legacy data raises ValidationError. It does not create a Case or run local suggestion.

Strategy Group API

Use the Strategy Groups guide for the CLI and Agent Profile workflow.

Public name	Accepted input / exposed fields	Result and failure behavior
StrategyGroupDeclaration	Exact id and version; to_dict() adds kuma.strategy_group_selection.v1.	Immutable Agent Profile-ready coordinate.
StrategyGroup	id, version, display_name, description, required_capabilities, available, and group limits.	Immutable validated catalog entry; coordinate returns (id, version) and to_dict() returns detached JSON.
StrategyGroupCatalog	catalog_release, exact default, and ordered groups.	group(declaration) returns the exact entry or None; to_dict() returns canonical catalog JSON.
ResolvedStrategyGroup	Selected group, selection_source, and catalog_release.	to_declaration() returns the Agent Profile object; to_wire() returns the closed resolved public selection.
validate_strategy_group_declaration(value)	Plain mapping with exactly schema_version, id, and version.	Returns StrategyGroupDeclaration; unknown fields, versions, or invalid text raise ValidationError(code="strategy_group_invalid").
validate_strategy_group_catalog(value)	Complete closed catalog mapping.	Returns StrategyGroupCatalog; malformed fields, ordering, limits, coordinates, or default fail closed.
validate_strategy_group_wire_selection(value)	Complete resolved mapping with schema version, group ID/version, source, and catalog release.	Returns a detached public mapping; invalid or extra fields fail closed. Intended for advanced Provider boundaries.

The schema constants STRATEGY_GROUP_SELECTION_SCHEMA_VERSION and STRATEGY_GROUP_CATALOG_SCHEMA_VERSION expose the two accepted versions. These value objects and validators perform no network, filesystem, Agent, or model operation.

Agent capability API

Use the Agent tool capabilities guide for the closed JSON schema, CLI workflow, Agent Profile path rules, and privacy boundary.

Public name	Input	Return value and side effects
scan_agent_tools(tools)	A list or tuple of 1–100 plain tool mappings.	Returns immutable AgentCapabilities with scanner_generated provenance. Does not inspect framework objects or execute tools.
validate_agent_capabilities(value)	A complete plain kuma.agent_tool_capabilities.v1 mapping.	Returns validated, canonically ordered AgentCapabilities; invalid, oversized, or sensitive data fails closed.
load_agent_capabilities(path)	UTF-8 JSON file up to the documented bound.	Reads and validates one file; returns AgentCapabilities.
save_agent_capabilities(document, path)	A mapping or AgentCapabilities plus an explicit destination whose parent already exists.	Revalidates and atomically writes canonical JSON; returns the resolved Path.
scan_agent_tool_manifest(path)	Explicit UTF-8 scanner-input JSON manifest.	Reads only that file and returns generated AgentCapabilities; no Agent import, repository traversal, tool execution, or network.

AgentCapabilities, ToolCapability, and ResourceScope are immutable public values with detached to_dict() output. AGENT_CAPABILITIES_SCHEMA_VERSION identifies the accepted document version. Loading or saving may raise ValidationError or SensitiveDataError; none of these APIs uploads the document.

An Agent Profile link to a reviewed capability file opts official Case generation into uploading its complete normalized tool_capabilities, including schema descriptions/defaults/examples. Local helper calls alone do not upload. Omission sends no declaration; invalid/sensitive content fails before network I/O with tool_capabilities_invalid / sensitive_data_blocked, with no sensitive override. See Agent tool capabilities for bounds and compatibility.

OpenTelemetry

Install kuma-defuzex[otel] before importing kuma.otel.

Argument	Type	Required/default	What it does and when to use it
tracer_provider	OTel SDK Provider | None	None	Selects the in-process OTel Provider from which KUMA receives ended spans. Pass your application's existing Provider when it is not global; None uses the current global Provider. KUMA adds a processor but never replaces or resets the Provider.
logger_provider	OTel SDK Provider | None	None	Selects an existing in-process OTel LoggerProvider for bounded native log metadata. Pass it for explicit OTel log capture; None leaves logs unattached in explicit mode. KUMA never replaces it.
limits	TraceEvidenceLimits | None	None	Controls how much Trace data one Run may retain. Pass custom limits for tighter memory/privacy budgets; None uses the bounded defaults below.

Returns: a TraceEvidenceCapture for create_run(trace_evidence=...).

Preconditions: install the otel extra and configure an in-process OTel SDK Provider that accepts span processors. Pass a non-global Provider explicitly.

Postconditions: one KUMA processor is attached and the returned capture can associate ended spans with a Run. Existing instrumentation and exporters remain installed.

Raises and side effects: invalid Providers or limits raise ConfigurationError. Registration mutates the selected Provider; call once for an explicitly managed Provider. Only bounded allowlisted data is retained; recognized model/tool bodies use separate redacted projections. This does not allow arbitrary source/log bodies, credentials or private Rubrics. See OpenInference capture for the exact body contract.

Argument	Type	Required/default	What happens when the limit is reached
max_spans	positive int	200	After this many ended spans have been retained for a Run, additional spans are dropped and the Evidence reports the drop instead of growing memory without bound.
max_attributes	positive int	32	Keeps at most this many safe, allowlisted attributes on each span; additional attributes are dropped and counted. Sensitive attributes remain rejected regardless of this number.
max_events_per_span	positive int	20	Keeps at most this many safe OTel events on each span; later events are dropped and reported.
max_text_length	positive int	256 characters	Bounds retained metadata strings. Tool arguments/results use a separate 4 MiB canonical JSON limit and are omitted whole, never truncated. See Runtime Trace.
max_total_bytes	positive int	8388608 bytes (8 MiB)	Caps the compact JSON size of all committed Trace envelopes in one Run. KUMA deterministically drops excess Trace data and reports the loss; the value must still fit the smallest valid envelope.
max_log_records	positive int	200	Keeps at most this many normalized OTel log records per step; excess records are dropped and reported.
max_log_bytes	positive int	128000 bytes	Caps structured OTel log artifacts committed across one Run; raw log bodies are not retained.

Preconditions: every value is a positive integer and max_total_bytes is large enough for the required envelope.

Postconditions: the immutable limits make capture drop or truncate excess Trace data with an explicit reason instead of exceeding the configured bounds. Increasing a limit never broadens the privacy allowlist.

Public result contracts

The main immutable contracts are exported from kuma:

Type	Important fields and meaning
KumaInput	run_id, case_id, input_id, zero-based index, payload_type, frozen payload, public constraints, schema version, and public extensions.
Submission	Correlated IDs, terminal step status, JSON output/error, capture completeness, bounded logs/file Evidence, dropped/missing counters, schema version, and extensions.
HistoryItem	One KumaInput paired with its ID-matching Submission.
TestReport	report_id, run_id, status (pass, issue, or insufficient_evidence), confidence, stop reason, public issues/evidence gaps, and extensions. Official reports with negotiated assessment include a local claim_coverage_notice even on pass; non-pass reports may also include explanation and step_explanations. These do not change verdict/confidence or fabricate gaps; see interpretation and limits.
CaptureStatus	Completeness for file snapshot/diff, logs, sensitive scan, and traces. Each component is complete, partial, failed, or skipped.

Private Rubrics, prompts, model settings, and Core records are not part of these objects. Runtime Evidence v1 is hash-only; explicitly negotiated v2 may carry a bounded, scanned completed Agent output. Both formats are defined in the Runtime Evidence contract.

Error fields

support_code: str | None is an optional opaque support category from exactly one validated X-KUMA-Support-Code response header (SB000–SB003). Official busy errors display it alongside a valid response request_id; missing/invalid headers and non-busy errors leave it None. It is not inferred from error text, used for retry decisions or added to the JSON wire. See error display.

Catch KumaError for normal SDK failures. str(exc) is a safe user-facing message. Program logic should use exc.code, exc.retryable, and exc.request_id; exc.details is a bounded public mapping and should be logged only through an application-approved allowlist.

request_id: str | None carries an actual X-Request-ID response header only when it matches 32 lowercase hexadecimal characters. Missing, malformed, or duplicate headers yield None; the SDK never generates a replacement or reads IDs from the JSON body. For async terminal failures it identifies that poll response, not the operation/start request. The separate kreq_… client_request_id remains the local recovery identity. A valid header can be server-echoed rather than server-generated; it is not an authentication token.

The same ID is retained for decode/size/status failures and rejected operation start/poll/result schemas, using only the response being validated. No-response network failures and local persistence errors are not assigned a prior ID.

Remote error details use exact per-code schemas (HTTP failures and async failed operations share validation):

exc.code	Allowed exc.details	Validation
case_step_limit_exceeded	{"max_allowed_steps": 10}	Required non-boolean integer, 1–10.
unsupported_difficulty	{"supported_difficulties": ["D0", "D2"]}	1–5 unique values from D0–D4; server order is preserved, not required to be sorted.
strategy_capability_mismatch	{"missing_capabilities": ["file_change", "tool_call"]}	1–7 unique Evidence capabilities in canonical order: file_change, tool_call, command_result, test_result, state_transition, artifact_snapshot, agent_response_claim.

For example, on unsupported_difficulty, show the validated exc.details.get("supported_difficulties", []) so the caller can choose a supported value. Historical omission of difficulty/capability details yields {}. Present malformed, empty, unknown-key or out-of-range details for these codes raise ProviderError(code="invalid_response"); an invalid async response does not clear pending recovery state. The Case-limit contract is unchanged.

invalid_request additionally accepts optional details.fields: 1–16 closed records with required field and reason. Fields are the static public serializer paths listed in public error diagnostics, not submitted values. Reasons are required, invalid_type, blank, min_value, max_value, max_length, invalid_choice, or invalid. Optional expected_type, minimum, maximum, and allowed_values must match the frozen per-field constraints. The SDK includes these safe constraints in its English correction message.

For official Judge only, internal model_invalid_result / model_invalid_response failures (including older servers) are presented as ServiceBusyError with code service_busy, message Service is busy. Please try again later., and no details. The original retryable and response-header request_id remain available. No automatic retry, new task, or fabricated report is created; committed Run history is retained. Input, authentication, permission and quota errors are not converted. Case generation keeps the following existing policy.

model_invalid_result (and historical model_invalid_response) accepts only optional {"reason": "invalid_structure"} with reason from invalid_structure, invalid_type, out_of_bounds, or invalid_format. Its message explicitly describes a service-generated result failure, not a request to fix user input. Missing details stay empty: historical failures do not acquire guessed explanations. Only these two model codes and invalid_request also accept the legacy exact empty object details: {} as absence; null/lists/unknown nonempty details remain invalid.

Other HTTP details remain discarded; unknown async detail shapes remain rejected. Remote free-form messages, private paths and raw model responses are never shown. Details do not change retryability, pending identity, billing or automatic retry policy. See the unreleased error change notes.