winterforge 0.2.1

AI-native framework with composable primitives

WinterForge

Async-first framework for composable data primitives.

---

Quick Start

from winterforge.frags import Frag
from winterforge.frags.registries import UserRegistry
from winterforge.plugins import discover_plugins, StorageManager

# Initialize
discover_plugins()
StorageManager.load_bootstrap()

# Create user
users = UserRegistry()
user = await users.create(
    username='alice',
    email='[e-mail]',
    password='secure123'
)

# Query
user = await users.get('[e-mail]')  # Email resolution
active = await users.verified_only().all()   # Filter

# Create Frag
post = Frag(
    affinities=['post', 'published'],
    traits=['titled', 'timestamped', 'sluggable']
)

post.set_title("Hello World") \
    .generate_slug("Hello World")

await post.save()

---

Core Concepts

Frags

Composable data primitives built from:

• Affinities - What it IS (tags: ['user', 'admin'])
• Traits - What it CAN DO (behavior: ['titled', 'persistable'])
• Aliases - Flexible metadata (relations: {'employee_id': '12345'})

Registries

Query collections of Frags by composition.

users = UserRegistry()
admins = await users.with_role('admin').all()

Storage

SQLite, PostgreSQL, YAML, Env backends.

storage = StorageManager.get('sqlite', db_path='app.db')
await storage.save(frag)

---

Installation

pip install -e .

---

Testing

# All tests
pytest

# Core tests (no PostgreSQL)
pytest --ignore=tests/frags/storage/test_postgresql_integration.py

Expected: 581 passing, 1 warning (JWT dev secret)

---

Documentation

• Quick Start: QUICKSTART.md - 5-minute introduction
• Glossary: GLOSSARY.md - Complete terminology reference
• Handoff: HANDOFF.md - Recent changes and architecture
• Examples: examples/pkm/ - Personal knowledge management app

---

Project Structure

winterforge/
├── frags/              # Frag core
│   ├── base.py        # Frag class
│   ├── registry.py    # FragRegistry
│   ├── traits/        # Built-in traits
│   └── registries/    # Specialized registries
├── plugins/           # Plugin system
│   ├── storage/       # Storage backends
│   ├── identity/      # Identity resolvers
│   └── managers/      # Plugin managers
└── cli/              # CLI commands

---

Built-in Traits

• titled - title, subtitle
• sluggable - URL slugs
• timestamped - created_on, updated_on
• persistable - save(), delete(), is_new()
• userable - username, email, email_verified
• authenticatable - password hashing
• authorizable - roles, permissions
• sessionable - session management

---

CLI

# User management
winterforge user create alice [e-mail]
winterforge user add-role alice admin

# Session management
winterforge session create alice
winterforge session verify <token>

# Role/permission management
winterforge role create admin "Admin role"
winterforge permission create posts.create

---

Async-First

All I/O operations are async:

# Storage
await storage.save(frag)
frag = await storage.load(id)

# Frags
await frag.save()
await frag.delete()

# Registry
frag = await registry.get(identity)
all_frags = await registry.all()

Sync wrapper (rare):

from winterforge.utils.sync import to_sync

@to_sync
async def create_user_sync(username, email):
    users = UserRegistry()
    return await users.create(username, email, 'password')

user = create_user_sync('alice', '[e-mail]')

---

Architecture

• Composition over inheritance - Frags compose capabilities
• Plugin-based - Extensible via decorators
• Async-first - Modern Python standards
• Everything is a Frag - Even CLI output

---

Status

Version: Pre-release (Phase 4 complete) Tests: 581 passing Warnings: 1 (expected) Ready for: Feature development

---

WinterForge is async-first, composition-driven, and ready for production.