🚀 Tachyon API

A lightweight, high-performance API framework for Python with the elegance of FastAPI and the speed of light.

Tachyon API combines the intuitive decorator-based syntax you love with minimal dependencies and maximal performance. Built with Test-Driven Development from the ground up, it offers a cleaner, faster alternative with full ASGI compatibility.

🚀 Quick Start

from tachyon_api import Tachyon, Struct, Body, Query

app = Tachyon()

class User(Struct):
    name: str
    email: str

@app.get("/")
def hello():
    return {"message": "Tachyon is running at lightspeed!"}

@app.post("/users")
def create_user(user: User = Body()):
    return {"created": user.name}

@app.get("/search")
def search(q: str = Query(...), limit: int = Query(10)):
    return {"query": q, "limit": limit}

pip install tachyon-api
tachyon run                 # uvloop + httptools + reload, served at :8000

📖 Docs: http://localhost:8000/docs

⚡ Performance

Benchmarked against FastAPI 0.136.1 (Pydantic v2) · 1 worker · 100 concurrent connections · uvloop + httptools · precompiled Cython extensions (shipped by default — see below)

Latency: ~2.3ms (Tachyon) vs ~13ms (FastAPI) on average.

Benchmark code in benchmark/. Run with bash benchmark/run_benchmark.sh.

Precompiled wheels — zero setup

pip install tachyon-api ships prebuilt wheels with all 27 Cython extensions already compiled for:

No manual build step. No Cython required. The numbers above are what you get out of the box.

Not on the list? (macOS Intel, Alpine, etc.) pip falls back to the sdist and compiles from .pyx source — requires a C compiler and pip install tachyon-api[fast] (which pulls in Cython). If compilation fails, the framework still works: runtime falls back to the pure-Python siblings of every .pyx module automatically.

Compiled vs pure-Python delta

Same code, same workload — the only difference is whether the 27 Cython .so extensions are loaded:

The biggest wins concentrate on real framework work — DI resolution (+18.3%), path/query parsing (+17.9%), response model (+17.1%), and validation (+13–15%). Hello-world barely moves (+3.9%): the framework is already a tiny slice of that request.

Why is Tachyon faster?

• Radix trie routing — O(k) path matching vs Starlette's O(N×regex) scan; trie compiled to C
• Middleware bypass — HTTP requests skip Starlette's ServerErrorMiddleware and ExceptionMiddleware entirely; exceptions handled directly in each closure
• Endpoint pre-compilation — inspect.signature(), isinstance chains, type resolution, and msgspec.Decoder creation run once at startup, not per request
• No-Request fast path — endpoints with no parameters skip Request() creation and call the ASGI handler directly
• msgspec — validation and deserialization in C, 5–10x faster than Pydantic
• Direct serialization — Struct responses use msgspec.json.encode() directly (no Python intermediate step)
• Pre-built ASGI dicts — response send payloads constructed once in __init__, not recreated per request
• No middleware bloat — Tachyon mounts only what you register; FastAPI adds ~15 middlewares by default

✨ Features

📚 Documentation

🏦 Example: KYC Demo API

A complete example demonstrating all Tachyon features is available in example/:

cd example
pip install -r requirements.txt
tachyon run example.app:app

The KYC Demo exercises every v1.2.x feature:

• 🔐 JWT Authentication + API Keys
• 👤 Customer CRUD + bulk endpoint (Body(List[Struct]))
• 📋 KYC Verification with Background Tasks
• 📁 Document Uploads (multipart/form-data)
• 🌐 WebSocket — legacy plain-string + modern DI-injected with room_id: uuid.UUID
• 💉 DI scopes — singleton (services), request (correlation context), transient (ID generator)
• 🛡️ Security headers + opt-in CORS allow-list
• 🚨 Custom exception handler for the KYCException hierarchy
• 🧪 17 tests (pytest example/tests/), including async tests via create_client

Demo credentials: demo@example.com / demo123

👉 See example/README.md for full details.

🔌 Core Dependencies

🏛️ Architecture

Tachyon's request hot path is a thin chain of composed collaborators — every piece is single-responsibility and ready for Cython compilation:

client
  │
  ├─→ Tachyon.__call__ (ASGI entry — sets scope["app"])
  │     │
  │     ├─→ ASGIEntry         lazy build of HTTP app
  │     │
  │     ├─→ HTTPDispatcher    HTTP → trie  ·  WS/lifespan → Starlette
  │     │
  │     ├─→ MiddlewareStack   user-registered middlewares (CORS, Security…)
  │     │
  │     └─→ TachyonDispatcher (Cython cdef)  ← radix trie match O(k)
  │           │
  │           ├─→ _ASGIHandler (no-param fast path, 2 sends only)
  │           │
  │           └─→ handler closure
  │                 ├─→ ParameterPipeline → 8 atomic extractors
  │                 │     (body / query / query-list / header / cookie / form / file / path)
  │                 ├─→ DependencyResolver → OverrideLookup / ScopeCache /
  │                 │                        ClassFactory / CallableFactory
  │                 ├─→ ResponseProcessor (msgspec encode if Struct)
  │                 └─→ ExceptionTable (walks subclass handlers)
  │
  └─→ TachyonJSONResponse | TachyonBytesResponse | _InternalErrorResponse
        (pre-built ASGI dicts, zero extra allocations per response)

The v1.2.x SRP refactor decomposed the monolithic hot path into atomic modules with __slots__ and full type hints — direct cdef class candidates. The v1.2.9 Cython sprint then compiled 27 of them to .so, keeping every .py sibling as a transparent fallback (Python prefers .so automatically).

👉 Full architecture documentation

💉 Dependency Injection

from tachyon_api import injectable, Depends

@injectable                       # singleton (default) — one per app
class DB:
    def __init__(self):
        self.pool = "..."

@injectable(scope="request")      # one per HTTP request
class RequestContext:
    def __init__(self):
        import uuid
        self.correlation_id = str(uuid.uuid4())

@injectable(scope="transient")    # new instance every time it's injected
class IdGenerator:
    def __init__(self):
        self._seq = 0

@app.get("/users/{id}")
def get_user(id: str, db: DB = Depends(), ctx: RequestContext = Depends()):
    return {"id": id, "trace": ctx.correlation_id}

👉 Full DI documentation

🔐 Security

from tachyon_api.security import HTTPBearer, OAuth2PasswordBearer

bearer = HTTPBearer()

@app.get("/protected")
async def protected(credentials = Depends(bearer)):
    return {"token": credentials.credentials}

👉 Full Security documentation

⚡ Background Tasks

from tachyon_api.background import BackgroundTasks

@app.post("/notify")
def notify(background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email, "user@example.com")
    return {"status": "queued"}

👉 Full Background Tasks documentation

🌐 WebSockets

import uuid
from tachyon_api import injectable, Depends

@injectable
class RoomBroadcaster:
    async def join(self, ws, room_key: str): ...

@app.websocket("/ws/rooms/{room_id}")           # typed UUID path param
async def room(
    websocket,
    room_id: uuid.UUID,                          # auto-converted; 1008 on mismatch
    broadcaster: RoomBroadcaster = Depends(),    # @injectable DI in WS
):
    await broadcaster.join(websocket, str(room_id))
    while True:
        await websocket.send_json({"room": str(room_id)})

👉 Full WebSockets documentation

🔧 CLI Tools

# Create project (generates .env.example, config.py with dotenv, clean arch)
tachyon new my-api

# Start development server (uvloop + httptools auto-detected, reload on)
tachyon run

# List all registered routes
tachyon routes

# Generate a full CRUD module
tachyon g service users --crud

# Generate an ASGI middleware skeleton
tachyon g middleware auth

# Code quality
tachyon lint all

Name validation: hyphens auto-converted to underscores (my-api → my_api), Python keywords rejected with a clear error.

AI Agent Integration

Teach your AI coding assistant (Claude Code, Cursor, Copilot, OpenCode, Codex) how to write correct Tachyon code:

tachyon install-skill              # generates context files for all tools
tachyon install-skill --cursor     # only .cursorrules
tachyon install-skill --claude     # only CLAUDE.md
tachyon install-skill --copilot    # only .github/copilot-instructions.md

Installs knowledge about Body() requirement, Struct vs BaseModel, DI patterns, CLI commands, and anti-patterns. Safe to run multiple times.

👉 Full CLI documentation

🧪 Testing

# Sync — Starlette TestClient compatible
from tachyon_api.testing import TachyonTestClient

def test_hello():
    client = TachyonTestClient(app)
    assert client.get("/").status_code == 200


# Async — httpx.AsyncClient over ASGI transport
import pytest
from tachyon_api.testing import create_client

@pytest.mark.asyncio
async def test_hello_async():
    async with create_client(app, headers={"X-Trace": "abc"}) as client:
        response = await client.get("/")
        assert response.status_code == 200

pytest tests/ -v

👉 Full Testing documentation

📊 Why Tachyon?

📝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (pytest tests/ -v)
4. Commit your changes
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

📜 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

🔮 What's Next

See CHANGELOG.md for version history.

Upcoming:

• Response streaming
• GraphQL support
• Multi-worker benchmarks
• Benchmark suite vs Litestar / BlackSheep / Robyn
• SQLAlchemy async integration guide

Built with 💜 by developers, for developers