Metadata-Version: 2.4
Name: winterforge
Version: 0.2.1
Summary: AI-native framework with composable primitives
Author: Beau Simensen
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.1.7
Requires-Dist: argon2-cffi>=23.1.0
Requires-Dist: bcrypt>=4.1.2
Requires-Dist: PyJWT>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"

# WinterForge

**Async-first framework for composable data primitives.**

---

## Quick Start

```python
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='alice@example.com',
    password='secure123'
)

# Query
user = await users.get('alice@example.com')  # 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.

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

### Storage
**SQLite**, **PostgreSQL**, **YAML**, **Env** backends.

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

---

## Installation

```bash
pip install -e .
```

---

## Testing

```bash
# 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

```bash
# User management
winterforge user create alice alice@example.com
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:**

```python
# 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):**

```python
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', 'alice@example.com')
```

---

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