# PyFulmen v0.1.0 Release Notes

**Release Date**: October 13, 2025  
**Release Type**: Foundation Release with Complete Foundry Module  
**Milestone**: Foundry Module Complete + Progressive Logger Phase 1

---

## 🎯 Release Overview

PyFulmen v0.1.0 establishes the foundation for the FulmenHQ Python helper library ecosystem with a **complete Foundry module** (pattern catalogs, MIME types, HTTP helpers) and **Phase 1 progressive logger** implementation.

This release prioritizes:

- **Enterprise-grade quality**: 96% test coverage, comprehensive validation
- **Developer experience**: Pydantic models, Python magic methods, intuitive APIs
- **Cross-language consistency**: Aligned with gofulmen and tsfulmen ecosystems
- **Progressive enhancement**: Zero-complexity defaults with enterprise power-ups ready

---

## ✨ Major Features

### Foundry Module (Complete)

The Foundry module provides the foundation utilities and pattern catalog system for PyFulmen.

#### Base Pydantic Models

Three specialized base classes for consistent data handling across the ecosystem:

```python
from pyfulmen.foundry import (
    FulmenDataModel,     # Immutable data (events, messages, API responses)
    FulmenConfigModel,   # Mutable config with deep merge support
    FulmenCatalogModel,  # Immutable catalog entries (patterns, MIME types)
)
```

**Features**:

- Pydantic v2.12+ for validation and schema generation
- Computed fields with exclusion by default (safe roundtripping)
- JSON serialization helpers (`to_json_dict()`, `to_json_str()`)
- Deep merge support for three-layer config pattern

#### Utility Functions

```python
from pyfulmen.foundry import utc_now_rfc3339nano, generate_correlation_id

# RFC3339Nano timestamps (microsecond precision)
timestamp = utc_now_rfc3339nano()  # "2025-10-13T14:32:15.123456Z"

# UUIDv7 correlation IDs (time-sortable)
correlation_id = generate_correlation_id()  # "0199dd68-a9de-75e8-811b-9ea72de82b73"
```

**Features**:

- UUIDv7 for time-sortable correlation tracking (cross-language consistency)
- RFC3339 with microsecond precision for enterprise logging
- Python 3.12+ compatible (uuid6 library fallback for UUIDv7)

#### Pattern Catalog System

Access curated patterns from Crucible with lazy loading and caching:

```python
from pyfulmen.foundry import FoundryCatalog, PatternAccessor
from pyfulmen.config.loader import ConfigLoader

# Create catalog
loader = ConfigLoader(app_name="fulmen")
catalog = FoundryCatalog(loader)
patterns = PatternAccessor(catalog)

# Access patterns by name
email = patterns.email()          # Internationalized email (RFC 5322)
slug = patterns.slug()             # Kebab-case or snake_case slugs
uuid = patterns.uuid_v4()          # RFC 4122 UUID v4
semver = patterns.semantic_version()  # SemVer 2.0.0 versions

# Pattern matching (multiple approaches)
if email.match("user@example.com"):
    print("Valid email")

if email("user@example.com"):  # Callable via __call__
    print("Valid email")

if email.search("Contact: user@example.com for info"):
    print("Email found in text")
```

**Available Patterns** (20+ total):

- `ansi-email`: Internationalized email with Unicode support
- `slug`: Lowercase slugs (kebab-case, snake_case)
- `path-segment`: URL path segments
- `identifier`: CamelCase/snake_case identifiers
- `domain-name`: Fully qualified domain names
- `ipv6`: IPv6 addresses (full and compressed)
- `uuid-v4`: RFC 4122 UUID v4
- `semantic-version`: SemVer 2.0.0 versions
- `strict-iso-date`: ISO 8601 dates (YYYY-MM-DD)
- `iso-timestamp-z`: ISO 8601 UTC timestamps
- And more...

#### MIME Type Detection

File type identification by extension:

```python
from pyfulmen.foundry import get_mime_type_by_extension

# Extension-based detection
mime = get_mime_type_by_extension("json")
print(mime.mime)  # "application/json"
print(mime.extensions)  # ["json", "map"]

# Check extension match
if mime.matches_extension(".json"):
    print("JSON file detected")
```

**Supported MIME Types**:

- `application/json`: JSON files (.json, .map)
- `application/yaml`: YAML files (.yaml, .yml)
- `application/x-ndjson`: Newline-delimited JSON (.ndjson)
- `text/csv`: CSV files (.csv)
- `application/xml`: XML files (.xml)
- `application/x-protobuf`: Protocol Buffers (.pb, .proto)
- `text/plain`: Plain text (.txt)

#### HTTP Status Helpers

Status code classification and grouping:

```python
from pyfulmen.foundry import is_success, is_client_error, is_server_error
from pyfulmen.foundry import HttpStatusHelper, get_default_catalog

# Convenience functions
if is_success(200):
    print("Request succeeded")

if is_client_error(404):
    print("Resource not found")

if is_server_error(500):
    print("Server error occurred")

# Detailed helper
helper = HttpStatusHelper(get_default_catalog())
print(helper.get_reason_phrase(200))  # "OK"
print(helper.get_reason_phrase(404))  # "Not Found"
```

**Status Groups**:

- `informational` (1xx): 100-103 codes
- `success` (2xx): 200-226 codes
- `redirect` (3xx): 300-308 codes
- `client-error` (4xx): 400-451 codes
- `server-error` (5xx): 500-511 codes

#### Global Catalog Convenience

Singleton catalog with simplified API:

```python
from pyfulmen.foundry import (
    get_pattern,              # Get pattern by ID
    get_mime_type,            # Get MIME type by ID
    get_mime_type_by_extension,  # Get MIME by extension
    is_success,               # Check 2xx status
    is_client_error,          # Check 4xx status
    is_server_error,          # Check 5xx status
)

# Simple pattern access
email_pattern = get_pattern("ansi-email")
if email_pattern and email_pattern("user@example.com"):
    print("Valid email")

# Simple MIME detection
mime = get_mime_type_by_extension("json")
print(f"Detected: {mime.name}")

# Simple HTTP status checks
if is_success(response.status_code):
    return response.json()
```

### Logging Module (Phase 1)

Progressive logger with three profiles for different deployment scenarios:

```python
from pyfulmen.logging import Logger, Severity

# Create logger (auto-selects profile from config/environment)
logger = Logger(service="myapp")

# Log with different severity levels
logger.trace("Detailed debug trace")
logger.debug("Debug information")
logger.info("Informational message")
logger.warn("Warning condition")
logger.error("Error occurred")
logger.fatal("Fatal error, shutting down")
```

**Three Profiles**:

1. **SimpleLogger** (default): Console-only, basic formatting
   - Zero-complexity default for getting started
   - Plain text output to stdout
   - Minimal dependencies

2. **StructuredLogger** (cloud-native): JSON output with core fields
   - Structured JSON for log aggregators
   - Core envelope fields (timestamp, severity, service, correlation_id)
   - Ready for Splunk, Datadog, ELK stack

3. **EnterpriseLogger** (full governance): 20+ field envelope
   - Complete logging envelope with all enterprise fields
   - Policy enforcement ready (Phases 2-5 will activate)
   - Correlation, context, redaction support ready

**Severity Levels**:

- `TRACE` (5): Most detailed debugging
- `DEBUG` (10): Debugging information
- `INFO` (20): Informational messages
- `WARN` (30): Warning conditions
- `ERROR` (40): Error conditions
- `FATAL` (50): Fatal errors requiring shutdown
- `NONE` (100): Disable logging

### Configuration Management

Three-layer configuration loading with Crucible integration:

```python
from pyfulmen.config.loader import ConfigLoader

loader = ConfigLoader(app_name="fulmen")

# Layer 1: Crucible defaults (embedded from sync)
# Layer 2: User overrides from ~/.config/fulmen/
# Layer 3: Application-provided config (BYOC)
config = loader.load('terminal/v1.0.0/terminal-overrides-defaults')
```

**Features**:

- Deep merge across layers
- Crucible embedded defaults
- User customization support
- Application override capability

### Schema Validation

JSON/YAML schema validation with Crucible schema registry:

```python
from pyfulmen.schema.validator import SchemaValidator

validator = SchemaValidator()
result = validator.validate(data, schema_path="crucible-py/config/sync-keys.yaml")

if result.is_valid:
    print("Validation passed")
else:
    for error in result.errors:
        print(f"Error: {error}")
```

---

## 📊 Quality Metrics

### Test Coverage

- **Foundry Module**: 104 tests, 96% coverage
- **Logging Module**: 48 tests, 96-100% coverage
- **Total**: 152+ tests passing
- **Overall Coverage**: 95%+ across all modules

### Code Quality

- ✅ Ruff linting: All checks passing
- ✅ Ruff formatting: Code formatted consistently
- ✅ Type hints: Comprehensive type coverage
- ✅ Documentation: All public APIs documented

### Performance

- Lazy loading: Catalog data loaded only when accessed
- Cached compilation: Patterns compiled once and reused
- Singleton catalog: Single instance shared across application
- Minimal dependencies: Fast startup time

---

## 🔧 Technical Details

### Dependencies

```toml
[project]
dependencies = [
    "jsonschema>=4.25.1",   # Schema validation
    "pydantic>=2.12.0",     # Data validation with computed fields
    "pyyaml>=6.0.3",        # YAML parsing
    "uuid6>=2025.0.1",      # UUIDv7 support (fallback for Python 3.12)
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",        # Testing framework
    "pytest-cov>=4.1.0",    # Coverage reporting
    "ruff>=0.1.0",          # Linting and formatting
]
```

### Python Version Support

- **Minimum**: Python 3.12
- **Tested**: Python 3.12, 3.13
- **Recommended**: Python 3.13 for native UUIDv7 support

### Installation

```bash
# Install from source (for now - pre-release)
git clone <repository-url>
cd pyfulmen
uv pip install -e .

# With development dependencies
uv pip install -e ".[dev]"
```

---

## 🚀 Getting Started

### Quick Example

```python
from pyfulmen.foundry import get_pattern, is_success
from pyfulmen.logging import Logger

# Setup logger
logger = Logger(service="myapp")

# Validate email with pattern
email_pattern = get_pattern("ansi-email")
if email_pattern("user@example.com"):
    logger.info("Valid email address")
else:
    logger.warn("Invalid email format")

# Check HTTP status
response_code = 200
if is_success(response_code):
    logger.info("Request successful")
```

### More Examples

See the comprehensive documentation in:

- `src/pyfulmen/foundry/README.md` - Foundry module guide
- `tests/unit/foundry/test_catalog.py` - Pattern usage examples
- `tests/unit/logging/test_logger.py` - Logger usage examples

---

## 📝 Known Limitations

### Not Yet Implemented (Planned for v0.1.1+)

- **Logging Phases 2-5**: Severity mapping, context propagation, redaction, throttling, middleware
- **Country Code Lookup**: ISO country codes (optional feature)
- **MIME Magic Numbers**: Byte-level MIME detection (optional feature)

### Current Limitations

- Logging policy enforcement is configured but not fully activated (awaits Phases 2-5)
- No byte-level MIME detection (extension-based detection covers 95% of use cases)
- No country code lookups (not needed for most applications)

---

## 🔄 Migration Guide

This is the initial v0.1.0 release. No migration required.

### Future Compatibility

- v0.1.x releases will maintain API compatibility
- No breaking changes planned during v0.1.x series
- v0.2.0 may introduce breaking changes with notice

---

## 🤝 Contributors

**Generated by**: PyFulmen Architect (@pyfulmen-architect) using [OpenCode](https://github.com/sst/opencode)  
**Supervised by**: @3leapsdave (Dave Thompson)  
**Agentic Attribution**: All commits follow FulmenHQ agentic attribution standards

---

## 📚 Additional Resources

- **Repository**: [pyfulmen](https://github.com/fulmenhq/pyfulmen) (internal)
- **Documentation**: `docs/` directory
- **Standards**: `docs/crucible-py/standards/` for FulmenHQ ecosystem standards
- **Architecture**: `docs/crucible-py/architecture/` for design decisions
- **Maintainers**: See `MAINTAINERS.md` for project governance

---

## 🎯 Next Steps

### v0.1.1 (Planned)

Focus on completing logging upscale:

- Severity mapping and level filtering
- Context propagation with correlation IDs
- Redaction and PII protection
- Throttling and rate limiting
- Custom middleware pipeline

### v0.1.2+ (Planned)

Optional enhancements:

- Country code lookup utilities
- MIME magic number detection
- Additional ecosystem utilities

### v0.2.0 (Planned)

Enterprise complete milestone:

- Full progressive logging implementation
- Production-ready for FulmenHQ ecosystem
- Comprehensive documentation and examples
- Cross-language compatibility verified

---

**Release**: v0.1.0  
**Date**: October 13, 2025  
**Status**: ✅ Released
