tachyon-api 1.0.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

Scenario	FastAPI	Tachyon	Speedup
Hello World	10,283 req/s	40,545 req/s	3.94x
Path + query params	7,133 req/s	30,637 req/s	4.30x
Body validation (Struct)	8,336 req/s	31,808 req/s	3.82x
Nested body (complex Struct)	8,006 req/s	30,807 req/s	3.85x
Response model serialization	6,673 req/s	34,991 req/s	5.24x
Header param + auth	8,662 req/s	34,126 req/s	3.94x
Dependency injection	6,225 req/s	32,941 req/s	5.29x
Multiple query params	6,242 req/s	25,915 req/s	4.15x
Total throughput	61,560 req/s	261,770 req/s	4.25x

Latency: ~3ms (Tachyon) vs ~14ms (FastAPI) on average.

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

Why is Tachyon faster?

• Endpoint pre-compilation — inspect.signature(), isinstance chains, type resolution, and msgspec.Decoder creation run once at startup, not per request
• msgspec — validation and deserialization in C, 5–10x faster than Pydantic
• Direct serialization — Struct responses use msgspec.json.encode() directly (no Python intermediate step)
• Minimal response overhead — custom response class bypasses Starlette's MutableHeaders construction
• 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 new project
tachyon new my-api

# Generate module
tachyon generate service users --crud

# Code quality
tachyon lint all

👉 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	~262k req/s total	~62k req/s total
Latency	~3ms avg	~14ms avg
Serialization	msgspec + orjson	Pydantic v2
Request compilation	Once at startup	Per request
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