Metadata-Version: 2.4
Name: fivccliche
Version: 0.1.82
Summary: A modern async Python framework for building scalable applications with FastAPI and SQLModel
Author-email: Charlie Zhang <sunnypig2002@gmail.com>
Project-URL: Homepage, https://github.com/MindFiv/FivcCliche
Project-URL: Repository, https://github.com/MindFiv/FivcCliche.git
Project-URL: Issues, https://github.com/MindFiv/FivcCliche/issues
Keywords: fastapi,sqlmodel,async,orm,rest-api
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.104.0
Requires-Dist: sqlmodel>=0.0.14
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic[email]>=2.0.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: fivcplayground>=0.1.37
Requires-Dist: fivcplayground[strands]>=0.1.37
Requires-Dist: fivcplayground[chroma]>=0.1.37
Requires-Dist: fivcglue>=0.1.7
Requires-Dist: passlib[argon2]>=1.7.4
Requires-Dist: pyjwt>=2.10.1
Requires-Dist: greenlet>=3.2.4
Requires-Dist: python-cas>=1.7.1
Requires-Dist: fastapi-cdn-host>=0.9.3
Requires-Dist: pydantic-strict-partial>=0.6.2
Requires-Dist: apscheduler>=3.10.0
Requires-Dist: pg0-embedded>=0.15.0
Requires-Dist: asyncpg>=0.29.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: httpx>=0.25.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Dynamic: license-file

# 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.10+
- **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.10 or higher
- `uv` package manager ([install](https://docs.astral.sh/uv/))

### Installation

```bash
# 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:

```bash
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

```bash
# 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](docs/getting-started.md)** - Install, migrate, run, and authenticate
- **[Architecture](docs/architecture.md)** - Module layering, ownership, HTTP CRUD
- **[Scheduled Tasks](docs/scheduler.md)** - Per-module APScheduler integration
- **[Agent Memories](docs/agent-memories.md)** - Optional Hindsight memory API

## 🛠️ Development

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

### Run Tests
```bash
pytest
pytest -v --cov=src  # With coverage
```

### Code Quality
```bash
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](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/
