aeat.agent._skill_metadata module

Structured applies_when selection predicate for operator harness skills.

Each shipped skill’s SKILL.md frontmatter carries a machine-queryable applies_when predicate that a router, an MCP guided prompt, or a live-eval scenario can evaluate deterministically, instead of parsing the selection rule out of the human description prose. This module defines that predicate schema and the frontmatter parser that produces it.

The predicate is expressed over three orthogonal axes:

  • profile_facts - conjunctive predicates over TaxpayerProfile fact names. A fact name that is not a real field of the model fails validation, so a typo cannot ship; enum-valued facts additionally validate their expected values against the enum member set.

  • workflow_phase - the point in the operator lifecycle spine a cross-cutting helper skill serves (ledger upkeep, classification, export, reconciliation, …).

  • temporal_trigger - a life-situation (WHEN) overlay keyed off deadline or lifecycle state (backlog overdue, quarter boundary, annual window, activity start/end).

A skill that is a cross-cutting helper invoked by other skills, with no profile, phase, or temporal gate, declares always: true.

The fact-name and enum-value registries are derived from the live TaxpayerProfile model at import, never hand-maintained, so the predicate vocabulary tracks the profile model automatically.

exception SkillMetadataError[source]

Bases: ValueError

Raised when a skill’s frontmatter or applies_when predicate is invalid.

class ProfileFactMatch(*values)[source]

Bases: StrEnum

How a single TaxpayerProfile fact is matched by a predicate.

PRESENT

The fact is declared (not None and, for a collection, non-empty).

ABSENT

The fact is undeclared (None or an empty collection).

EQUALS

A scalar fact equals one of the predicate’s values (in-set membership).

CONTAINS

A collection fact intersects the predicate’s values (non-empty overlap).

IS_TRUE

A boolean fact is True.

IS_FALSE

A boolean fact is False.

class WorkflowPhase(*values)[source]

Bases: StrEnum

The operator-lifecycle point a cross-cutting helper skill serves.

ONBOARDING
LEDGER_UPKEEP
CLASSIFICATION
MODELO_PREPARATION
EXPORT
RECONCILIATION
class TemporalTrigger(*values)[source]

Bases: StrEnum

A life-situation (WHEN) overlay keyed off deadline or lifecycle state.

BACKLOG_OVERDUE
QUARTER_BOUNDARY
ANNUAL_WINDOW
AMENDMENT_REQUESTED
ACTIVITY_START
ACTIVITY_END
class MatchMode(*values)[source]

Bases: StrEnum

How the profile_facts conjuncts combine into one profile predicate.

ALL

Every profile_facts predicate must hold (logical AND).

ANY

At least one profile_facts predicate must hold (logical OR).

profile_fact_names()[source]

Return every valid TaxpayerProfile fact name a predicate may cite.

Return type:

frozenset[str]

class ProfileFactPredicate(**data)[source]

Bases: BaseModel

A single conjunct: a TaxpayerProfile fact matched a stated way.

Parameters:
fact: str
match: ProfileFactMatch
values: tuple[str, ...]
class SkillAppliesWhen(**data)[source]

Bases: BaseModel

The structured selection predicate lifted from a skill’s prose description.

Parameters:
profile_facts: tuple[ProfileFactPredicate, ...]
profile_match: MatchMode
workflow_phase: WorkflowPhase | None
temporal_trigger: TemporalTrigger | None
always: bool
class SkillMetadata(**data)[source]

Bases: BaseModel

The validated frontmatter of a shipped SKILL.md.

applies_when is optional at the load boundary: a skill whose predicate has not yet been lifted from prose still loads (with applies_when None), and a predicate that IS present is fully validated. Strict presence - the requirement that every shipped skill declare the field - is enforced by the coverage gate, not the load path, so the tree stays loadable while the lifts land.

Parameters:
name: str
description: str
applies_when: SkillAppliesWhen | None
parse_skill_frontmatter(text)[source]

Extract and YAML-parse the leading frontmatter block of a SKILL.md.

Return type:

Mapping[str, object]

Parameters:

text (str)

parse_skill_metadata(text)[source]

Parse and validate the full frontmatter of a SKILL.md document.

Return type:

SkillMetadata

Returns:

A SkillMetadata.

Parameters:

text (str)