Skip to content

SPEC.md

Latest commit

 

History

History
91 lines (70 loc) · 4.94 KB

SPEC.md

File metadata and controls

91 lines (70 loc) · 4.94 KB
Raw

GNN Module — Specification

Architecture

The GNN module follows the Thin Orchestrator pattern: lightweight coordination scripts delegate to focused processing modules.

Format and serializer counts (canonical)

These definitions are the single source of truth for cross-references in READMEs and status docs:

Concept Count Notes
GNNFormat enum 23 All supported formats, defined in parsers/common.py.
Parsers registered 23 PARSER_REGISTRY in parsers/system.py — one parser class per format.
Serializers registered 22 SERIALIZER_REGISTRY in parsers/system.py — PNML has a parser but no dedicated serializer (parse-focused / XML-related).
Round-trip test list 21 strings in testing/test_round_trip.py FORMAT_TEST_CONFIG['test_formats'] Includes markdown plus 20 other formats. EBNF and PNML are not in this list (PNML round-trip disabled in config).

When a document says “100% round-trip,” it refers to the formats exercised by test_round_trip.py, not necessarily every enum value.

File discovery (two strategies)

API / entry Policy Where
discover_gnn_files() Narrow globs: *.md, *.gnn, *.txt; filters common non-model filenames processor.py
process_gnn_multi_format() (Step 3) Broad registered extension list so serialized formats (JSON, YAML, Lean, etc.) under the target tree are discovered parsers/common.py (FORMAT_EXTENSION_MAP) consumed by multi_format_processor.py

Do not assume the two lists stay identical: lightweight discovery favors typical author workflows; the pipeline step favors full multi-format round-tripping from a folder of mixed artifacts.

.pkl and pickle policy

.pkl is the textual Apple PKL DSL extension. Binary pickle payloads should use .pickle; previous-format binary pickle bytes found in .pkl are detected by content and routed to the pickle parser with a warning.

Components

Component File Purpose
Types types.py Shared data classes (ParsedGNN, ValidationResult, etc.). GNNFormat is defined in parsers/common.py and re-exported from types.py for consumers that import domain types from one place.
Parser parser.py GNN file parsing, format detection, validation entry point
Schema Validator schema_validator.py Full GNNParser with section-level parsing, GNNValidator for multi-level validation
Simple Validator simple_validator.py Lightweight recovery validator without complex dependencies
Validation validation.py ValidationStrategy orchestrating multi-level validation
Processor processor.py Lightweight GNN directory processing and file discovery
Core Processor core_processor.py Full pipeline orchestration with phased processing
Processors processors.py Enhanced processing with round-trip and cross-format support
Cross-Format cross_format_validator.py Cross-format consistency validation
MCP mcp.py Model Context Protocol integration for external tool access
Multi-Format multi_format_processor.py Pipeline step for multi-format serialization

Subdirectories

Directory Purpose
parsers/ Format-specific parsers & serializers: PARSER_REGISTRY (23) and SERIALIZER_REGISTRY (22); per-format *_parser.py / *_serializer.py modules in parsers/system.py
schemas/ Schema definition files (JSON, YAML, XSD, Proto, ASN.1, PKL)
grammars/ BNF and EBNF grammar definitions
testing/ Round-trip tests, performance benchmarks, integration tests
type_systems/ Scala and Haskell type system implementations
documentation/ GNN file format reference (structure, punctuation)
formal_specs/ Formal mathematical specifications in 8 languages
gnn_examples/ Reference GNN model files

Key Exports

from gnn import (
    discover_gnn_files,      # File discovery
    parse_gnn_file,          # Single-file parsing
    validate_gnn_structure,  # Structure validation
    validate_gnn,            # Full validation (file or content)
    process_gnn_directory,   # Directory processing
    generate_gnn_report,     # Report generation
    GNNParsingSystem,        # Parser registry
    ValidationLevel,         # Validation levels (BASIC, STANDARD, STRICT)
    ParsedGNN,               # Parsed GNN representation
    GNNFormat,               # Format enumeration
)

Testing

uv run --extra dev python -m pytest src/tests/gnn/test_gnn_overall.py src/tests/gnn/test_gnn_validation.py src/tests/gnn/test_gnn_parsing.py src/tests/gnn/test_gnn_processing.py -v

Documentation

  • README: Module Overview
  • AGENTS: Agentic Workflows
  • SPEC: Architectural Specification
  • SKILL: Capability API