Metadata-Version: 2.4
Name: vertebra-core
Version: 0.2.0
Requires-Dist: anyio>=4.0
Requires-Dist: msgspec>=0.18
Requires-Dist: rich>=13.0
Requires-Dist: rich-click>=1.7
Requires-Dist: advanced-alchemy>=1.12.0 ; extra == 'alchemy'
Requires-Dist: sqlalchemy>=2.0.36 ; extra == 'alchemy'
Requires-Dist: alembic>=1.14.0 ; extra == 'alchemy'
Requires-Dist: sqlspec>=0.69.0 ; extra == 'all'
Requires-Dist: advanced-alchemy>=1.12.0 ; extra == 'all'
Requires-Dist: sqlalchemy>=2.0.36 ; extra == 'all'
Requires-Dist: alembic>=1.14.0 ; extra == 'all'
Requires-Dist: pyarrow>=18.0.0 ; extra == 'all'
Requires-Dist: pydantic>=2.9.0 ; extra == 'all'
Requires-Dist: attrs>=24.0.0 ; extra == 'all'
Requires-Dist: polars>=1.0.0 ; extra == 'all'
Requires-Dist: litestar>=2.15.0 ; extra == 'all'
Requires-Dist: starlette>=0.40.0 ; extra == 'all'
Requires-Dist: fastapi>=0.115.0 ; extra == 'all'
Requires-Dist: flask>=3.0.0 ; extra == 'all'
Requires-Dist: django>=5.1.0 ; extra == 'all'
Requires-Dist: litestar-queues>=0.12.0 ; extra == 'all'
Requires-Dist: litestar-security>=0.6.0 ; extra == 'all'
Requires-Dist: litestar-autowire>=0.2.0 ; extra == 'all'
Requires-Dist: litestar-email>=0.4.0 ; extra == 'all'
Requires-Dist: litestar-mcp>=0.16.0 ; extra == 'all'
Requires-Dist: litestar-vite>=0.32.0 ; extra == 'all'
Requires-Dist: litestar-asyncapi>=0.2.0 ; extra == 'all'
Requires-Dist: litestar-htmx>=0.5.0 ; extra == 'all'
Requires-Dist: litestar-saq>=0.8.0 ; extra == 'all'
Requires-Dist: pyarrow>=18.0.0 ; extra == 'arrow'
Requires-Dist: litestar-asyncapi>=0.2.0 ; extra == 'asyncapi'
Requires-Dist: attrs>=24.0.0 ; extra == 'attrs'
Requires-Dist: litestar-autowire>=0.2.0 ; extra == 'autowire'
Requires-Dist: django>=5.1.0 ; extra == 'django'
Requires-Dist: litestar-email>=0.4.0 ; extra == 'email'
Requires-Dist: fastapi>=0.115.0 ; extra == 'fastapi'
Requires-Dist: pydantic>=2.9.0 ; extra == 'fastapi'
Requires-Dist: flask>=3.0.0 ; extra == 'flask'
Requires-Dist: litestar-htmx>=0.5.0 ; extra == 'htmx'
Requires-Dist: litestar>=2.15.0 ; extra == 'litestar'
Requires-Dist: litestar-mcp>=0.16.0 ; extra == 'mcp'
Requires-Dist: polars>=1.0.0 ; extra == 'polars'
Requires-Dist: pydantic>=2.9.0 ; extra == 'pydantic'
Requires-Dist: litestar-queues>=0.12.0 ; extra == 'queues'
Requires-Dist: litestar-saq>=0.8.0 ; extra == 'saq'
Requires-Dist: litestar-security>=0.6.0 ; extra == 'security'
Requires-Dist: sqlspec>=0.69.0 ; extra == 'sqlspec'
Requires-Dist: starlette>=0.40.0 ; extra == 'starlette'
Requires-Dist: litestar-vite>=0.32.0 ; extra == 'vite'
Provides-Extra: alchemy
Provides-Extra: all
Provides-Extra: arrow
Provides-Extra: asyncapi
Provides-Extra: attrs
Provides-Extra: autowire
Provides-Extra: django
Provides-Extra: email
Provides-Extra: fastapi
Provides-Extra: flask
Provides-Extra: htmx
Provides-Extra: litestar
Provides-Extra: mcp
Provides-Extra: polars
Provides-Extra: pydantic
Provides-Extra: queues
Provides-Extra: saq
Provides-Extra: security
Provides-Extra: sqlspec
Provides-Extra: starlette
Provides-Extra: vite
Summary: One runtime for Python and TypeScript — backend, frontend, web, gRPC, workers, and standalone apps.
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-inline-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="docs/assets/banner-inline-light.svg">
    <img alt="Vertebra" src="docs/assets/banner-inline-light.svg" width="520">
  </picture>
  <p><strong>One runtime for Python and TypeScript — backend, frontend, web, gRPC, workers, and standalone apps.</strong></p>
</div>

---

Vertebra is one unified runtime for Python and TypeScript across backend, frontend, web, gRPC, workers, and standalone apps:

- **Python Framework & Server**: Type-safe APIs (`App`, `Controller`, `Router`, `Route`, `Procedure`, `ProcedureRouter`, `Provide`, `Inject`, `QueueService`, Inertia v3, SSR, and MCP/A2A agent protocols) plus native, ASGI, WSGI, and RSGI support.
- **Worker Runtime (`vertebra-core`, `vertebra-py`)**: Runs Python in-process or across multiple worker processes over shared memory.
- **HTTP Server & Bundler (`vertebra-http`, `vertebra-bundler`)**: HTTP/1.1, HTTP/2, HTTP/3, gRPC, WebSockets, SSE, TLS, compression, static files, JavaScript bundling, and QuickJS SSR.
- **Storage, Databases & TypeScript Client (`vertebra-storage`, `vertebra-db`, `@vertebra/client`)**: Multicloud object storage (S3, GCS, Azure, R2, OCI, HTTP, local), database drivers (Postgres, MySQL, SQLite, Oracle 26ai, SQL Server, DuckDB, Redis, Valkey, DataFusion), CTE statement stacking (`QueryPipeline`), Cloud SQL/AlloyDB dialers, and a typed TypeScript client for React, Vue, Svelte, Angular, HTMX, and Vite.

## Quickstart

```bash
uv add vertebra-core
```

## CLI Usage (`vtb`)

```bash
vtb run myapp:app --host 127.0.0.1 --port 8000 --workers 4
vtb dev myapp:app --port 8000
vtb js build
vtb js generate-types
vtb init my-project
vtb build --standalone
```

## Common Make Targets

```bash
make dev         # Build Rust crates and install debug Python extensions
make build       # Build TS client, release Rust binaries, and wheel
make test        # Run all tests (Rust + Python + TypeScript)
make rs-test     # Run Rust workspace tests (tls + compression features)
make py-test     # Run Python test suite
make ts-test     # Run TypeScript client tests (Vitest)
make lint        # Format and lint Python, Rust, and TypeScript
make check       # Run full lint, type checks, all tests, and coverage
make docs        # Build Zensical site, postbuild, and verify artifacts
make docs-serve  # Serve Zensical documentation locally with live reload
make bench       # Run benchmark suite
```

## Repository Layout

```text
src/
  py/
    vertebra/          # Python framework, server, CLI, agent, storage, db
    tests/             # Python unit and FFI test suite
  rs/
    vertebra-core/     # Shared-memory rings and worker IPC
    vertebra-py/       # PyO3 native extension (_vertebra)
    vertebra-http/     # HTTP/1.1, HTTP/2, HTTP/3, gRPC, WebSocket, and TLS server
    vertebra-bundler/  # JavaScript bundler and QuickJS SSR
    vertebra-storage/  # Cloud and local object storage (_storage)
    vertebra-db/       # Postgres, MySQL, and SQLite connection pools
  ts/
    vertebra-client/   # @vertebra/client TypeScript SDK
```

## Execution Modes

Vertebra automatically picks the right worker mode from `--workers` and your Python build (or you can set `--topology embedded` or `--topology shm` yourself):

### 1. Embedded Mode
- **When it runs**: Automatically for a single worker (`--workers 0` or `1`) or on free-threaded Python (`3.14t`/`3.15t`), or when you pass `--topology embedded`.
- **How it works**: The Rust HTTP server and Python app run inside the same OS process with no cross-process overhead.

### 2. Shared-Memory Mode (`shm`)
- **When it runs**: Automatically when `--workers > 1` on standard GIL-enabled Python on Linux/macOS, or when you pass `--topology shm`.
- **How it works**: The Rust HTTP server spawns separate Python worker processes and passes requests and responses through shared memory.

