export

Imported from ActiveInferenceInstitute/GeneralizedNotationNotation (src/gnn/export/AGENTS.md). Install upstream with npx skills add ActiveInferenceInstitute/GeneralizedNotationNotation --skill export. Copyright stays with the author.

Export Module - Agent Scaffolding

Module Overview

Purpose: Multi-format export generation (JSON, XML, GraphML, GEXF, Pickle) from parsed GNN models

Pipeline Step: Step 7: Multi-format export (src/gnn/7_export.py)

Category: Data Export / Transformation

Status: Production Ready

Version: 3.2.0

Last Updated: 2026-09-04

Core Functionality

Primary Responsibilities

1. Export parsed GNN models to multiple formats
2. Generate graph-based representations (GraphML, GEXF)
3. Create portable serializations (JSON, XML, Pickle)
4. Validate export integrity
5. Provide format-specific documentation

Key Capabilities

• JSON export with schema validation
• XML export with DTD/XSD
• GraphML for network analysis tools
• GEXF for Gephi visualization
• Pickle for Python persistence

API Reference

Public Functions

process_export(target_dir, output_dir, verbose=False, **kwargs) -> bool

Description: Pipeline entry point (called by src/gnn/7_export.py). Loads parsed GNN specs from Step 3 output (gnn_processing_results.json) and exports each file to the requested formats. Accepts a formats keyword (list of format names) and an optional opt-in geo_infer options mapping (see Configuration).

validate_export_outputs(output_dir, expected_formats=None) -> Dict[str, Any]

Description: Post-run validation of export artifacts. Reads the export_results.json manifest and checks that every recorded export file exists, is non-empty, and parses cleanly for its format. When expected_formats is provided, models missing those formats are reported as incomplete. Returns a dict with keys success, checked, missing, invalid, incomplete, files.

generate_exports(target_dir, output_dir, verbose=False) -> bool

Description: Standalone export over the *.md files directly in target_dir; writes to output_dir/exports/.

export_model(model_data, output_dir, formats=None) -> Dict[str, Any]

Description: Export one already-parsed model dict to the selected formats; returns a per-format result dictionary.

Example:

from gnn.export import generate_exports

success = generate_exports(
    target_dir=Path("input/gnn_files"),
    output_dir=Path("output/7_export_output"),
    verbose=True,
)

Supported Export Formats

Standard Formats

1. JSON: Human-readable, widely compatible
2. XML: Schema-validated, industry standard

Graph Formats

3. GraphML: Standard graph format (Cytoscape, yEd)
4. GEXF: Gephi visualization format

Text Formats

5. Plaintext Summary: Human-readable model overview
6. Plaintext DSL: Round-trip GNN-like text

Binary Formats

7. Pickle: Fast Python serialization

Configuration

Configuration Options

process_export accepts these keywords:

• formats (List[str]): Formats to export (default: ["json", "xml", "graphml", "gexf", "pickle"])
• logger (logging.Logger): Override the default module logger (injected by the pipeline template)
• geo_infer (Dict[str, Any]): Optional opt-in mapping enabling the strict GEO-INFER export when "geo_infer" is requested in formats. Keys: step_seconds (float, mandatory, must be finite and positive), state_ids_path (path to a JSON array labeling states in matrix order, optional; required for space_kind="h3"), and space_kind ("categorical" (default) or "h3"). If geo_infer is requested without a step_seconds key, process_export fails visibly before any output is written (returns False and reports the missing key); the Step 7 CLI additionally raises a distinct ValueError naming the flags when --geo-* options are given without --geo-step-seconds. When geo_infer is not requested, the five default formats are produced exactly as before.

The default format set and the writer dispatch tables are derived from the canonical format registry (export.registry). The registry is the single source of truth for format names, extensions, writer callables, and categories. Do not add format-dispatch if/elif chains — extend the registry instead.

Dependencies

Required Dependencies

• json - JSON export
• xml.etree.ElementTree - XML serialization (writers)
• defusedxml - XML, GraphML, and GEXF validation reads without DTD/entity expansion
• pickle - Pickle serialization

Optional Dependencies

• networkx - Graph format export (recovery: basic XML-based export)

Usage Examples

Basic Usage

from gnn.export import generate_exports

success = generate_exports(
    target_dir=Path("input/gnn_files"),
    output_dir=Path("output/7_export_output"),
    verbose=True,
)

Specific Formats

from gnn.export import export_model

results = export_model(
    model_data=parsed_data,
    output_dir=Path("output/7_export_output"),
    formats=["json", "graphml", "gexf"],
)

Output Specification

process_export (pipeline path) writes under the step output dir:

output/7_export_output/
├── model_name/
│   ├── model_name.json
│   ├── model_name.xml
│   ├── model_name.graphml
│   ├── model_name.gexf
│   └── model_name_pickle.pkl
├── export_results.json
└── export_summary.json

generate_exports (standalone) instead writes {stem}.{json,xml,graphml,gexf,pkl} plus export_results.json under output_dir/exports/.

Integration Points

Pipeline Integration

• Input: Receives parsed GNN models from Step 3 (gnn processing)
• Output: Writes multi-format exports to output/7_export_output/ (no dedicated downstream step consumer; included in the uniform output-dir scans of Steps 20, 22, and 23)
• Dependencies: Requires GNN parsing results from src/gnn/3_gnn.py output

Module Dependencies

• gnn/: Loads the Step 3 manifest + parsed models from output/3_gnn_output/
• visualization/: Provides graph formats for visualization
• render/: Provides model data for code generation
• website/: Provides export data for website generation

External Integration

• Cytoscape: GraphML format for network analysis
• Gephi: GEXF format for graph visualization
• NetworkX: Graph format conversion and analysis

Data Flow

output/3_gnn_output/ (Step 3 manifest + parsed models)
  ↓
src/gnn/7_export.py (Multi-format export)
  ↓
  └→ output/7_export_output/ (Standalone exports; no dedicated downstream step consumer)

Testing

Test Files

• tests/export/test_export_overall.py
• tests/export/test_export_format_writers.py
• tests/export/test_export_public_api.py
• tests/export/test_export_roundtrip.py
• tests/export/test_export_registry_and_validate.py
• tests/export/test_geo_infer_contract.py
• tests/export/test_export_geo_pipeline.py

Test Coverage

Measure on demand:

uv run --extra dev python -m pytest tests/export/ \
    --cov=src/gnn/export --cov-report=term-missing

Key Test Scenarios

1. Multi-format export generation
2. Format validation and error handling
3. Graph format conversion

MCP Integration

Tools Registered

• process_export — Run the export step over a directory of GNN files
• export_single_gnn_file — Export a single GNN file to selected formats
• list_export_formats — List supported export formats and descriptions
• validate_export_format — Check whether a format name is supported

MCP File Location

• src/gnn/export/mcp.py — Tool registrations and MCP wrappers

Troubleshooting

Common Issues

Issue 1: Export fails for specific format

Symptom: Export succeeds for some formats but fails for others
Cause: Missing optional dependency (networkx) or format-specific errors
Solution:

• Check that required dependencies are installed: uv pip install networkx
• Use --verbose flag to see detailed error messages
• Check format-specific requirements in documentation

Issue 2: GraphML/GEXF export fails

Symptom: Graph formats fail to generate
Cause: Missing networkx dependency or invalid graph structure
Solution:

• Install networkx: uv pip install networkx
• Verify GNN model has valid connections section
• Check that graph data is properly structured

Issue 3: Large model export

Symptom: Export is slow or memory-heavy
Cause: Model too large for a single export operation
Solution:

• Export formats individually instead of all at once
• Process models in smaller batches

Performance Issues

Slow Export Performance

Symptoms: Export takes longer than expected
Diagnosis:

# Enable verbose logging
python src/gnn/7_export.py --target-dir input/ --verbose

Solutions:

• Export only needed formats (don't export all formats if not needed)
• Use pickle format for fastest serialization

# Enable verbose logging
python src/gnn/7_export.py --target-dir input/ --verbose

Solutions:

• Export only needed formats (don't export all formats if not needed)
• Use pickle format for fastest serialization

Version History

Current Version: 3.2.0

Features:

• Multi-format export (JSON, XML, GraphML, GEXF, Pickle, Plaintext Summary, Plaintext DSL)
• Format validation and error handling
• Graph format conversion via NetworkX
• Export integrity verification
• MCP tool integration

Known Issues:

• None currently

Roadmap

• Future: Streaming export for very large models

References

Related Documentation

• Pipeline Overview
• Architecture Guide
• GNN Export Guide

External Resources

• GraphML Specification
• GEXF Format
• NetworkX Documentation

Last Updated: 2026-04-16 Maintainer: GNN Pipeline Team Status: Production Ready Version: 3.2.0 Architecture Compliance: 100% Thin Orchestrator Pattern

Documentation

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

GNN / GEO-INFER boundary

geo_infer.py owns the opt-in geo_infer registry writer. Its normative contract accepts only explicit single-factor A–E models and requires physical step seconds. Keep the default five Step 7 formats stable. Do not import GEO-INFER into this package, infer geographic state meaning, repair matrix probabilities, or silently coerce a continuous model into categorical form. Run export tests and the POMDP extractor orientation tests when changing this boundary; run GEO's separate-environment conformance command when both repos are available. General canonicalization must preserve non-square axes and be idempotent.

geo_infer_gaussian.py adds the explicit discrete-time linear Gaussian v2 producer. It requires source F/G/H/Q/R and initial belief plus caller units; never add default control maps or interpret F as a generator. process_export accepts geo_infer_options keyed by source filename and reads contained original source for provenance. Missing metadata fails the requested format and run. test_geo_infer_gaussian.py covers unequal axes, covariance rejection, CLI, source containment, partial failure and unchanged default formats.

Step 7 additionally exposes --geo-step-seconds, --geo-state-ids and --geo-space-kind CLI flags; when --geo-step-seconds is passed, the adapter supplies a single global geo_infer mapping to process_export instead of per-file metadata. Requesting geo_infer through Step 7 with neither mechanism fails without writing output.

options.py loads bounded, duplicate-free physical metadata for the numbered Step 7 CLI; geo_infer_factored.py exports explicitly structured factored JSON.

Export validation parses XML, GraphML and GEXF with defusedxml and rejects entity declarations; the manifest records these files as invalid.