Skip to content

Deep Understanding¶

mvp.deep_understanding — symbolic reasoning substrate for G6.

Cluster: ML & Optimisation | Type: component | MCP Tools: 28

Overview¶

Symbolic reasoning substrate that checks structural equivalence between domain models using four modes: exact_chain (functor chain equality), morita_bridge (Morita equivalence via bimodules), topos_integrate (sheaf-theoretic global model integration), and analogy (cross-domain structural similarity scoring). Domains are defined as objects and typed morphisms; axioms and Morita witness constructions are validated against the specification.

Approximate symbolic reasoning

deep_understanding is a practical structural-analysis aid, not a complete mathematical verifier. Its category-theory-inspired modes use graph structure, degree profiles, string similarity, axiom overlap, and optional library evidence to surface likely equivalences, analogies, and integration conflicts. Treat its confidence scores and explanations as decision support that should be reviewed by a human or paired with formal verification for high-stakes claims.

When to use:

Determining whether two knowledge representations are structurally equivalent before merging them
Finding analogical mappings between source and target domains for transfer learning or explanation
Integrating heterogeneous domain models into a global sheaf and detecting obstruction points

Example:

from mvp.deep_understanding import DeepUnderstandingBlock, DeepUnderstandingInput, DomainSpec, MorphismSpec

block = DeepUnderstandingBlock(name="deep")
result = block.infer(DeepUnderstandingInput(
    mode="analogy",
    domains=[
        DomainSpec(name="electricity", objects=["voltage","current","resistance"],
                   morphisms=[MorphismSpec(source="voltage", target="current", name="ohm")]),
        DomainSpec(name="fluid", objects=["pressure","flow","friction"],
                   morphisms=[MorphismSpec(source="pressure", target="flow", name="hagen")]),
    ],
    query="Map electricity concepts to fluid dynamics",
))
# result.ok → True; result.value → DeepUnderstandingOutput with analogies, confidence

Works well with: formal_methods, cegis, hyperdistillation

Public API¶

`DeepUnderstandingBlock(AIBlock[DeepUnderstandingInput, DeepUnderstandingOutput, dict])`¶

Multi-mode symbolic reasoning block.

Field	Type	Default
`name`	`str`	'deep_understanding'
`resource_bounds`	`ResourceBounds \\| None`	None
`usage`	`ResourceUsage`	field(default_factory=ResourceUsage)
`db_path`	`str`	'~/.g6/deep_understanding.db'

Methods:

`infer(data: DeepUnderstandingInput) -> Result[DeepUnderstandingOutput]`¶

`health() -> dict`¶

Return health status for production monitoring.

`MorphismSpec(BaseModel)`¶

A typed directed edge in a domain graph.

Field	Type	Default
`source`	`str`	required
`target`	`str`	required
`name`	`str`	required
`properties`	`list[str]`	Field(default_factory=list)

`DomainSpec(BaseModel)`¶

A named domain: objects + morphisms + optional axioms.

Field	Type	Default
`name`	`str`	required
`objects`	`list[str]`	required
`morphisms`	`list[MorphismSpec]`	required
`axioms`	`list[str]`	Field(default_factory=list)

`AnalogyHit(BaseModel)`¶

A single analogy match between source and target concepts.

Field	Type	Default
`source_concept`	`str`	required
`target_concept`	`str`	required
`score`	`float`	required

`DeepUnderstandingInput(BaseModel)`¶

Input for DeepUnderstandingBlock.

Field	Type	Default
`mode`	`Literal['exact_chain', 'morita_bridge', 'topos_integrate', 'analogy']`	required
`domains`	`list[DomainSpec]`	required
`query`	`str`	required
`library_sources`	`list[str]`	Field(default_factory=list)
`equivalence_type`	`Literal['auto', 'definitional', 'morita', 'categorical']`	'auto'

`DeepUnderstandingOutput(BaseModel)`¶

Output from DeepUnderstandingBlock.

Field	Type	Default
`mode`	`str`	required
`equivalent`	`bool \\| None`	None
`equivalence_type`	`str`	'none'
`bridge_description`	`str`	''
`confidence`	`float`	0.0
`exact_at`	`list[str]`	Field(default_factory=list)
`broken_at`	`list[str]`	Field(default_factory=list)
`global_model`	`DomainSpec \\| None`	None
`sheaf_obstructions`	`list[str]`	Field(default_factory=list)
`analogies`	`list[AnalogyHit]`	Field(default_factory=list)
`justification`	`str`	''
`elapsed_sec`	`float`	0.0
`degraded`	`bool`	False
`degradation_reason`	`str`	''
`corpus_grounded`	`bool`	False
`corpus_coverage`	`str`	'none'
`n_corpus_facts`	`int`	0

`MCPUnderstandingInput(BaseModel)`¶

Field	Type	Default
`op`	`UnderstandingOp`	required
`domain_id`	`str \\| None`	None
`domain_json`	`str \\| None`	None
`domains_json`	`str \\| None`	None
`source_concept`	`str \\| None`	None
`target_domain_json`	`str \\| None`	None
`top_k`	`int \\| None`	None
`analysis_id`	`str \\| None`	None
`analysis_ids_json`	`str \\| None`	None
`query`	`str \\| None`	None
`session_id`	`str \\| None`	None
`session_name`	`str \\| None`	None
`limit`	`int \\| None`	None
`request_id`	`str \\| None`	None
`run_id`	`str \\| None`	None

`MCPUnderstandingOutput(BaseModel)`¶

Field	Type	Default
`ok`	`bool`	required
`message`	`str`	required
`data_json`	`str \\| None`	None
`degraded`	`bool`	False
`degradation_reason`	`str \\| None`	None
`completion_state`	`Literal['verified', 'qualified-draft', 'blocked-escalated']`	'qualified-draft'
`warning_card`	`dict[str, Any]`	Field(default_factory=dict)
`evidence`	`dict[str, Any]`	Field(default_factory=dict)
`request_id`	`str \\| None`	None
`run_id`	`str \\| None`	None

`UnderstandingStore`¶

5-table SQLite store for Deep Understanding MCP.

Constructor:

Parameter	Type	Default
`db_path`	`str`	':memory:'

Methods:

`register_domain(name: str, objects_json: str = '[]', morphisms_json: str = '[]', axioms_json: str = '[]') -> dict`¶

`get_domain(domain_id: str) -> dict | None`¶

`list_domains(limit: int = 50) -> list[dict]`¶

`update_domain(domain_id: str, **kwargs) -> bool`¶

`retire_domain(domain_id: str) -> bool`¶

`record_analysis(domain_ids: list[str], mode: str, result_json: str = '{}', confidence: float = 0.0) -> dict`¶

`get_analysis(analysis_id: str) -> dict | None`¶

`list_analyses(mode: str | None = None, limit: int = 50) -> list[dict]`¶

`record_composition(domain_ids: list[str], result_json: str = '{}', obstructions_json: str = '[]') -> dict`¶

`get_composition(composition_id: str) -> dict | None`¶

`record_usage(domain_id: str, mode: str = '', success: bool = True) -> dict`¶

`get_domain_stats(domain_id: str) -> dict`¶

`get_effectiveness(mode: str | None = None) -> dict`¶

`save_session(name: str, data_json: str = '{}', session_id: str | None = None) -> dict`¶

`load_session(session_id: str) -> dict | None`¶

`search(query: str, top_k: int = 10) -> list[dict]`¶

`UnderstandingMCPBlock(AIBlock[MCPUnderstandingInput, MCPUnderstandingOutput, dict])`¶

26-op MCP block for Deep Understanding.

Field	Type	Default
`name`	`str`	'understanding_mcp'
`state`	`dict \\| None`	None
`db_path`	`str`	''
`resource_bounds`	`ResourceBounds \\| None`	None
`usage`	`ResourceUsage`	field(default_factory=ResourceUsage)
`max_list_limit`	`int`	1000
`max_search_limit`	`int`	1000
`max_analyze_domains`	`int`	50
`max_compose_domains`	`int`	50

Methods:

`infer(data: MCPUnderstandingInput) -> Result[MCPUnderstandingOutput]`¶

MCP Tools¶

Operation	Source
`register_domain`	understanding_mcp
`get_domain`	understanding_mcp
`list_domains`	understanding_mcp
`update_domain`	understanding_mcp
`retire_domain`	understanding_mcp
`verify_exact_chain`	understanding_mcp
`find_morita_bridge`	understanding_mcp
`integrate_domains`	understanding_mcp
`find_analogies`	understanding_mcp
`analyze_all`	understanding_mcp
`get_analysis`	understanding_mcp
`list_analyses`	understanding_mcp
`compare_analyses`	understanding_mcp
`validate_domain`	understanding_mcp
`get_degree_sequence`	understanding_mcp
`find_shared_objects`	understanding_mcp
`compose_domains`	understanding_mcp
`get_composition`	understanding_mcp
`record_usage`	understanding_mcp
`get_domain_stats`	understanding_mcp
`get_effectiveness`	understanding_mcp
`save_session`	understanding_mcp
`load_session`	understanding_mcp
`search`	understanding_mcp
`list_patterns`	understanding_mcp
`info`	understanding_mcp
`ops`	understanding_mcp
`help`	understanding_mcp