topos.mcp.schemas¶

Pydantic schemas for the Topos MCP server.

Input models validate tool arguments; return models give FastMCP the outputSchema it emits to clients when structured output is enabled.

class topos.mcp.schemas.LatticeElement(*values)[source]

Bases: StrEnum

String-valued mirror of EvaluationValue for MCP wire format.

These are the 8 elements of the free Heyting algebra H(G_qual) on the three generators SIMPLE, COMPOSABLE, SECURE. Mapped to the Medal Podium: IDEAL = 🥇 GOLD, SLOP = ❌ No Medal.

SLOP = 'SLOP'

SIMPLE = 'SIMPLE'

COMPOSABLE = 'COMPOSABLE'

SECURE = 'SECURE'

SIMPLE_COMPOSABLE = 'SIMPLE_COMPOSABLE'

SIMPLE_SECURE = 'SIMPLE_SECURE'

COMPOSABLE_SECURE = 'COMPOSABLE_SECURE'

IDEAL = 'IDEAL'

class topos.mcp.schemas.AssessmentStatus(*values)[source]

Bases: StrEnum

Outcome of comparing a proposed change to the baseline.

IMPROVEMENT = 'IMPROVEMENT'

IMPROVEMENT_SCORE = 'IMPROVEMENT_SCORE'

LATERAL_MOVE = 'LATERAL_MOVE'

REGRESSION = 'REGRESSION'

REGRESSION_SCORE = 'REGRESSION_SCORE'

SUSPICIOUS_NO_STRUCTURAL_CHANGE = 'SUSPICIOUS_NO_STRUCTURAL_CHANGE'

class topos.mcp.schemas.PrioritySource(*values)[source]

Bases: StrEnum

How the MCP layer selected the scorer priority.

DEFAULT = 'default'

PREFERENCES = 'preferences'

EXPLICIT = 'explicit'

class topos.mcp.schemas.UserPreferencesInput(*, ranking, target=None)[source]

Bases: _StrictModel

A strict total order on the three quality generators.

Stronger than priority (which only upweights one generator): this is a full ranking that induces a total order on the 8-element lattice Ω. Agents use the induced order to pick a targeted relaxation walk — by convention 🥇 GOLD (IDEAL) is treated as infeasible and the default target becomes the meet of the top-two ranked generators (the 🥈 SILVER “ideal intersection”, e.g. SIMPLE_SECURE).

Example

ranking=["secure", "simple", "composable"] ⟹ default target SIMPLE_SECURE; walk descends through it down toward SLOP.

ranking

target

to_preferences()[source]: Convert into the domain-layer UserPreferences.

to_priority()[source]: Use the top-ranked generator as the scorer priority.

model_config = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

topos.mcp.schemas.resolve_priority(preferences)[source]: Resolve MCP preference input to the legacy scorer priority.

class topos.mcp.schemas.EvaluateCodeInput(*, code, language='python', preferences=None, verbose=False, allow=<factory>)[source]

Bases: _StrictModel

Arguments for topos_evaluate_code.

code

language

preferences

verbose

allow

model_config = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.EvaluateFileInput(*, filepath, gitnexus_dir=None, preferences=None, include_security_findings=True, allow=<factory>, verbose=False)[source]

Bases: _StrictModel

Arguments for topos_evaluate_file.

filepath

gitnexus_dir

preferences

include_security_findings

allow

verbose

model_config = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.EvaluateProjectInput(*, path, preferences=None, gitnexus_dir=None, limit=25, offset=0, verbose=False, include_security_findings=False, allow=<factory>)[source]

Bases: _StrictModel

Arguments for topos_evaluate_project.

path

preferences

gitnexus_dir

limit

offset

verbose

include_security_findings

allow

model_config = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.CompareCodeInput(*, source_code, target_code, language='python')[source]

Bases: _StrictModel

Arguments for topos_compare_code.

source_code

target_code

language

model_config = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.CompareFilesInput(*, source, target)[source]

Bases: _StrictModel

Arguments for topos_compare_files.

source

target

model_config = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.AssessImprovementInput(*, proposed_code=None, proposed_filepath=None, filepath=None, current_code=None, language='python', preferences=None, gitnexus_dir=None, include_security_findings=True, allow=<factory>)[source]

Bases: _StrictModel

Arguments for topos_assess_improvement.

Provide EITHER filepath (preferred — scores the COMPOSABLE generator against the cached ModuleDependencyGraph) OR current_code (AST + CFG + CPG only; COMPOSABLE unreachable).

proposed_code

proposed_filepath

filepath

current_code

language

preferences

gitnexus_dir

include_security_findings

allow

validate_inputs()[source]

model_config = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.InspectCodeInput(*, code=None, filepath=None, language='python', preferences=None, top_n_functions=10, verbose=False, allow=<factory>)[source]

Bases: _StrictModel

Arguments for topos_inspect_code.

code

filepath

language

preferences

top_n_functions

verbose

allow

validate_source()[source]

model_config = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.CalculateCoverageInput(*, put_files, test_files, language='python', k=3, include_unknown=False, coverage_threshold=0.5)[source]

Bases: _StrictModel

Arguments for topos_calculate_coverage.

put_files

test_files

language

k

include_unknown

coverage_threshold

model_config = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.PreferenceWalkInput(*, ranking, current=None, target=None)[source]

Bases: _StrictModel

Arguments for topos_preference_walk.

Convert a strict total order on the three generators into a concrete relaxation walk on Ω — the sequence of verdicts an agent should aim for, in descending order of preference.

ranking

current

target

model_config = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.WalkStep(*, verdict, preference_score, generators_satisfied=<factory>)[source]

Bases: BaseModel

One verdict on the relaxation walk.

Annotated with the satisfied-generator set so an agent can see at a glance what changing to this verdict requires — e.g. “this step adds COMPOSABLE” or “this step drops SECURE”.

verdict

preference_score

generators_satisfied

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.PreferenceWalkResult(*, ranking, aspirational_target, fallback_target, current=None, next_step=None, progress, walk=<factory>, induced_order=<factory>, warnings=<factory>, error=None)[source]

Bases: BaseModel

Result of topos_preference_walk — the agent’s concrete walk.

The walk lets an agent plan a refactor without re-running an evaluation: it converts the ranking into an explicit list of “aim-for” goals, each labelled with what generators it commits the code to.

ranking

aspirational_target

fallback_target

current

next_step

progress

walk

induced_order

warnings

error

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.PreferenceWalk(*, ranking, target, fallback_target, walk=<factory>, next_step=None, progress)[source]

Bases: BaseModel

Targeted relaxation walk derived from a user preference ranking.

Two-stage strategy:

Aim for 🥇 GOLD (target) — try to beat the policy thresholds for all three generators.
Divert to the 🥈 SILVER “ideal intersection” (fallback_target) when 🥇 GOLD plateaus — the meet of the top-two ranked generators per the preference ordering.

Beyond the fallback the walk continues down through 🥉 BRONZE atoms toward ❌ SLOP, in descending preference order.

ranking

target

fallback_target

walk

next_step

progress

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.PillarResult(*, achieved, score)[source]

Bases: BaseModel

Lean per-generator summary (achieved + score).

The full per-metric detail and interpretation strings live once in the parent’s flat raw_metrics / interpretation maps (namespaced by representation prefix: cfg./ast. -> simple, mdg. -> composable, cpg. -> secure, pdg. -> unprefixed structural). They are NOT duplicated here.

achieved

score

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.SecurityFinding(*, kind, line, snippet, callee=None, source=None, sink=None)[source]

Bases: BaseModel

Actionable SECURE diagnostic for an agent.

kind

line

snippet

callee

source

sink

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.AcknowledgedRisk(*, callee=None, kind, line, snippet, reason, scope='**')[source]

Bases: BaseModel

A disclosed security finding acknowledged by project config or input.

callee

kind

line

snippet

reason

scope

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.FunctionEntry(*, name, line, complexity)[source]

Bases: BaseModel

Function-level complexity diagnostic.

name

line

complexity

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.Suggestion(*, pillar, metric=None, severity, message)[source]

Bases: BaseModel

One actionable, refactor-focused next step.

Wire mirror of topos.evaluation.suggestions.Suggestion — the pure engine emits the frozen dataclass; this is its Pydantic shape so the same suggestions reach MCP agents that the CLI already shows.

pillar

metric

severity

message

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.AgentContract(*, next_tool=None, next_actions=<factory>, blocked_by=<factory>, verification_gates=<factory>, risk_flags=<factory>)[source]

Bases: BaseModel

Compact loop-control packet for agentic harnesses.

next_tool

next_actions

blocked_by

verification_gates

risk_flags

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.EvaluationResult(*, is_parseable, lattice_element, lattice_symbol, lattice_description, dimensions, scores, pillars=<factory>, priority, priority_source=PrioritySource.DEFAULT, guidance, coupling_available, raw_metrics=<factory>, interpretation=<factory>, warnings=<factory>, agent_contract=None, security_findings=<factory>, acknowledged_risks=<factory>, raw_lattice_element=None, adjusted_lattice_element=None, secure_raw=None, secure_adjusted=None, grade_capped=False, suggestions=<factory>, preference_walk=None, error=None)[source]

Bases: BaseModel

Result of a single-unit evaluation on the Medal Podium.

is_parseable

lattice_element

lattice_symbol

lattice_description

dimensions

scores

pillars

priority

priority_source

guidance

coupling_available

raw_metrics

interpretation

warnings

agent_contract

security_findings

acknowledged_risks

raw_lattice_element

adjusted_lattice_element

secure_raw

secure_adjusted

grade_capped

suggestions

preference_walk

error

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.ProjectFileEntry(*, filepath, lattice_element, scores, pillars=<factory>, raw_metrics=<factory>, warnings=<factory>, security_findings=<factory>, acknowledged_risks=<factory>, raw_lattice_element=None, adjusted_lattice_element=None, secure_raw=None, secure_adjusted=None, grade_capped=False, is_parseable=True)[source]

Bases: BaseModel

filepath

lattice_element

scores

pillars

raw_metrics

warnings

security_findings

acknowledged_risks

raw_lattice_element

adjusted_lattice_element

secure_raw

secure_adjusted

grade_capped

is_parseable

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.ProjectEvaluationResult(*, root, file_count, parse_failures, rolled_up_dimensions, rolled_up_scores, aggregate_floor_verdict, aggregate_explanation, worst_file_verdict=None, worst_files=<factory>, guidance='', priority, priority_source=PrioritySource.DEFAULT, coupling_available, warnings=<factory>, agent_contract=None, count, offset, total, has_more, next_offset, files, verbose=False, error=None)[source]

Bases: BaseModel

Result of a directory-wide evaluation.

root

file_count

parse_failures

rolled_up_dimensions

rolled_up_scores

aggregate_floor_verdict

aggregate_explanation

worst_file_verdict

worst_files

guidance

priority

priority_source

coupling_available

warnings

agent_contract

count

offset

total

has_more

next_offset

files

verbose

error

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.ComparisonResult(*, raw_distance, normalized_distance, similarity, operations, source_valid, target_valid, warnings=<factory>, error=None)[source]

Bases: BaseModel

Result of AST-distance comparison between two programs.

raw_distance

normalized_distance

similarity

operations

source_valid

target_valid

warnings

error

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.AssessmentResult(*, status, priority, priority_source=PrioritySource.DEFAULT, current, proposed, score_deltas, metric_deltas=<factory>, structural_distance=None, similarity=None, coupling_available_for_proposed, warnings=<factory>, agent_contract=None, suspicion_reason=None, regression_diff=None, error=None)[source]

Bases: BaseModel

Result of topos_assess_improvement.

status

priority

priority_source

current

proposed

score_deltas

metric_deltas

structural_distance

similarity

coupling_available_for_proposed

warnings

agent_contract

suspicion_reason

regression_diff

error

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.InspectionResult(*, evaluation, functions=<factory>, function_entries=<factory>, total_functions, entropy_compression_ratio=None, entropy_interpretation=None, error=None)[source]

Bases: BaseModel

Result of topos_inspect_code — full breakdown.

evaluation

functions

function_entries

total_functions

entropy_compression_ratio

entropy_interpretation

error

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.TopologicalCoverageResult(*, unavailable=False, reason=None, distance=None, coverage_score=None, tested_functions=<factory>, untested_functions=<factory>, put_node_count=None, test_node_count=None, scoped_node_count=None, achieved=None, threshold=None, interpretation=<factory>)[source]

Bases: BaseModel

ECT-based topological semantic coverage (optional extra).

unavailable

reason

distance

coverage_score

tested_functions

untested_functions

put_node_count

test_node_count

scoped_node_count

achieved

threshold

interpretation

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class topos.mcp.schemas.CoverageResult(*, mean_declaration_coverage, best_declaration_recall, declaration_locations, stmt_recall, expr_recall, mean_test_precision, f2_score, declaration_path_recall_kgram, uncovered_declarations, put_declaration_count, test_declaration_count, topological_coverage=None, warnings=<factory>, error=None)[source]

Bases: BaseModel

Structural test coverage report (v2).

mean_declaration_coverage

best_declaration_recall

declaration_locations

stmt_recall

expr_recall

mean_test_precision

f2_score

declaration_path_recall_kgram

uncovered_declarations

put_declaration_count

test_declaration_count

topological_coverage

warnings

error

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].