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: Protocol

The 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: BaseModel

The 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: BaseModel

A 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: BaseModel

One 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: BaseModel

A 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, or failed.

  • 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: BaseModel

The 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: object

A 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: BaseModel

A sanitized tool call in a provider response.

Parameters:
  • tool_id (str) – Tool identifier.

  • status (str, optional) – ok, blocked, or error.

  • 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: BaseModel

One 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 prompt is 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 FakeAgentProvider in 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-AUTHORITY findings.

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-PRIVATE findings. 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:
Returns:

ContractValidation – Errors, warnings, and counts.