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 -
uvfor fast, reliable dependency management
🚀 Quick Start
Prerequisites
- Python 3.11 or higher
uvpackage 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 exec users createsuperuser # Interactive admin user
python -m fivccliche.cli serve # 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 withid,description,provider,model,api_key,base_url,temperature,max_tokens, optional nullableenable_thinking,user_uuid,updated_at, andupdated_user_uuidfields.enable_thinking = nullleaves provider behavior unchanged,trueenables provider-supported thinking output, andfalsedisables 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 withid,question, optionalanswer,is_active,user_uuid,updated_at, andupdated_user_uuidfields; list with?is_active=trueor?is_active=falseto 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 serve --host 127.0.0.1 --port 9000
# Production mode (no auto-reload)
python -m fivccliche.cli serve --no-reload
# Test configuration without running
python -m fivccliche.cli serve --dry-run
# Verbose output
python -m fivccliche.cli serve --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/
1 maintainer
Metadata
1 maintainer
Release files for fivccliche 0.1.115
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| fivccliche-0.1.115.tar.gz | 178.3 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| fivccliche-0.1.115-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 280.6 kB
Release files / fivccliche-0.1.115.tar.gz
| Download URL | fivccliche-0.1.115.tar.gz |
|---|---|
| Size | 178.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
55c62147f5707a704fca267c57e573daad3b6aaa9e92318bd189bb8752ca893e
|
|
BLAKE2b-256 checksum How to use checksums |
e3506478167f7f1c575f0769f6ad4c84564ed7ef79c6adbdab03bcf50a28fecc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.5.10
|
Release files / fivccliche-0.1.115-py3-none-any.whl
| Download URL | fivccliche-0.1.115-py3-none-any.whl |
|---|---|
| Size | 102.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
276a4c213e4cda7dfc9a2a9030632612894690486649986a49e20841fdacffd2
|
|
BLAKE2b-256 checksum How to use checksums |
5c0400b16ac003cc09954be1bb4499c991470d6021c12ae8749834cd76c14204
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.5.10
|
Security for fivccliche 0.1.115
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
