Metadata-Version: 2.5
Name: neutron-framework
Version: 0.1.0
Summary: The AI application development framework for Python
Project-URL: Homepage, https://neutron.build/
Project-URL: Documentation, https://neutron.build/docs/python/overview
Project-URL: Repository, https://github.com/neutron-build/neutron
Project-URL: Issues, https://github.com/neutron-build/neutron/issues
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: cyclopts>=3.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: starlette>=0.38.0
Requires-Dist: structlog>=24.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: ai
Requires-Dist: httpx>=0.27.0; extra == 'ai'
Provides-Extra: all
Requires-Dist: argon2-cffi>=23.1.0; extra == 'all'
Requires-Dist: granian>=2.0.0; extra == 'all'
Requires-Dist: httpx>=0.27.0; extra == 'all'
Requires-Dist: pyjwt[crypto]>=2.8.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Provides-Extra: crypto
Requires-Dist: argon2-cffi>=23.1.0; extra == 'crypto'
Requires-Dist: pyjwt[crypto]>=2.8.0; extra == 'crypto'
Provides-Extra: granian
Requires-Dist: granian>=2.0.0; extra == 'granian'
Provides-Extra: rich
Requires-Dist: rich>=13.0; extra == 'rich'
Provides-Extra: test
Requires-Dist: argon2-cffi>=23.1.0; extra == 'test'
Requires-Dist: editables>=0.5; extra == 'test'
Requires-Dist: httpx>=0.27.0; extra == 'test'
Requires-Dist: pyjwt[crypto]>=2.8.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# neutron-framework

The AI application development framework for Python — Starlette underneath,
Pydantic throughout, with a first-class client for [Nucleus](https://github.com/neutron-build/neutron/tree/main/nucleus), the
multi-model database the rest of Neutron is built on.

```bash
pip install neutron-framework
```

> The distribution is **`neutron-framework`**, not `neutron` — that name on PyPI
> belongs to OpenStack's networking service.

## A first app

```python
from pydantic import BaseModel
from neutron import App, Router

app = App(title="My API", version="1.0.0")
router = Router()

class User(BaseModel):
    id: int
    name: str
    email: str

@router.get("/users/{user_id}")
async def get_user(user_id: int) -> User:
    return await app.db.sql.query_one(
        User, "SELECT * FROM users WHERE id = $1", user_id
    )

app.include_router(router)
```

Return a Pydantic model and you get validation, serialisation and an OpenAPI
3.1 schema from the same declaration. `GET /health`, `GET /openapi.json` and
`GET /docs` are mounted for you.

## What ships

| Area | Module |
|---|---|
| Routing, handlers, dependency injection | `neutron/router.py`, `handler.py`, `depends.py` |
| Middleware (the contract's 10-layer order) | `neutron/middleware.py`, `default_stack()` |
| Errors as RFC 7807 problem+json | `neutron/error.py` |
| OpenAPI 3.1 generation | `neutron/openapi.py` |
| Nucleus client — all 14 data models | `neutron/nucleus/` |
| AI: providers, agents, RAG, MCP | `neutron/ai/` |
| Auth, cache, jobs, realtime | `neutron/auth/`, `cache/`, `jobs/`, `realtime/` |
| CLI (`python -m neutron`) | `neutron/cli.py` |
| Test helpers | `neutron/test/` |

## Extras

```bash
pip install "neutron-framework[ai]"      # AI providers, agents, RAG
pip install "neutron-framework[crypto]"  # password hashing
pip install "neutron-framework[granian]" # the Granian server
pip install "neutron-framework[rich]"    # richer CLI output
pip install "neutron-framework[all]"     # everything above
```

`[test]` is the development extra and is what CI installs.

## Nucleus

One pgwire connection reaches every data model; the non-relational models are
SQL functions rather than separate services or ports.

```python
from neutron.nucleus import NucleusClient

db = await NucleusClient.connect("postgresql://localhost:5432/mydb")

await db.kv.set("session:abc", "user-1", ttl=3600)
await db.vector.search("docs", embedding, k=5)
await db.document.insert("events", {"kind": "signup"})
```

Any PostgreSQL client works against Nucleus, so `asyncpg` and `psycopg` remain
available if you would rather not use this client at all.

## Documentation

Published docs — overview, quickstart, routing, middleware, database, realtime,
deployment — start at **https://neutron.build/docs/python/overview**. The wire-level
contract every Neutron SDK implements is
[`FRAMEWORK_CONTRACT.md`](https://github.com/neutron-build/neutron/blob/main/FRAMEWORK_CONTRACT.md); this SDK scores 12/12 on
its conformance matrix.

## Development

```bash
pip install -e ".[test]"
pytest
```

Live-database tests skip unless `NEUTRON_TEST_DATABASE_URL` points at a running
Nucleus instance.
