mechaharness.core.access

Cost units and deny-by-default tool grants.

Ability is a five-step scale; higher ability costs more. Grants are open identity: a class hierarchy with wire form namespace:name (for example core:fs.read, acme:widget). Unknown namespaced keys round-trip; bare names are rejected.

class mechaharness.core.access.Ability(*values)

Bases: str, Enum

How capable a completer or tool is at a given kind of work.

ADVANCED = 'advanced'

BASIC = 'basic'

INTERMEDIATE = 'intermediate'

PROFICIENT = 'proficient'

SIMPLE = 'simple'

property rank: int

property units: int

1, 2, 4, 8, 16.

Type:

Cost units

class mechaharness.core.access.AccessControl

Bases: ABC

Whether a tool may run. Deny-by-default unless a grant covers it.

abstractmethod allows(required: Sequence[object], *, tool_name: str = '', agent_id: str = '', run_id: str = '', parent_agent_id: str | None = None) → bool

Return True if every required grant is held.

class mechaharness.core.access.AccessPolicy(*, grants: list[str] = <factory>)

Bases: BaseModel

Deny-by-default grant list for a harness.

allows(required: Sequence[object]) → bool

grants: list[str]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mechaharness.core.access.Capability(*, kind: CapabilityKind, level: Ability)

Bases: BaseModel

kind: CapabilityKind

level: Ability

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mechaharness.core.access.CapabilityKind(*values)

Bases: str, Enum

Kinds of work a completer can perform (aligned with model skills).

CODE = 'code'

REASONING = 'reasoning'

TOOL_USE = 'tool_use'

class mechaharness.core.access.CapabilityProfile(*, capabilities: list[Capability] = <factory>)

Bases: BaseModel

Declared skills of a completer. Cost is the sum of each capability’s units.

capabilities: list[Capability]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

units() → int

class mechaharness.core.access.CompoundPolicy(*, policies: list[AccessPolicy] = <factory>)

Bases: BaseModel

Union of AccessPolicy layers (still deny-by-default).

Compose reusable grant sets (e.g. read-only + media) without rewriting lists. Overlaps are idempotent — there is no deny grant, only allow-list membership. Not related to JudgementPolicy.

allows(required: Sequence[object]) → bool

flatten() → AccessPolicy

Single AccessPolicy with the unioned grant list.

property grants: list[str]

Flattened unique grants in first-seen order across policies.

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod of(*policies: AccessPolicy) → CompoundPolicy

Build from one or more access policies.

policies: list[AccessPolicy]

class mechaharness.core.access.CoreGrant

Bases: Grant

Built-in MechaHarness grants (core:*). Conveniences, not a closed set.

namespace: ClassVar[str] = 'core'

class mechaharness.core.access.CostAccountant

Bases: ABC

Price one inference call or tool invocation and keep a ledger.

abstractmethod price_inference(name: str, profile: CapabilityProfile, *, agent_id: str = '', run_id: str = '', parent_agent_id: str | None = None, usage: Usage | None = None) → CostEntry

Units for one completer call.

abstractmethod price_tool(name: str, ability: Ability, *, agent_id: str = '', run_id: str = '', parent_agent_id: str | None = None) → CostEntry

Units for one successful tool run.

abstractmethod report() → CostReport

Accumulated ledger for this accountant instance.

class mechaharness.core.access.CostEntry(*, kind: str, name: str, units: int, capabilities: list[Capability] = <factory>, prompt_tokens: int | None = None, completion_tokens: int | None = None, total_tokens: int | None = None)

Bases: BaseModel

capabilities: list[Capability]

completion_tokens: int | None

kind: str

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

prompt_tokens: int | None

total_tokens: int | None

units: int

class mechaharness.core.access.CostReport(*, units: int = 0, entries: list[CostEntry] = <factory>, prompt_tokens: int = 0, completion_tokens: int = 0, total_tokens: int = 0)

Bases: BaseModel

add(entry: CostEntry) → None

completion_tokens: int

entries: list[CostEntry]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

prompt_tokens: int

total_tokens: int

units: int

class mechaharness.core.access.FsRead

Bases: CoreGrant

name: ClassVar[str] = 'fs.read'

class mechaharness.core.access.FsWrite

Bases: CoreGrant

name: ClassVar[str] = 'fs.write'

class mechaharness.core.access.Grant

Bases: object

Namespaced grant identity.

Subclass to add grants. The wire form is namespace:name (for example core:fs.read). Intermediate classes set namespace; leaves set name.

classmethod key() → str

name: ClassVar[str] = ''

namespace: ClassVar[str] = ''

classmethod parse(value: str) → type[Grant]

Return the class registered for namespace:name.

class mechaharness.core.access.InMemoryAccessControl(event_log: EventLog | None = None, grants: Sequence[object] | None = None, policy: AccessPolicy | CompoundPolicy | None = None)

Bases: AccessControl

Deny-by-default grant list; records and emits every check.

__init__(event_log: EventLog | None = None, grants: Sequence[object] | None = None, policy: AccessPolicy | CompoundPolicy | None = None) → None

allows(required: Sequence[object], *, tool_name: str = '', agent_id: str = '', run_id: str = '', parent_agent_id: str | None = None) → bool

Return True if every required grant is held.

checks: list[dict[str, Any]]

property grants: list[str]

class mechaharness.core.access.InMemoryCostAccountant(event_log: EventLog | None = None)

Bases: CostAccountant

Prices from the capability profile and tool ability; emits core:cost.

__init__(event_log: EventLog | None = None) → None

price_inference(name: str, profile: CapabilityProfile, *, agent_id: str = '', run_id: str = '', parent_agent_id: str | None = None, usage: Usage | None = None) → CostEntry

Units for one completer call.

price_tool(name: str, ability: Ability, *, agent_id: str = '', run_id: str = '', parent_agent_id: str | None = None) → CostEntry

Units for one successful tool run.

report() → CostReport

Accumulated ledger for this accountant instance.

class mechaharness.core.access.MediaAudio

Bases: CoreGrant

name: ClassVar[str] = 'media.audio'

class mechaharness.core.access.MediaImage

Bases: CoreGrant

name: ClassVar[str] = 'media.image'

class mechaharness.core.access.MediaVideo

Bases: CoreGrant

name: ClassVar[str] = 'media.video'

class mechaharness.core.access.NetHttp

Bases: CoreGrant

name: ClassVar[str] = 'net.http'

mechaharness.core.access.default_capability_profile() → CapabilityProfile

Pass-through / unknown completer: simple reasoning only.

mechaharness.core.access.grant_key(value: object) → str

Normalize a class or namespace:name string to the wire key.

mechaharness.core.access.inference_cost_entry(name: str, profile: CapabilityProfile, *, usage: Usage | None = None) → CostEntry

mechaharness.core.access.tool_cost_entry(name: str, ability: Ability) → CostEntry