Skip to content

Align Specs

Align Specs — mvp.align_specs

Cluster: Safety & Alignment | Type: component | MCP Tools: 35

Overview

Specification and checklist manager that converts a list of constraint strings into a structured Specification object with SpecClause entries, lightweight predicate checks, compliance scores, and an epsilon risk bound. Each constraint string becomes its own clause with an auto-generated name and predicate metadata, making the spec useful for rubric-style output validation, CSF gating context, and downstream review workflows. The extended MCP sub-package exposes 29 deterministic operations for managing, validating, and querying specifications remotely (including list_patterns, predicate_backends, list_templates, and get_template); none of these operations call an LLM.

Launch-readiness caveat

align_specs is a lightweight specification and checklist compliance layer, not a complete formal verification or regulated-domain assurance engine. Its natural-language parsing is heuristic: it handles simple required phrases, forbidden phrases, regex clauses, word-count bounds, and keyword-style checks, but unclear constraints can be interpreted too narrowly or too broadly. For healthcare, legal, finance, safety-critical engineering, or other regulated workflows, treat these templates as human-review checklists and audit aids. Do not use a passing compliance_score as proof of legal, clinical, financial, or safety compliance without independent domain review and, where needed, solver-backed verification via components such as formal_methods.

Predicate backend disclosure is explicit but not a certification. semantic_similarity may use semantic_similarity_fallback_jaccard when the semantic backend is unavailable, and z3 may surface z3_unavailable_fallback_false when z3-solver is absent. Such results are qualified-draft, not verified.

When to use:

  • Encoding system-level safety or functional constraints in a machine-readable form before formal verification
  • Checking outputs against explicit rubric items, required disclaimers, forbidden phrases, or simple structural constraints
  • Passing a structured spec into csf or formal_methods as context for stricter verification
  • Capturing epsilon-bounded risk requirements alongside domain and goal descriptions

Do not use as:

  • A standalone regulated-domain compliance decision
  • Evidence that a clinical, legal, financial, or safety-critical output is correct
  • A substitute for human-in-the-loop review or solver-backed verification on high-stakes workflows

Example:

from mvp.align_specs import AlignSpecsBlock, SpecInput

block = AlignSpecsBlock(name="specs")
result = block.infer(SpecInput(
    domain="robotics",
    goal_description="Pick and place object safely",
    constraints=["gripper force <= 10N", "no obstacle collision"],
    epsilon=0.05,
))
# result.value.clauses → [SpecClause(name="constraint_0", ...), ...]

Works well with: csf, formal_methods, align_artifacts

Public API

SpecClause(BaseModel)

A single predicate or constraint within a specification.

Field Type Default
name str required
description str required
predicate_str str ''

SpecInput(BaseModel)

Input for AlignSpecsBlock — describes the specification to produce.

Field Type Default
domain str required
goal_description str required
constraints list[str] Field(default_factory=list)
epsilon float 0.2

Specification(BaseModel)

A formal specification produced by AlignSpecsBlock.

Field Type Default
domain str required
goal_description str required
clauses list[SpecClause] required
epsilon float required
structured_predicates list[dict[str, Any]] Field(default_factory=list)
metadata dict[str, str] Field(default_factory=dict)
degraded bool False
degradation_reason str ''
completion_state Literal['verified', 'qualified-draft', 'blocked-escalated'] 'qualified-draft'
warning_card dict[str, Any] \| None None
evidence dict[str, Any] Field(default_factory=dict)

AlignSpecsBlock(AIBlock[SpecInput, Specification, None])

Converts a SpecInput into a structured Specification.

Field Type Default
name str 'align_specs'
resource_bounds ResourceBounds \| None None
usage ResourceUsage field(default_factory=ResourceUsage)
compliance_threshold float 1.0

Methods:

infer(data: SpecInput) -> Result[Specification]

verify_compliance(output_text: str, spec: Specification, threshold: float | None = None) -> Result[dict[str, Any]]

Check output text against a Specification's structured predicates.

MCPSpecsInput(BaseModel)

Field Type Default
op SpecsMCPOp required
spec_id str \| None None
spec_name str \| None None
domain str \| None None
goal_description str \| None None
constraints list[str] Field(default_factory=list)
epsilon float 0.2
clause_id str \| None None
predicate str \| None None
clause_type str \| None None
weight float 1.0
target_spec_id str \| None None
link_type str \| None None
domain_name str \| None None
domain_priors list[str] Field(default_factory=list)
version int \| None None
items list[dict[str, Any]] Field(default_factory=list)
content str \| None None
template_name str \| None None
upsert bool False
request_id str \| None None
task_id str \| None None
run_id str \| None None
query str \| None None
goal str \| None None
limit int 20
metadata dict[str, Any] Field(default_factory=dict)

MCPSpecsOutput(BaseModel)

Field Type Default
op str required
success bool required
spec_id str \| None None
spec dict[str, Any] \| None None
specs list[dict[str, Any]] Field(default_factory=list)
clause_id str \| None None
clause dict[str, Any] \| None None
clauses list[dict[str, Any]] Field(default_factory=list)
compliant bool False
compliance_score float 0.0
violations list[str] Field(default_factory=list)
versions list[dict[str, Any]] Field(default_factory=list)
domains list[dict[str, Any]] Field(default_factory=list)
links list[dict[str, Any]] Field(default_factory=list)
count int 0
stats dict[str, Any] Field(default_factory=dict)
message str ''
error str ''
degraded bool False
degradation_reason str ''
completion_state Literal['verified', 'qualified-draft', 'blocked-escalated'] 'qualified-draft'
warning_card dict[str, Any] \| None None
evidence dict[str, Any] Field(default_factory=dict)
request_id str \| None None
task_id str \| None None
run_id str \| None None
result_class ComplianceResultClass 'heuristic_only'
predicate_backend str 'unknown'

AlignSpecsMCPBlock(AIBlock[MCPSpecsInput, MCPSpecsOutput, dict])

Field Type Default
name str 'align_specs_mcp'
state dict \| None None
db_path str ':memory:'
resource_bounds ResourceBounds \| None None
usage ResourceUsage field(default_factory=ResourceUsage)

Methods:

infer(inp: MCPSpecsInput) -> Result[MCPSpecsOutput]

Functions

evaluate_predicate(predicate: dict[str, Any], text: str) -> bool

Evaluate a structured predicate against text.

weighted_compliance_score(text: str, clauses: list[dict[str, Any]]) -> float

Evaluate weighted compliance of text against clauses.

clauses_from_strings(constraints: list[str]) -> list[dict[str, Any]]

Convert plain-text constraint strings into structured clause dicts.

MCP Tools

Operation Source
create align_specs_mcp
validate align_specs_mcp
check_compliance align_specs_mcp
export align_specs_mcp
list align_specs_mcp
store_spec align_specs_mcp
get_spec align_specs_mcp
delete_spec align_specs_mcp
search_specs align_specs_mcp
create_clause align_specs_mcp
get_clause align_specs_mcp
update_clause align_specs_mcp
delete_clause align_specs_mcp
validate_compliance align_specs_mcp
check_goal align_specs_mcp
link_spec align_specs_mcp
get_linked align_specs_mcp
store_domain align_specs_mcp
list_domains align_specs_mcp
export_json align_specs_mcp
import_json align_specs_mcp
version_spec align_specs_mcp
get_version align_specs_mcp
stats align_specs_mcp
info align_specs_mcp
list_patterns align_specs_mcp
predicate_backends align_specs_mcp
list_templates align_specs_mcp
get_template align_specs_mcp
pass align_specs_mcp
fail align_specs_mcp
degraded align_specs_mcp
heuristic_only align_specs_mcp
expert_review_required align_specs_mcp
solver_review_required align_specs_mcp