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.

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/

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fivccliche-0.1.89.tar.gz (125.1 kB view details)

Uploaded Sep 4, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

fivccliche-0.1.89-py3-none-any.whl (70.4 kB view details)

Uploaded Sep 4, 2026 Python 3

File details

Details for the file fivccliche-0.1.89.tar.gz.

File metadata

Download URL: fivccliche-0.1.89.tar.gz
Upload date: Sep 4, 2026
Size: 125.1 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.5.10

File hashes

Hashes for fivccliche-0.1.89.tar.gz
Algorithm	Hash digest
SHA256	`659fa7a54b8cf50937055e5ceedff9599450e06dfa88ba6fc8dd77d06bb7b8ab`
MD5	`48705e79657ff27d9624ed7f4f56b15b`
BLAKE2b-256	`d16d2770e605fd9193dc5b14ad0cc9f78612e462915109d88e98af56db642be9`

See more details on using hashes here.

File details

Details for the file fivccliche-0.1.89-py3-none-any.whl.

File metadata

Download URL: fivccliche-0.1.89-py3-none-any.whl
Upload date: Sep 4, 2026
Size: 70.4 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.5.10

File hashes

Hashes for fivccliche-0.1.89-py3-none-any.whl
Algorithm	Hash digest
SHA256	`ed97766b700b3448cbcb27fe0dcc841944efe7b5c9c3544a03dcca9d24402df3`
MD5	`aa99097d6a10d04b028f5a15f25d1c0e`
BLAKE2b-256	`375b0f05aee70fc916c28d5a508aedf05b9f2b295f9e4c83c370e130fa6156eb`