AGENTS.md@docs/pkl git:20260907.ae194c2A

Immutable. This exact content is served forever at /api/v1/blob/f254f6e77e835d1a.

# 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  
**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

### Integration (Steps 17-24)
- **Step 17 (Integration)**: Pkl configuration coordination
- **Step 23 (Report)**: Configuration validation results

See [src/gnn/AGENTS.md](../../src/gnn/AGENTS.md) for complete pipeline documentation.

## Function Signatures and API

### 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  
**Compliance**: Professional documentation standards  
**Maintenance**: Regular updates with new Pkl features and integration capabilities