# icog-labs-dev/hybrid-miner architecture

> Architecture diagram of the GitHub repository icog-labs-dev/hybrid-miner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/icog-labs-dev/hybrid-miner
- Repository: https://github.com/icog-labs-dev/hybrid-miner

## Overview

Hybrid Miner provides two mining interfaces: standalone mining of trusted MeTTa graphs, and a source-grounded workflow that validates semantic documents, emits facts plus provenance, admits them against bundle-derived PeTTa checks, recovers exact evidence, and builds typed candidate records. The map retains the raw graph adapter alongside the document stages. Inter-module details are limited to excerpted references and explicit README workflow statements; unsampled implementations are represented only where the README identifies their role.

Main entry points: [`src/hybrid_miner/emission/emit_petta.py`](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/emission/emit_petta.py) (Fact and Metadata Emitter), [`src/hybrid_miner/mining/build_pattern_records.py`](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/build_pattern_records.py) (Candidate Record Builder), [`src/hybrid_miner/mining/exact_matches.py`](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/exact_matches.py) (Exact Evidence Recovery), [`src/hybrid_miner/ingestion/petta_gate.py`](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/ingestion/petta_gate.py) (PeTTa Evidence Gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contracts["Contracts and Ontology"]
  node_semantic_doc["Semantic Document"]
  node_pattern_record["Pattern Record<br/>[pattern_record.py]"]
  node_ontology_bundle["Ontology Bundle<br/>[bundle.py]"]
end

subgraph group_ingestion["Document Admission"]
  node_jsonl_ingestion["JSONL Validation"]
  node_admission_policy["Admission Manifest<br/>[admission.py]"]
  node_petta_gate["PeTTa Evidence Gate<br/>[petta_gate.py]"]
end

subgraph group_emission["Graph Emission"]
  node_fact_emitter["Fact and Metadata Emitter<br/>[emit_petta.py]"]
  node_rule_emitter["Rule Graph Encoder<br/>[semantic_rules.py]"]
  node_symbol_codec["Symbol Codec<br/>[symbols.py]"]
end

subgraph group_mining["Mining and Evidence"]
  node_raw_mining["Standalone Graph Mining<br/>[petta_runner.py]"]
  node_admitted_mining["Admitted Support Mining"]
  node_exact_matches["Exact Evidence Recovery<br/>[exact_matches.py]"]
  node_pattern_canonicalization["Pattern Canonicalization"]
  node_pattern_predicates["Pattern Predicate Rules"]
  node_pattern_types["Pattern Type Rules<br/>[pattern_types.py]"]
  node_record_builder["Candidate Record Builder"]
end

node_user(("Package User"))
node_petta_runtime{{"PeTTa Runtime"}}
node_hyperon_miner{{"Hyperon Miner"}}

node_user -->|"submits trusted facts"| node_raw_mining
node_raw_mining -->|"runs graph queries"| node_petta_runtime
node_raw_mining -->|"mines patterns"| node_hyperon_miner
node_user -->|"submits documents"| node_jsonl_ingestion
node_user -->|"supplies definitions"| node_ontology_bundle
node_jsonl_ingestion -->|"validates records"| node_semantic_doc
node_jsonl_ingestion -->|"validates against"| node_ontology_bundle
node_jsonl_ingestion -->|"provides accepted JSONL"| node_fact_emitter
node_fact_emitter -->|"revalidates documents"| node_semantic_doc
node_fact_emitter -->|"encodes with"| node_ontology_bundle
node_fact_emitter -->|"encodes symbols"| node_symbol_codec
node_fact_emitter -->|"encodes source rules"| node_rule_emitter
node_fact_emitter -->|"emits artifacts for checks"| node_petta_gate
node_petta_gate -->|"checks graph evidence"| node_petta_runtime
node_petta_gate -->|"derives schema from"| node_ontology_bundle
node_petta_gate -->|"records selection"| node_admission_policy
node_admitted_mining -->|"gates admitted facts"| node_petta_gate
node_admitted_mining -->|"mines support"| node_petta_runtime
node_admitted_mining -->|"uses miner runtime"| node_hyperon_miner
node_admitted_mining -->|"produces support input"| node_exact_matches
node_exact_matches -->|"recovers bindings"| node_petta_runtime
node_exact_matches -->|"canonicalizes patterns"| node_pattern_canonicalization
node_exact_matches -->|"checks exclusions"| node_admission_policy
node_exact_matches -->|"provides verified bindings"| node_record_builder
node_record_builder -->|"checks canonical form"| node_pattern_canonicalization
node_record_builder -->|"derives predicate constraints"| node_pattern_predicates
node_record_builder -->|"derives type constraints"| node_pattern_types
node_record_builder -->|"constructs typed records"| node_pattern_record
node_record_builder -->|"validates against"| node_ontology_bundle

click node_semantic_doc "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/contracts/semantic_document.py"
click node_pattern_record "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/contracts/pattern_record.py"
click node_ontology_bundle "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/ontology/bundle.py"
click node_jsonl_ingestion "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/ingestion/semantic_documents.py"
click node_admission_policy "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/ingestion/admission.py"
click node_petta_gate "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/ingestion/petta_gate.py"
click node_fact_emitter "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/emission/emit_petta.py"
click node_rule_emitter "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/emission/semantic_rules.py"
click node_symbol_codec "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/emission/symbols.py"
click node_raw_mining "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/petta_runner.py"
click node_admitted_mining "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/admitted_support.py"
click node_exact_matches "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/exact_matches.py"
click node_pattern_canonicalization "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/canonicalize_patterns.py"
click node_pattern_predicates "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/pattern_predicates.py"
click node_pattern_types "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/pattern_types.py"
click node_record_builder "https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/build_pattern_records.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_semantic_doc,node_pattern_record,node_ontology_bundle,node_user toneBlue
class node_jsonl_ingestion,node_admission_policy,node_petta_gate toneAmber
class node_fact_emitter,node_rule_emitter,node_symbol_codec toneMint
class node_raw_mining,node_admitted_mining,node_exact_matches,node_pattern_canonicalization,node_pattern_predicates,node_pattern_types,node_record_builder toneRose
class node_petta_runtime,node_hyperon_miner toneIndigo
```

## Components

### Contracts and Ontology

- [Semantic Document](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/contracts/semantic_document.py): `src/hybrid_miner/contracts/semantic_document.py`
- [Pattern Record](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/contracts/pattern_record.py): `src/hybrid_miner/contracts/pattern_record.py`
- [Ontology Bundle](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/ontology/bundle.py): `src/hybrid_miner/ontology/bundle.py`

### Document Admission

- [JSONL Validation](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/ingestion/semantic_documents.py): `src/hybrid_miner/ingestion/semantic_documents.py`
- [Admission Manifest](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/ingestion/admission.py): `src/hybrid_miner/ingestion/admission.py`
- [PeTTa Evidence Gate](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/ingestion/petta_gate.py): `src/hybrid_miner/ingestion/petta_gate.py`

### Graph Emission

- [Fact and Metadata Emitter](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/emission/emit_petta.py): `src/hybrid_miner/emission/emit_petta.py`
- [Rule Graph Encoder](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/emission/semantic_rules.py): `src/hybrid_miner/emission/semantic_rules.py`
- [Symbol Codec](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/emission/symbols.py): `src/hybrid_miner/emission/symbols.py`

### Mining and Evidence

- [Standalone Graph Mining](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/petta_runner.py): `src/hybrid_miner/mining/petta_runner.py`
- [Admitted Support Mining](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/admitted_support.py): `src/hybrid_miner/mining/admitted_support.py`
- [Exact Evidence Recovery](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/exact_matches.py): `src/hybrid_miner/mining/exact_matches.py`
- [Pattern Canonicalization](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/canonicalize_patterns.py): `src/hybrid_miner/mining/canonicalize_patterns.py`
- [Pattern Predicate Rules](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/pattern_predicates.py): `src/hybrid_miner/mining/pattern_predicates.py`
- [Pattern Type Rules](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/pattern_types.py): `src/hybrid_miner/mining/pattern_types.py`
- [Candidate Record Builder](https://github.com/icog-labs-dev/hybrid-miner/blob/main/src/hybrid_miner/mining/build_pattern_records.py): `src/hybrid_miner/mining/build_pattern_records.py`

### Other components

- **Package User**
- **PeTTa Runtime**
- **Hyperon Miner**

## Connections

- Package User → Standalone Graph Mining: submits trusted facts (evidence: `README.md`)
- Standalone Graph Mining → PeTTa Runtime: runs graph queries (evidence: `README.md`)
- Standalone Graph Mining → Hyperon Miner: mines patterns (evidence: `README.md`)
- Package User → JSONL Validation: submits documents (evidence: `README.md`)
- Package User → Ontology Bundle: supplies definitions (evidence: `README.md`)
- JSONL Validation → Semantic Document: validates records (evidence: `src/hybrid_miner/ingestion/semantic_documents.py`)
- JSONL Validation → Ontology Bundle: validates against (evidence: `src/hybrid_miner/ingestion/semantic_documents.py`)
- JSONL Validation → Fact and Metadata Emitter: provides accepted JSONL (evidence: `README.md`)
- Fact and Metadata Emitter → Semantic Document: revalidates documents (evidence: `README.md`)
- Fact and Metadata Emitter → Ontology Bundle: encodes with (evidence: `src/hybrid_miner/emission/emit_petta.py`)
- Fact and Metadata Emitter → Symbol Codec: encodes symbols (evidence: `src/hybrid_miner/emission/emit_petta.py`)
- Fact and Metadata Emitter → Rule Graph Encoder: encodes source rules (evidence: `src/hybrid_miner/emission/emit_petta.py`)
- Fact and Metadata Emitter → PeTTa Evidence Gate: emits artifacts for checks (evidence: `README.md`)
- PeTTa Evidence Gate → PeTTa Runtime: checks graph evidence (evidence: `README.md`)
- PeTTa Evidence Gate → Ontology Bundle: derives schema from (evidence: `README.md`)
- PeTTa Evidence Gate → Admission Manifest: records selection (evidence: `README.md`)
- Admitted Support Mining → PeTTa Evidence Gate: gates admitted facts (evidence: `README.md`)
- Admitted Support Mining → PeTTa Runtime: mines support (evidence: `README.md`)
- Admitted Support Mining → Hyperon Miner: uses miner runtime (evidence: `README.md`)
- Admitted Support Mining → Exact Evidence Recovery: produces support input (evidence: `README.md`)
- Exact Evidence Recovery → PeTTa Runtime: recovers bindings (evidence: `README.md`)
- Exact Evidence Recovery → Pattern Canonicalization: canonicalizes patterns (evidence: `src/hybrid_miner/mining/exact_matches.py`)
- Exact Evidence Recovery → Admission Manifest: checks exclusions (evidence: `src/hybrid_miner/mining/exact_matches.py`)
- Exact Evidence Recovery → Candidate Record Builder: provides verified bindings (evidence: `README.md`)
- Candidate Record Builder → Pattern Canonicalization: checks canonical form (evidence: `src/hybrid_miner/mining/build_pattern_records.py`)
- Candidate Record Builder → Pattern Predicate Rules: derives predicate constraints (evidence: `src/hybrid_miner/mining/build_pattern_records.py`)
- Candidate Record Builder → Pattern Type Rules: derives type constraints (evidence: `src/hybrid_miner/mining/build_pattern_records.py`)
- Candidate Record Builder → Pattern Record: constructs typed records (evidence: `src/hybrid_miner/mining/build_pattern_records.py`)
- Candidate Record Builder → Ontology Bundle: validates against (evidence: `src/hybrid_miner/mining/build_pattern_records.py`)