AGENTIC Backend Template

Production-ready FastAPI template for AI AGENTIC services.

This repository gives you a clean starting point for new backend services with:

• FastAPI application bootstrap
• structured logging with structlog
• environment-based settings via pydantic-settings
• SQLAlchemy foundation for database work
• ARQ worker setup for background jobs
• linting, testing, and pre-commit hooks

Stack

• Python 3.13
• FastAPI
• SQLAlchemy
• ARQ
• uv for dependency management
• pytest and ruff for quality checks

Project Structure

src/
  config.py                 # app settings
  logger.py                 # structured logging setup
  main.py                   # FastAPI app entrypoint
  middleware/               # shared request middleware
  db/                       # database base and engine utilities
  extensions/arq/           # background worker setup
  modules/                  # feature modules
  services/                 # service layer
  workflows/                # langgraph & other workflows
tests/
docs/

Quick Start

1. Create a local environment file:

cp .env.example .env

2. Install dependencies:

uv sync --extra dev

3. Install git hooks:

uv run pre-commit install

4. Start the API:

uv run uvicorn src.main:app --reload

The API will be available at http://localhost:8000.

Background Worker

Run the ARQ worker with:

uv run arq src.extensions.arq.arq_common.WorkerSettings

Common Commands

Run tests:

uv run pytest

Run lint:

uv run ruff check .

Format code:

uv run ruff format .

Environment Variables

The template includes .env.example with the default local setup:

ENVIRONMENT=development
APP_HOST=0.0.0.0
APP_PORT=8000
APP_NAME=Vita Backend
APP_VERSION=0.1.0
SERVICE_NAME=vita-backend
LOG_LEVEL=DEBUG
LOG_FORMAT=console
CONNECTION_STRING=
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=
ARQ_MAX_JOBS=50
ARQ_JOB_TIMEOUT=300
ARQ_KEEP_RESULT=3600

Health Endpoint

After startup, you can verify the service with:

curl http://localhost:8000/health

Expected response:

{"status":"ok"}

Notes

• The repository is configured as a GitHub template repository.
• Add your service-specific modules under src/modules/.
• Extend docs/overview.md when the service architecture becomes more specific.