ZodiacCore-Py

The opinionated, async-first core library for modern Python web services.

🎯 Mission

Stop copy-pasting your infrastructure code.

Every new FastAPI project starts the same way: setting up logging, error handling, database sessions, pagination... It's tedious, error-prone, and inconsistent across teams.

ZodiacCore solves this in two ways: a library you drop into any FastAPI app, and a CLI that scaffolds a full project so you can start coding in seconds.

✨ Key Features

• 🔍 Observability First: Built-in JSON structured logging with Trace ID injection across the entire request lifecycle (Middleware → Context → Log).
• 🛡️ Robust Error Handling: Centralized exception handlers that map ZodiacException to standard HTTP 4xx/5xx JSON responses.
• 💾 Database Abstraction: Async SQLAlchemy session management and BaseSQLRepository with pagination helpers (paginate_query).
• 🎁 Standard Response Wrapper: Automatic wrapping of API responses into code / data / message via APIRouter.
• 📄 Standard Pagination: PageParams and PagedResponse[T] with repository integration.
• ⚡ Async Ready: Python 3.12+ async/await from the ground up.
• ⌨️ zodiac CLI: Scaffold a 3-tier FastAPI project (DI, routers, config) with one command.

📦 Quick Install

Extras (combinable): zodiac-core[sql] (SQLModel), zodiac-core[mongo] (Motor, helpers planned), zodiac-core[zodiac] (CLI). See the Installation Guide for details.

🚀 Two ways to use ZodiacCore

1. Scaffolding (fastest start)

Use the zodiac CLI to generate a full project: 3-tier architecture, dependency injection, config, and tests.

Note: dfd-service below is the name of the new project you want to create; replace it with your own.

mkdir dfd-service
cd dfd-service
uv init --python 3.12

uv add "zodiac-core[zodiac,sql]"
zodiac new dfd-service --tpl standard-3tier -o .. --force

uv add "fastapi[standard]" --dev
uv run fastapi run --reload

Open http://127.0.0.1:8000/docs and http://127.0.0.1:8000/api/v1/health. See Getting started and CLI docs.

2. Library (use in your own app)

Add zodiac-core to an existing FastAPI project and wire up logging, middleware, and response wrapping.

from fastapi import FastAPI
from loguru import logger
from zodiac_core.exception_handlers import register_exception_handlers
from zodiac_core.exceptions import NotFoundException
from zodiac_core.logging import setup_loguru
from zodiac_core.middleware import register_middleware
from zodiac_core.routing import APIRouter

setup_loguru(level="INFO", json_format=True)
app = FastAPI()
register_middleware(app)
register_exception_handlers(app)

router = APIRouter()


@router.get("/items/{item_id}")
async def read_item(item_id: int):
    logger.info(f"request: item_id={item_id}")
    if item_id == 0:
        raise NotFoundException(message="Item not found")
    return {"item_id": item_id}


app.include_router(router)

📚 Documentation

• Online: https://ttwshell.github.io/ZodiacCore-Py/ (multiple versions via release).
• Local: make docs-serve (sources in docs/).
• Developer skills: reusable agent skills live in skills/. Install them into a service project's .agents/skills/ directory. Use zodiac-docs for version-aware framework guidance and zodiac-core-integration-summary for adoption audits (zodiac check --format json supplies mechanical wiring evidence). See the skills guide.

🤝 Contributing

Contributions are welcome. Please read CONTRIBUTING.md for development setup and workflow.

📄 License

This project is licensed under the MIT License.