Fivccliche

A production-ready, multi-user backend framework designed specifically for AI agents. Built with FastAPI and SQLModel for high-performance, type-safe async operations that handle concurrent AI agent requests at scale.

✨ Features

AI Agent Backend - Purpose-built for multi-user AI agent interactions and orchestration
FastAPI - Modern, fast web framework for building high-performance APIs with Python 3.11+
SQLModel - SQL ORM combining SQLAlchemy and Pydantic for type-safe database operations
Async/Await - Full async support for handling concurrent AI agent requests at scale
Type Safety - Built-in type hints with Pydantic 2.0 validation for reliable data handling
Multi-User Support - Designed for managing multiple AI agents with proper isolation and access control
Scheduled Tasks - APScheduler-based per-module scheduled job support, wired through IModule.mount
Testing - Pytest with async support for comprehensive test coverage
Code Quality - Black, Ruff, and MyPy configured for professional code standards
Package Management - uv for fast, reliable dependency management

🚀 Quick Start

Prerequisites

Python 3.11 or higher
uv package manager (install)

Installation

# Clone the repository
git clone https://github.com/MindFiv/FivcCliche.git
cd FivcCliche

# Install production dependencies
uv pip install -e .

# Or install with development tools
uv pip install -e ".[dev]"

Using the CLI

The easiest way to run FivcCliche is using the built-in CLI:

python -m fivccliche.cli migrate            # Create missing tables
python -m fivccliche.cli createsuperuser    # Interactive admin user
python -m fivccliche.cli run                # Start the server
python -m fivccliche.cli jobs list          # List scheduled jobs
python -m fivccliche.cli info               # Show project information
python -m fivccliche.cli clean              # Clean temporary files and cache

Visit http://localhost:8000/docs for interactive API documentation.

Configuration APIs

Authenticated users can manage user-scoped AI agent resources under /configs/. Superusers create global configs (user_uuid = null) that regular users can read but not update or delete.

/configs/embeddings/ - embedding provider/model configs
/configs/models/ - LLM provider/model configs with id, description, provider, model, api_key, base_url, temperature, max_tokens, optional nullable enable_thinking, user_uuid, updated_at, and updated_user_uuid fields. enable_thinking = null leaves provider behavior unchanged, true enables provider-supported thinking output, and false disables it.
/configs/agents/ - agent configs that compose models, tools, and skills
/configs/tools/ - tool configs, including MCP/function transports
/configs/skills/ - reusable skill configs and resources
/configs/questions/ - reusable user question configs with id, question, optional answer, is_active, user_uuid, updated_at, and updated_user_uuid fields; list with ?is_active=true or ?is_active=false to filter by active state

python -m fivccliche.cli migrate creates missing tables but does not alter existing tables. Existing databases created before user_llm.enable_thinking was added need a manual nullable boolean column on user_llm or a table rebuild. Existing databases created before chat.updated_at was added need:

ALTER TABLE chat ADD COLUMN updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW();
UPDATE chat SET updated_at = created_at;

CLI Options

# Custom host and port
python -m fivccliche.cli run --host 127.0.0.1 --port 9000

# Production mode (no auto-reload)
python -m fivccliche.cli run --no-reload

# Test configuration without running
python -m fivccliche.cli run --dry-run

# Verbose output
python -m fivccliche.cli run --verbose

📚 Documentation

For detailed information, see the documentation in the docs/ folder:

Getting Started - Install, migrate, run, and authenticate
Architecture - Module layering, ownership, HTTP CRUD
Scheduled Tasks - Per-module APScheduler integration
Agent Memories - Optional Hindsight memory API

🛠️ Development

CLI Commands

make format  # Format code with Black
make lint    # Lint with Ruff
make check   # Run all checks (format, lint, type check)

Run Tests

pytest
pytest -v --cov=src  # With coverage

Code Quality

black src/ tests/      # Format code
ruff check src/ tests/ # Lint code
mypy src/              # Type check

Project Structure

fivccliche/
├── pyproject.toml
├── src/fivccliche/
│   ├── cli.py
│   ├── services/
│   ├── utils/
│   ├── settings/
│   └── modules/
│       ├── users/
│       ├── agent_configs/
│       ├── agent_chats/
│       └── agent_memories/
├── tests/
└── docs/

📦 Dependencies

Production Core: FastAPI, SQLModel, Uvicorn, Pydantic, SQLAlchemy, APScheduler

CLI & Output: Typer, Rich, python-dotenv

Component System: fivcglue, fivcplayground

Development: Pytest, Black, Ruff, MyPy, Coverage

See pyproject.toml for complete dependency list and versions.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Charlie Zhang (sunnypig2002@gmail.com)

🔗 Links

Repository: https://github.com/MindFiv/FivcCliche
FastAPI: https://fastapi.tiangolo.com/
SQLModel: https://sqlmodel.tiangolo.com/
Pydantic: https://docs.pydantic.dev/

Metadata

Release files for fivccliche 0.1.102

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fivccliche 0.1.102
File	Size	Uploaded
fivccliche-0.1.102.tar.gz	168.3 kB	Sep 27, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for fivccliche 0.1.102
File	Interpreter	ABI	Platform	Reset
fivccliche-0.1.102-py3-none-any.whl 94.3 kB Sep 27, 2026	Python 3	none	any	Details

Total release size: 262.6 kB

Release files / fivccliche-0.1.102.tar.gz

Download URL	fivccliche-0.1.102.tar.gz
Size	168.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`e122a0db55c5db9919ec94105669996eec9dc129604cfc85f78f56c40b682011`
BLAKE2b-256 checksum How to use checksums	`bea1b4f69ca5eb6b2dd492081e648c4b36b807721f25cc6f923bddf7274e58cc`
Upload date	Sep 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.5.10`

Release files / fivccliche-0.1.102-py3-none-any.whl

Download URL	fivccliche-0.1.102-py3-none-any.whl
Size	94.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e68df9056fbed2fa2cda2554f916b9396f97794d06dd44b3875c69b448fd58db`
BLAKE2b-256 checksum How to use checksums	`71d8d88ef170c3625116275eca2d967b85279ebe8a1c5e1a5c61e23ec30dbbab`
Upload date	Sep 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.5.10`