p8s 1.3.0

A batteries-included async Python framework combining Django's DX with FastAPI's performance

P8s (Prometheus)

Forge AI-native, full-stack applications with the fire of the gods.

Getting Started • Documentation • Features • Quick Start

---

Why P8s?

Django	FastAPI	P8s
Complete but legacy	Fast but fragmented	Best of both
Sync-first	Async-first	Async by default
Admin included	No admin	Django-style admin
No AI support	No AI support	AI is a primitive

P8s brings order to modern Python development.

---

Features

Async Backend

• FastAPI under the hood
• SQLModel ORM (SQLAlchemy + Pydantic)
• Automatic CRUD for registered models
• UUID & Soft Deletes by default (.active(), .deleted(), .all_with_deleted())

Authentication

• JWT Authentication out of the box
• User roles (User, Admin, Superuser)
• Permissions & Groups (Django-style)
• Secure defaults (bcrypt, protected routes)

AI-Native

• AIField: Auto-generate content from prompts
• VectorField: Store embeddings for semantic search
• VectorSearch: Query by similarity
• Supports OpenAI, Anthropic, Google, Ollama, and more

Admin Panel

• Django-style admin interface
• Dynamic CRUD from your models
• Search, filter, paginate, bulk actions
• No frontend code required

Forms & Validation

• Pydantic-based form validation
• ModelForm auto-generated from models
• 11 field types with HTML rendering hints
• CSRF protection middleware

Database & Migrations

• Auto-detected migrations with Alembic
• Fixtures: dumpdata / loaddata
• Database shell: dbshell

CLI Tools (18+ commands)

p8s new project myapp    # Create project
p8s new app blog         # Add app
p8s dev                  # Development server (backend + frontend)
p8s migrate              # Run migrations
p8s makemigrations       # Auto-detect model changes
p8s createsuperuser      # Create admin user
p8s shell                # Interactive Python shell
p8s check                # Validate configuration
p8s dumpdata             # Export fixtures
p8s loaddata             # Import fixtures
p8s dbshell              # Database shell
p8s sendtestemail        # Test email config
p8s collectstatic        # Collect static files

---

Quick Start

Installation

pip install p8s

Create a Project

p8s new project myapp
cd myapp

Run Development Server

p8s dev

P8s (Prometheus)
━━━━━━━━━━━━━━━━━━━
Starting development server...
  Backend:  http://localhost:8000
  Frontend: http://localhost:5173

[backend] INFO: Uvicorn running on http://localhost:8000
[frontend] VITE ready in 456ms

Access Your App

URL	Description
http://localhost:8000	Backend API
http://localhost:8000/admin/	Admin panel
http://localhost:8000/docs	OpenAPI docs
http://localhost:5173	Frontend

---

Code Example

from p8s import Model
from p8s.ai import AIField, VectorField
from p8s.admin import register_model
from sqlmodel import Field

@register_model
class Product(Model, table=True):
    name: str = Field(index=True)
    description: str

    # AI-generated SEO description
    seo_description: str | None = AIField(
        prompt="Generate SEO description for {name}: {description}",
        source_fields=["name", "description"],
    )

    # Vector embedding for similarity search
    embedding: list[float] | None = VectorField(
        source_field="description"
    )

    class Admin:
        list_display = ["name", "created_at"]
        search_fields = ["name"]

Forms Example

from p8s.forms import Form, ModelForm, CharField, EmailField

class ContactForm(Form):
    name: str = CharField(max_length=100)
    email: str = EmailField()
    message: str

form = ContactForm.from_data(request.form)
if form.is_valid():
    send_email(form.data)

---

Project Structure

myapp/
├── backend/
│   ├── main.py          # FastAPI entry point
│   ├── models.py        # Database models
│   ├── settings.py      # Configuration (Pydantic Settings)
│   └── apps/            # Your apps
│       └── products/
│           ├── models.py
│           ├── router.py
│           └── schemas.py
├── frontend/            # React + Vite
│   └── src/
├── migrations/          # Alembic migrations
└── .env                 # Environment variables

---

Documentation

Topic	Description
Getting Started	Create your first project
CLI Reference	All 18+ commands
Models & Database	SQLModel ORM usage
Migrations	Auto-detected migrations
Authentication	JWT and user management
Admin Panel	Django-style admin
Forms	Validation & ModelForm
Middleware	CSRF, security, timing
AI Features	AIField, VectorField, search
Testing	Test utilities
Configuration	Environment and settings
Deployment	Docker, Railway, Fly.io

---

Test Coverage

pytest tests/ -v
# 186 passed

---

Roadmap

Completed

• Django-style settings discovery (P8S_SETTINGS_MODULE)
• Admin panel with login, CRUD, bulk actions
• JWT authentication with permissions/groups
• SQLModel integration with soft deletes
• Alembic migrations with auto-detection
• Forms module with ModelForm
• CSRF middleware
• Fixtures (dumpdata/loaddata)
• Testing utilities
• 186 tests passing

In Progress

• Admin inlines (nested models)
• Frontend auth hooks
• TypeScript type generation

Planned

• WebSocket support
• Background tasks (Celery/ARQ)
• i18n/l10n
• Multi-tenancy
• GraphQL support
• PyPI release

---

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting a PR.

# Run tests
pytest tests/

# Lint
ruff check src/

# Format
ruff format src/

---

License

MIT — steal the fire, responsibly

---

_{Built with ❤️ by Peppe37}