brushline.integrations.capabilities
The six bounded agent capabilities, the tool allowlist, the built-in validators, the offline fake provider, the sanitized outcome record, and the private-data and authority scans.
Agent capability registry and offline capability harness.
A capability is a prompt id, a tool allowlist, a validator, and a bounded retry budget. The agent cannot compute an authoritative number, coefficient, geometry, or validation result; the validator decides. A failed validator stops the capability instead of retrying with a new assumption.
The harness is offline. It calls a provider protocol, and the committed test provider is a fake. No live model provider is imported, configured, or contacted.
- class brushline.integrations.capabilities.AgentProvider(*args, **kwargs)[source]
Bases:
ProtocolThe provider protocol used by the offline harness.
- complete(request: AgentRequest) AgentResponse[source]
Return one response for a bounded request.
- Parameters:
request (AgentRequest) – Capability request.
- Returns:
AgentResponse – Outcome and tool calls.
- class brushline.integrations.capabilities.AgentRequest(*, capability_id: Annotated[str, MinLen(min_length=1)], prompt_id: Annotated[str, MinLen(min_length=1)], prompt_version: Annotated[str, MinLen(min_length=1)], prompt: Annotated[str, MinLen(min_length=1)], input_sha256: Annotated[str, _PydanticGeneralMetadata(pattern='^[0-9a-f]{64}$')], tool_allowlist: Annotated[list[str], MinLen(min_length=1)])[source]
Bases:
BaseModelThe bounded request sent to a provider.
- Parameters:
capability_id (str) – Capability id.
prompt_id (str) – Versioned prompt id.
prompt_version (str) – Prompt version.
prompt (str) – Sanitized prompt text.
input_sha256 (str) – SHA-256 of the canonical capability input.
tool_allowlist (list of str) – Tools the provider may use.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.integrations.capabilities.AgentResponse(*, outcome: dict[str, object]=<factory>, tool_calls: list[ToolCall] = <factory>)[source]
Bases:
BaseModelA provider response with an outcome and sanitized tool calls.
- Parameters:
outcome (dict of str to object) – Capability outcome for the validator.
tool_calls (list of ToolCall, optional) – Tool calls that produced the outcome.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.integrations.capabilities.CapabilityDefinition(*, id: Annotated[str, MinLen(min_length=1)], prompt_id: Annotated[str, MinLen(min_length=1)], prompt_version: Annotated[str, MinLen(min_length=1)], description: Annotated[str, MinLen(min_length=1)], tool_allowlist: Annotated[list[str], MinLen(min_length=1)], validator_id: Annotated[str, MinLen(min_length=1)], retry_budget: Annotated[int, Ge(ge=0), Le(le=2)] = 1)[source]
Bases:
BaseModelOne agent-facing build capability.
- Parameters:
id (str) – Capability id, one of the six build steps.
prompt_id (str) – Versioned prompt identifier.
prompt_version (str) – Prompt version label.
description (str) – What the capability does and does not do.
tool_allowlist (list of str) – Tools the capability may call.
validator_id (str) – Built-in outcome validator id.
retry_budget (int, optional) – Maximum provider retries from 0 to 2. Defaults to
1.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.integrations.capabilities.CapabilityOutcome(*, schema_version: ~typing.Literal['brushline.capability-outcome.v1'] = 'brushline.capability-outcome.v1', capability_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], prompt_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], input_sha256: ~typing.Annotated[str, _PydanticGeneralMetadata(pattern='^[0-9a-f]{64}$')], outcome_sha256: str = '', validator_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], validator_result: dict[str, object], tool_calls: list[~brushline.integrations.capabilities.ToolCall] = <factory>, final_state: str, attempts: ~typing.Annotated[int, ~annotated_types.Ge(ge=1)], retry_budget: ~typing.Annotated[int, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=2)], stopped_reason: str = '', created_utc: ~datetime.datetime)[source]
Bases:
BaseModelA sanitized record of one capability run.
- Parameters:
schema_version ({"brushline.capability-outcome.v1"}) – Record schema version.
capability_id (str) – Capability id.
prompt_id (str) – Prompt id.
input_sha256 (str) – SHA-256 of the canonical input.
outcome_sha256 (str) – SHA-256 of the provider outcome, or an empty string before a response.
validator_id (str) – Validator id.
validator_result (dict of str to object) – Shared contract-validation report.
tool_calls (list of ToolCall) – Sanitized tool calls.
final_state (str) –
succeeded,stopped, orfailed.attempts (int) – Provider attempts used.
retry_budget (int) – Capability retry budget.
stopped_reason (str) – Why a stopped or failed run ended.
created_utc (datetime) – Timezone-aware creation time.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.integrations.capabilities.CapabilityRegistry(*, schema_version: Literal['brushline.capabilities.v1'] = 'brushline.capabilities.v1', capabilities: list[CapabilityDefinition] = <factory>)[source]
Bases:
BaseModelThe versioned capability registry.
- Parameters:
schema_version ({"brushline.capabilities.v1"}) – Registry schema version.
capabilities (list of CapabilityDefinition) – Capability definitions.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.integrations.capabilities.FakeAgentProvider(responses: Mapping[str, Sequence[AgentResponse | Exception]])[source]
Bases:
objectA scripted provider for offline tests.
- Parameters:
responses (mapping of str to sequence of AgentResponse or Exception) – One scripted sequence per capability. Each call consumes the next item. A sequence that runs out raises
KeyError.
- property calls: int
Return the number of provider calls.
- Returns:
int – Call count.
- complete(request: AgentRequest) AgentResponse[source]
Return the next scripted response.
- Parameters:
request (AgentRequest) – Capability request.
- Returns:
AgentResponse – Scripted response.
- Raises:
KeyError – When the capability has no scripted response left.
- class brushline.integrations.capabilities.ToolCall(*, tool_id: Annotated[str, MinLen(min_length=1)], status: str = 'ok', summary: str = '')[source]
Bases:
BaseModelA sanitized tool call in a provider response.
- Parameters:
tool_id (str) – Tool identifier.
status (str, optional) –
ok,blocked, orerror.summary (str, optional) – Short non-private summary.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.integrations.capabilities.ToolDefinition(*, id: Annotated[str, MinLen(min_length=1)], description: Annotated[str, MinLen(min_length=1)], mutating: bool = False, private_access: bool = False, approval_required: bool = False)[source]
Bases:
BaseModelOne tool that a capability may use.
- Parameters:
id (str) – Stable tool identifier.
description (str) – What the tool does.
mutating (bool, optional) – Whether the tool writes an artifact. Defaults to
False.private_access (bool, optional) – Whether the tool reads private rows. Defaults to
False.approval_required (bool, optional) – Whether the tool needs an owner approval. Defaults to
False.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.integrations.capabilities.build_agent_request(capability: CapabilityDefinition, capability_input: Mapping[str, object], *, prompt: str | None = None) AgentRequest[source]
Build a bounded request without calling a provider.
- Parameters:
capability (CapabilityDefinition) – Capability to invoke.
capability_input (mapping of str to object) – Non-private input. It is hashed and included in the prompt when
promptis omitted.prompt (str, optional) – Prompt override. It is still scanned by
run_capability().
- Returns:
AgentRequest – Request with a stable input hash and the capability tool allowlist.
- brushline.integrations.capabilities.default_capability_registry() CapabilityRegistry[source]
Return the six-capability registry.
- Returns:
CapabilityRegistry – Default registry.
- brushline.integrations.capabilities.run_capability(capability: CapabilityDefinition, capability_input: Mapping[str, object], provider: AgentProvider, *, prompt: str | None = None, created_utc: datetime | None = None) CapabilityOutcome[source]
Run one capability with a validator, a retry budget, and sanitized evidence.
A provider error may retry up to the capability budget. A validator failure, a private-data marker, an unknown tool, or an authoritative field stops immediately and is recorded.
- Parameters:
capability (CapabilityDefinition) – Capability definition.
capability_input (mapping of str to object) – Non-private input.
provider (AgentProvider) – Provider, normally a
FakeAgentProviderin tests.prompt (str, optional) – Prompt override.
created_utc (datetime, optional) – Creation time. Defaults to the current UTC time.
- Returns:
CapabilityOutcome – Sanitized record with the validator result and final state.
- brushline.integrations.capabilities.scan_for_authority_keys(value: object) tuple[str, ...][source]
Scan an outcome for keys that claim an authoritative agent result.
- Parameters:
value (object) – Outcome value, usually a mapping.
- Returns:
tuple of str –
AGENT-AUTHORITYfindings.
- brushline.integrations.capabilities.scan_for_private_data(text: str) tuple[str, ...][source]
Scan a prompt or outcome for an explicit private-data marker.
- Parameters:
text (str) – Text to scan.
- Returns:
tuple of str –
AGENT-PRIVATEfindings. The marker value is never echoed.
- brushline.integrations.capabilities.validate_capability_outcome(outcome: CapabilityOutcome) ContractValidation[source]
Validate the sanitized outcome record.
- Parameters:
outcome (CapabilityOutcome) – Record to validate.
- Returns:
ContractValidation – Errors, warnings, and counts.
- brushline.integrations.capabilities.validate_capability_registry(registry: CapabilityRegistry, tools: Sequence[ToolDefinition] = (ToolDefinition(id='aoi.read', description='Read an AOI GeoJSON in the approved workspace.', mutating=False, private_access=False, approval_required=False), ToolDefinition(id='aoi.validate', description='Validate an AOI through the shared validator.', mutating=False, private_access=False, approval_required=False), ToolDefinition(id='catalogue.read', description='Read public source and connector metadata; never private rows.', mutating=False, private_access=False, approval_required=False), ToolDefinition(id='fetch.plan', description='Build the plan-only fetch preview.', mutating=False, private_access=False, approval_required=False), ToolDefinition(id='instance.seed_state', description='Validate and write the seed vegetation-state artifact.', mutating=True, private_access=False, approval_required=False), ToolDefinition(id='state.validate', description='Validate a state contract.', mutating=False, private_access=False, approval_required=False), ToolDefinition(id='instance.compile_dataset', description='Compile the fixture into a validated dataset.', mutating=True, private_access=False, approval_required=False), ToolDefinition(id='dataset.validate', description='Validate a compiled dataset.', mutating=False, private_access=False, approval_required=False), ToolDefinition(id='scenario.read', description='Read scenario and targets YAML.', mutating=False, private_access=False, approval_required=False), ToolDefinition(id='scenario.validate', description='Validate scenario and targets YAML.', mutating=False, private_access=False, approval_required=False), ToolDefinition(id='demo.build', description='Write the demo manifest artifact.', mutating=True, private_access=False, approval_required=False), ToolDefinition(id='demo.validate', description='Validate the demo manifest.', mutating=False, private_access=False, approval_required=False))) ContractValidation[source]
Validate capabilities, prompts, tools, validators, and retry budgets.
- Parameters:
registry (CapabilityRegistry) – Registry to validate.
tools (sequence of ToolDefinition, optional) – Known tool registry.
- Returns:
ContractValidation – Errors, warnings, and counts.