AGENTS.md@docs/pkl · diff
git:20260907.ae194c2 to git:20260917.482a267
15 added, 16 removed. Audit A to A.
# Pkl Documentation Agent
> **📋 Document Metadata**
> **Type**: Configuration Language Integration Agent | **Audience**: Developers, Configuration Engineers | **Complexity**: Intermediate
> **Cross-References**: [README.md](README.md) | [Pkl GNN Guide](pkl_gnn.md) | [Configuration Management](../configuration/README.md) | [Main Documentation](../README.md)
## Overview
This directory contains comprehensive documentation, resources, and implementation guides for integrating **Pkl** (Apple's Configuration Language) with GNN (Generalized Notation Notation). Pkl provides configuration-as-code capabilities with type safety, validation, and multi-format output generation, enhancing GNN model specification and management.
- **Status**: ✅ Production Ready
+ > **Scope note**: Apple Pkl is a *registered serialization format* (`GNNFormat.PKL`, `.pkl` — `PKLParser` in `src/gnn/parsers/schema_parser.py`, `PKLSerializer` in `src/gnn/parsers/pkl_serializer.py`), exercised by Step 3 (`3_gnn.py`) multi-format serialization, with artifacts written to `output/3_gnn_output/`. It is not a render or execution framework: no entry in `src/gnn/render/framework_registry.py`, no Step 11 render target, and no Step 12 executor. Distinct from this, the binary Python-pickle export in `src/gnn/export/` (Step 7) also uses a `.pkl` extension; per the format convention, `.pkl` defaults to textual Pkl DSL and binary pickle files should use `.pickle`.
+
+ **Status**: Format support implemented in `src/gnn/parsers/` (PKL parser + serializer); Pkl is not a render/execution framework
**Version**: 1.0
## Purpose
Pkl integration enables:
- **Enhanced Model Specification**: Type-safe GNN model definitions
- **Multi-Format Export**: Native multi-format rendering capabilities
- **Validation**: Built-in type system with constraint validation
- **Template System**: Reusable Active Inference model templates
- **Configuration-as-Code**: Scientific model configuration management
## Contents
**Files**: 4 | **Subdirectories**: 2
## Quick Navigation
- **README.md**: [Directory overview](README.md)
- **GNN Documentation**: [gnn/AGENTS.md](../gnn/AGENTS.md)
- **Main Documentation**: [docs/README.md](../README.md)
- **Pipeline Reference**: [src/gnn/AGENTS.md](../../src/gnn/AGENTS.md)
## Documentation Structure
This module is organized as follows:
- **Overview**: High-level description and purpose
- **Contents**: Files and subdirectories
- **Integration**: Connection to the broader pipeline
- **Usage**: How to work with this subsystem
## Integration with Pipeline
- This documentation is integrated with the 25-step GNN processing pipeline:
-
- ### Core Processing (Steps 0-9)
- - **Step 3 (GNN)**: Pkl configuration generation from parsed GNN models
- - **Step 5 (Type Checker)**: Type-safe model validation using Pkl
- - **Step 7 (Export)**: Multi-format output generation via Pkl
-
- ### Simulation (Steps 10-16)
- - **Step 11 (Render)**: Pkl configuration for simulation environments
- - **Step 12 (Execute)**: Pkl-based configuration management
+ This documentation references the 25-step GNN processing pipeline as follows:
- ### Integration (Steps 17-24)
- - **Step 17 (Integration)**: Pkl configuration coordination
- - **Step 23 (Report)**: Configuration validation results
+ The implemented integration point is the **format registry**, exercised at
+ **Step 3 (`3_gnn.py`) multi-format serialization** (artifacts in `output/3_gnn_output/`):
+ `PKLParser` and `PKLSerializer` handle `GNNFormat.PKL`. There is no Pkl involvement
+ in Steps 5, 11, 12, 17, or 23 — the touchpoints below are **proposals**, not
+ implemented behavior.
See [src/gnn/AGENTS.md](../../src/gnn/AGENTS.md) for complete pipeline documentation.
- ## Function Signatures and API
+ ## Function Signatures and API (proposed — not implemented)
+ The signatures below are illustrative sketches; no such functions exist in the
+ codebase. The implemented Pkl surface is `PKLParser`/`PKLSerializer` in
+ `src/gnn/parsers/`.
+
### Configuration Management Functions
```python
def generate_pkl_config(gnn_model: GNNModel) -> PklConfig:
"""
Generate Pkl configuration from GNN model.
Parameters:
gnn_model: Parsed GNN model structure
Returns:
PklConfig with type-safe model definition
"""
def validate_pkl_config(config: PklConfig) -> ValidationResult:
"""
Validate Pkl configuration using built-in type system.
Parameters:
config: Pkl configuration to validate
Returns:
ValidationResult with type checking results
"""
```
## Standards and Guidelines
All documentation in this module adheres to professional standards:
- **Clarity**: Concrete, technical writing
- **Functionality**: Describes actual capabilities
- **Completeness**: Comprehensive coverage
- **Consistency**: Uniform structure and style
## Related Resources
### Main GNN Documentation
- **[GNN Overview](../gnn/gnn_overview.md)**: Core GNN concepts
- **[GNN Quickstart](../gnn/tutorials/quickstart_tutorial.md)**: Getting started guide
- **[Configuration Management](../configuration/README.md)**: Configuration systems
### Configuration Resources
- **[Export Formats](../export/README.md)**: Multi-format export
- **[Type Checking](../../src/gnn/type_checker/AGENTS.md)**: Type validation
- **[Configuration Management](../configuration/README.md)**: Configuration systems
### Pipeline Architecture
- **[Pipeline Documentation](../gnn/operations/gnn_tools.md)**: Complete pipeline guide
- **[Pipeline AGENTS](../../src/gnn/AGENTS.md)**: Implementation details
- **[Pipeline README](../../src/gnn/README.md)**: Pipeline overview
## See Also
- **[Pkl Cross-Reference](../CROSS_REFERENCE_INDEX.md#pkl)**: Cross-reference index entry
- **[Configuration Management](../configuration/README.md)**: Configuration systems
- **[Export Formats](../export/README.md)**: Multi-format export
- **[Main Index](../README.md)**: Return to main documentation
---
- **Status**: ✅ Production Ready
+ **Status**: Format support implemented in `src/gnn/parsers/` (PKL parser + serializer at Step 3 serialization); Pkl is not a render/execution framework
**Compliance**: Professional documentation standards
**Maintenance**: Regular updates with new Pkl features and integration capabilities