GEMINI.md — FIM One Instructional Context

Project Overview

FIM One is an AI-powered Connector Hub that serves as a bridge between disjointed enterprise systems (ERP, CRM, OA, Databases) through autonomous AI agents.

Core Architecture

• Backend: FastAPI (Python 3.11+) asynchronous framework.
• Agent Core: ReAct reasoning loops and dynamic DAG planning with concurrent execution.
• Provider Agnostic: Protocol-first architecture using LiteLLM to support OpenAI, Anthropic, DeepSeek, Ollama, etc.
• RAG Pipeline: LanceDB vector store with hybrid retrieval (FTS + RRF) and reranking.
• Frontend: Next.js 15+ (App Router) with shadcn/ui and Tailwind CSS 4.
• Database: Dual-track support for SQLite (development) and PostgreSQL (production) via SQLAlchemy and Alembic.

Building and Running

Prerequisites

• Python 3.11+ with uv package manager.
• Node.js 18+ with pnpm.
• Docker (optional, for sandboxed code execution).

Key Commands

• Full Stack: ./start.sh portal (Production) or ./start.sh dev (Development with hot-reload).
• Backend Only: ./start.sh api or uv run uvicorn fim_one.web:create_app --factory --host 0.0.0.0 --port 8000.
• Frontend Only: cd frontend && pnpm dev.
• Database Migrations: uv run alembic upgrade head.
• Testing: uv run pytest.
• Linting/Formatting: ruff check src/ tests/ and mypy src/.

Development Conventions

Git & Workflow

• Atomic Commits: Unrelated changes must be split into separate commits.
• i18n Automation: Only edit English source files (messages/en/*.json, README.md, docs/*.mdx). Other languages are auto-translated on commit via scripts/translate.py.
• Worktrees: Agents must commit on their branch; merge via git merge, never file copying.
• Migrations: Worktree agents must NOT run alembic upgrade head; only write migration files. Migrations are applied after merging to main.

Backend (Python)

• Async First: Use async def for all I/O-bound operations.
• Type Safety: Mandatory type hints on all public functions.
• Migrations: All migrations must be idempotent and compatible with both SQLite and PostgreSQL (use helpers in fim_one.migrations.helpers).
• Boolean Defaults: Use server_default=sa.text("FALSE") or sa.text("TRUE") for PG compatibility.

Frontend (Next.js)

• i18n: Never hardcode English strings; use next-intl (useTranslations).
• UI Safety: Never rm -rf frontend/.next while dev server is running.
• Admin Tables: Follow the admin-users.tsx pattern: actions in a "..." DropdownMenu, Lucide icons for all menu items, destructive actions last.
• Dialogs: Use AlertDialog siblings for dirty state protection; avoid native confirm/alert.
• Styling: Prefer focus-visible:outline-* over ring-* to avoid clipping.

Project Structure

src/fim_one/
├── core/            # Agent logic (ReAct, Planner, Tools, RAG)
│   ├── agent/       # ReActAgent & Hook System
│   ├── workflow/    # DAG Engine & Node types
│   ├── model/       # LLM Providers & LiteLLM integration
│   └── tools/       # Base tools & Connector adapters
├── web/             # FastAPI App, API routes, and SSE endpoints
└── db/              # SQLAlchemy models & session management
frontend/            # Next.js Application
├── src/components/  # UI components (shadcn)
├── messages/        # i18n JSON files (en/ is source)
└── public/          # Static assets
docs/                # Documentation (Mintlify format)
tests/               # Comprehensive pytest suite