🚀 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 with tachyon-engine (Experimental)

Tachyon API v1.0.0 includes adapter infrastructure for tachyon-engine, a Rust-powered ASGI implementation:

from tachyon_api import Tachyon, AsgiEngine

# Default: Stable Starlette engine (production-ready)
app = Tachyon()

# Experimental: Rust-powered engine (4-7x faster when complete)
app = Tachyon(engine=AsgiEngine.TACHYON)

Current Status: tachyon-engine v0.1.0 is experimental. Production default uses Starlette. See docs/tachyon-engine.md for details.

Performance Goals (when tachyon-engine v0.2.0+ is ready):

• 10x faster path matching
• 2-3x faster request processing
• 1.7x faster JSON serialization
• 2-4x overall throughput improvement

---

✨ Features

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

---

📚 Documentation

Complete documentation is available in the docs/ folder:

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
tachyon-engine	Rust engine (experimental)

---

🏦 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: demo@example.com / 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, "user@example.com")
    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
Serialization	msgspec + orjson	pydantic
Performance	⚡⚡⚡ Ultra-fast	⚡ Fast
Bundle Size	Minimal	Larger
Learning Curve	Easy (FastAPI-like)	Easy
Type Safety	Full	Full

---

📝 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 (git commit -m 'Add some amazing feature')
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 features:

• Response streaming
• GraphQL support
• More deployment guides
• Performance benchmarks

---

Built with 💜 by developers, for developers