tachyon-api 1.2.0

A lightweight, FastAPI-inspired web framework

🚀 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
uvicorn app:app --reload

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

---

⚡ Performance

Benchmarked against FastAPI 0.136.1 (Pydantic v2) · 1 worker · 100 concurrent connections · uvloop + httptools · Cython extensions compiled

Scenario	FastAPI	Tachyon	Speedup
Hello World	10,378 req/s	49,521 req/s	4.77x
Path + query params	7,294 req/s	37,991 req/s	5.21x
Body validation (Struct)	8,533 req/s	41,507 req/s	4.86x
Nested body (complex Struct)	8,205 req/s	40,816 req/s	4.97x
Response model serialization	6,766 req/s	47,777 req/s	7.06x
Header param + auth	8,705 req/s	46,013 req/s	5.29x
Dependency injection	6,491 req/s	46,940 req/s	7.23x
Multiple query params	6,325 req/s	34,481 req/s	5.45x
Total throughput	62,697 req/s	345,046 req/s	5.50x

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

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

Optional: Cython compilation

Install with Cython extensions for additional speedup on the request hot path:

pip install tachyon-api[fast]          # installs cython dependency
python setup.py build_ext --inplace    # compile extensions (required step)

Note: pip install tachyon-api[fast] installs the cython package but does not auto-compile the extensions. Run python setup.py build_ext --inplace manually after install. Falls back to pure Python automatically when .so is not present — no code changes needed. Numbers above reflect the compiled version (~11% faster Python hot path).

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

Category	Features
Core	Decorators API, Routers, Middlewares, ASGI compatible
Parameters	Path, Query, Body, Header, Cookie, Form, File (all with alias=)
Validation	msgspec Struct (ultra-fast), automatic 422 errors, body size limit
DI	@injectable (implicit), Depends() (explicit), circular dep detection
Security	HTTPBearer, HTTPBasic, OAuth2, API Keys
Async	Background Tasks, WebSockets
Performance	orjson serialization, @cache decorator, endpoint pre-compilation
Docs	OpenAPI 3.0, Scalar UI, Swagger, ReDoc (XSS-safe HTML generation)
CLI	Project scaffolding, code generation, linting
Testing	TachyonTestClient, dependency_overrides

---

📚 Documentation

Guide	Description
Getting Started	Installation and first project
Architecture	Clean architecture patterns
Dependency Injection	@injectable and Depends()
Parameters	Path, Query, Body, Header, Cookie, Form, File
Validation	msgspec Struct validation
Security	JWT, Basic, OAuth2, API Keys
Caching	@cache decorator
Lifecycle Events	Startup/Shutdown
Background Tasks	Async task processing
WebSockets	Real-time communication
Testing	TachyonTestClient
CLI Tools	Scaffolding and generation
Request Lifecycle	How requests are processed
Migration from FastAPI	Migration guide
Best Practices	Recommended patterns

---

🏦 Example: KYC Demo API

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

cd example
pip install -r requirements.txt
uvicorn example.app:app --reload

The KYC Demo implements:

• 🔐 JWT Authentication
• 👤 Customer CRUD
• 📋 KYC Verification with Background Tasks
• 📁 Document Uploads
• 🌐 WebSocket Notifications
• 🧪 12 Tests with Mocks

Demo credentials: [e-mail] / demo123

👉 See example/README.md for full details.

---

🔌 Core Dependencies

Package	Purpose
starlette	ASGI framework
msgspec	Ultra-fast validation/serialization
orjson	High-performance JSON
uvicorn	ASGI server

---

💉 Dependency Injection

from tachyon_api import injectable, Depends

@injectable
class UserService:
    def get_user(self, id: str):
        return {"id": id}

@app.get("/users/{id}")
def get_user(id: str, service: UserService = Depends()):
    return service.get_user(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, "[e-mail]")
    return {"status": "queued"}

👉 Full Background Tasks documentation

---

🌐 WebSockets

@app.websocket("/ws")
async def websocket(ws):
    await ws.accept()
    data = await ws.receive_text()
    await ws.send_text(f"Echo: {data}")

👉 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

from tachyon_api.testing import TachyonTestClient

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

pytest tests/ -v

👉 Full Testing documentation

---

📊 Why Tachyon?

Feature	Tachyon	FastAPI
Throughput	~336k req/s total	~60k req/s total
Latency	~2.1ms avg	~14ms avg
Routing	Radix trie O(k)	Regex scan O(N)
Serialization	msgspec + orjson	Pydantic v2
Request compilation	Once at startup	Per request
Middleware overhead	User-only stack	+2 auto middleware layers
Bundle size	Minimal (4 deps)	Larger (~15 deps)
Learning curve	Easy (FastAPI-like)	Easy
Type safety	Full (msgspec Struct)	Full (Pydantic)

---

📝 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

---

Built with 💜 by developers, for developers