awesome-agentic-ai/HOWTO_BACKEND.md

🧱 Backend Development Guide

1. Project Setup & Structure

📁 Folder Structure

Ensure your project structure reflects the latest architecture (Phase 8):

agentic-ai/
├── main.py                 # FastAPI entry point
├── config.py               # Configuration (OFFLINE_MODE, LLM_ENGINE)
├── requirements.txt        # Python dependencies
├── cli/
│   └── main.py             # CLI entry point
├── agents/                 # Agent definitions
│   ├── agent_core.py       # Orchestrator & Persona Logic
│   ├── planner_agent.py
│   ├── executor_agent.py
│   └── ...
├── models/                 # Model Infrastructure
│   ├── registry.py         # ModelRegistry
│   ├── model_router.py     # Capability-based Router
│   ├── telemetry.py        # UsageTracker (SQLite)
│   ├── tone_engine.py      # ToneEngine (Persona templates)
│   └── ...
├── data/
│   └── telemetry.db        # Usage logs (SQLite)
├── web/                    # React Frontend
│   └── ...
└── ...

---

2. Environment Setup

🐍 Virtual Environment (Recommended)

This project requires Python 3.10+. Always use a virtual environment to avoid conflicts with system packages.

cd agentic-ai
python3 -m venv venv
source venv/bin/activate

📦 Install Dependencies

Install all required packages, including the new community providers and cryptography support:

pip install --upgrade pip
pip install -r requirements.txt

Note: Key dependencies include fastapi, uvicorn, langchain, langchain-community, python-jose[cryptography], pydantic.

🛠️ System Tools (Linux)

sudo apt update
sudo apt install ffmpeg portaudio19-dev

---

3. Configuration

🔧 config.py

The system behavior is controlled by config.py. Key settings include:

• OFFLINE_MODE: Set to True to force usage of local models (ollama, llama.cpp) and disable external APIs.
• LLM_ENGINE: Default engine to use (e.g., ollama, vllm).

🎭 Persona & Tone

• config/persona_presets.py: Define persona traits and branding.
• models/tone_engine.py: Manages tone templates. To add a new tone, update the templates in this file.

---

4. Running the Backend

🚀 Start FastAPI Server

# Make sure venv is active
uvicorn main:app --reload

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

🖥️ Run CLI

python cli/main.py

---

5. Telemetry & Analytics (Phase 7)

The system tracks usage locally in SQLite.

• Database: data/telemetry.db
• Table: usage_logs
• Logged Data: usage tokens, latency, cost estimates, model aliases.

To inspect logs:

sqlite3 data/telemetry.db "SELECT * FROM usage_logs ORDER BY id DESC LIMIT 5;"

---

---

7. Crew & Collective AI (Phase 11)

Phase 11 introduces multi-agent orchestration and cross-platform sync.

🚀 New Routes

• /api/crew/trust-scores: Real-time reliability scores for all active agents.
• /api/crew/active-treaties: Persistent agreements negotiated via the Diplomacy Protocol.
• /admin/notify/register: Endpoint for native clients to subscribe to system alerts.

🛡️ Reliability & Mocking

• Google Calendar: If credentials.json is missing, the system fallbacks to a MockCalendarService to prevent startup failure.
• Memory Management: The MemoryManager is now instantiated globally in memory/memory_manager.py as memory to ensure consistent session state across all routes.