Adaptive AI assistant for French freelancers and small business owners.
Kameleon guides users from zero — through a conversational onboarding — to a personalized dashboard powered by an AI that understands their situation, pain points and goals.
| Layer | Technology |
|---|---|
| Backend | Python 3.14, FastAPI, Uvicorn, SSE (sse-starlette) |
| Agent SDK | Strands Agents |
| AI | Mistral AI (API) |
| Database | SQLite |
| Frontend | React 19, Vite 7, React Router DOM 7 |
| Web search | Brave Search API |
- Python 3.14+ with
venv - Node.js 18+
- A Mistral API key
# Backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Frontend
cd frontend && npm install && cd ..Create a .env file at the project root:
MISTRAL_API=sk-...
BRAVE_API_KEY=BSA... # optional, for web search# Normal mode — starts backend + frontend, opens the browser
./scripts/start.sh
# Auto mode — resets the DB, runs the full LLM-driven onboarding test
./scripts/start.sh auto
# Resume mode — keeps the DB, reopens the dashboard directly
./scripts/start.sh resumeBackend runs on http://localhost:8000, frontend on http://localhost:5173.
Kameleon uses three multi-agent patterns from the Strands Agents SDK, chosen to match the needs of each phase.
Used in onboarding_workflow.py. Each step is an independent Strands Agent. The output of one step is injected as context into the next (context passing). All outputs are validated by Pydantic schemas before moving on.
Profile → [Agent: Analyst] → analysis → [Agent: Tool Mapper] → mapping → [Agent: Roadmap Builder] → roadmap → [Deterministic: UI Builder] → dock
This is a pure pipeline: no routing, no branching — just sequential chain with structured JSON handoff between agents.
Used in orchestrator.py. The main orchestrator owns sub-agents declared as @tool. Each sub-agent is a standalone Strands Agent with its own model, system prompt and tools. The orchestrator decides which sub-agent to call based on the user's intent.
User → [Orchestrator] → selects @tool → [Sub-agent: budget_agent] → DB operation → response
→ selects @tool → [Sub-agent: crm_agent] → DB operation → response
→ calls direct tool → [propose_choices] → HITL event
No Swarm, no remote A2A protocol — everything is local, synchronous, in-process.
Used in specialist_juridique.py and financial_swarm.py. These are independent agents with their own tool sets, not embedded in the orchestrator's tool list (the financial agent is the exception — it is also declared as @tool on the orchestrator, but internally it creates its own agent with its own tools).
The legal specialist lives in a separate chat panel with its own conversation history, completely independent from the main orchestrator.
The onboarding agent leads a natural conversation in 4-7 exchanges to collect the user's profile.
| Step | What happens | Model |
|---|---|---|
| Welcome | The agent introduces itself, asks the user to pick its name (Andy or Lisa) | mistral-large-2512 |
| Collection | First name, business activity, experience level, current situation, blockers, goals | mistral-large-2512 |
| Trigger | Once minimum data is collected, the agent emits [READY_FOR_PLAN] + a JSON profile |
mistral-large-2512 |
Why mistral-large here? Onboarding requires conversational nuance, empathy and the ability to produce a clean JSON at the end of the collection.
Once the profile is collected, 4 automatic steps run server-side. The frontend displays an animated stepper.
| Step | What happens | Model | Why this model |
|---|---|---|---|
| Profile analysis | Situation summary + 4-8 prioritized objectives (urgency/impact) | magistral-medium-2509 |
Structured reasoning, JSON output validated by Pydantic |
| Tool mapping | Each objective is assigned to a dashboard tool type | magistral-medium-2509 |
Same analytical logic, context enriched by the previous step |
| Roadmap generation | SMART objective + 3-5 phases with concrete actions | magistral-medium-2509 |
Structured planning, consistency with previous steps |
| UI construction | Dynamic activation of dock components | Deterministic (no LLM) | Pure logic: translates the mapping into UI events |
Each workflow step uses an externalized prompt (backend/agents/prompts/*.txt) and passes its result as context to the next step.
| What happens | Model | Why |
|---|---|---|
| Generates personalized descriptions for each activated tool | ministral-8b-2512 |
Simple copywriting task, 8B is more than enough and cheaper |
The user lands on their dashboard with a macOS-style dock. All conversation goes through the orchestrator.
Main orchestrator
| Component | Model | Role |
|---|---|---|
| Orchestrator (Marc) | mistral-large-2512 |
Understands intent, routes to the right sub-agent, manages dialogue |
Sub-agents (declared as @tool on the orchestrator)
| Sub-agent | Model | Tools | Domain |
|---|---|---|---|
objectifs_agent |
magistral-small-2509 |
manage_objectifs |
Goal tracking |
budget_agent |
magistral-small-2509 |
manage_budget |
Budget forecasting |
admin_agent |
magistral-small-2509 |
manage_admin |
Administrative checklist |
calendar_agent |
magistral-small-2509 |
manage_calendar |
Action calendar |
roadmap_agent |
magistral-small-2509 |
manage_roadmap |
Action plan tracking |
crm_agent |
mistral-large-2512 |
manage_crm, display_data_table |
Clients and invoicing |
financial_agent |
magistral-medium-2509 |
web_search, manage_crm, manage_previsions |
Financial forecasting |
Why this model hierarchy?
magistral-smallfor simple sub-agents (CRUD + formatting) — fast and cost-effectivemagistral-mediumfor tasks requiring reasoning (finance, analysis)mistral-largefor the orchestrator (complex routing) and CRM (rich data, tables)
Direct orchestrator tools (not sub-agents)
| Tool | Function |
|---|---|
propose_choices |
Displays clickable buttons in the chat (HITL) |
display_data_table |
Renders a data table inline |
suggest_specialist_chat |
Makes a dock icon bounce to redirect to a specialist |
activate_dock_component |
Dynamically adds a tool to the dock |
manage_statut_juridique |
Read/update legal status |
| Component | Model | Tools |
|---|---|---|
| Legal agent | magistral-medium-2509 |
web_search, manage_statut_juridique |
Accessible via the "Chat" dock icon. Lives in its own panel, independent from the orchestrator.
| Tool | Description |
|---|---|
| My Goals | Prioritized objectives from onboarding, progress tracking |
| Clients & Invoicing (CRM) | Client management, invoices, overdue reminders, raw invoice import |
| Administrative Checklist | Checkable to-do list for administrative tasks |
| Action Calendar | Events, deadlines, action dates |
| Budget Forecast | Expenses, revenue, projected balance |
| Plan Roadmap | Phase-by-phase action plan with SMART objective |
| Financial Forecasts | Target revenue, contributions, daily rate, remaining missions |
| Talk to a Specialist | Dedicated chat with the legal agent |
backend/
agents/
orchestrator.py # Main orchestrator — "Agents as Tools" pattern
onboarding_chat.py # Conversational onboarding agent
onboarding_workflow.py # Sequential workflow — context passing pattern
financial_swarm.py # Financial forecasting agent (standalone + @tool)
specialist_juridique.py # Legal specialist — standalone agent
invoice_parser.py # Invoice JSON normalizer (8B)
models.py # Pydantic schemas (AgentResponse, PlanPhase, etc.)
prompts/ # Externalized system prompts (.txt)
models/
magistral.py # Magistral wrapper (filters thinking tokens)
routes/
chat_init.py # GET /chat/init — first onboarding message
chat_onboarding.py # POST /chat/onboarding — sequential workflow
chat_stream.py # POST /chat/stream — main streaming endpoint
chat_common.py # Session and history helpers
tools.py # REST CRUD for all dashboard tools
session/
db.py # SQLite — table creation and queries
manager.py # In-memory session cache
tools/ # Strands tools (@tool) for agents
objectifs.py, crm.py, budget.py, admin.py,
calendar.py, roadmap.py, previsions.py,
profil.py, interaction.py, ui_components.py,
web_search.py
middleware/
subdomain.py # Subdomain routing (multi-tenant)
config.py # Model constants and configuration
main.py # FastAPI entry point
frontend/
src/
App.jsx # React routes
components/
WelcomePage.jsx # Landing page
ChatView.jsx # Onboarding chat view
PersonalAssistant.jsx # Full post-onboarding dashboard
Dock.jsx # macOS-style dock
ToolPanel.jsx # Individual tool panel container
Header.jsx # Navigation header
ChatInput.jsx # User input field
MessageBubble.jsx # Chat message rendering
ToolShowcase.jsx # Onboarding tool presentation
TypingIndicator.jsx # Loading indicator
ComponentRegistry.js # Dynamic tool component registry
tools/ # Individual tool components
ObjectifsTool.jsx, CRMTool.jsx, BudgetTool.jsx,
AdminTool.jsx, CalendarTool.jsx, RoadmapTool.jsx,
PrevisionsTool.jsx, ChatTool.jsx
hooks/
useChat.js # SSE streaming hook
useSession.js # Session management hook
useSubdomain.js # Subdomain detection hook
styles/ # CSS
scripts/
start.sh # Launch (normal / auto / resume)
01_first_step_onboarding.py # Auto test: LLM plays the user
02_second_step_plan.py # Auto test: triggers the workflow
run_full_flow_test.py # End-to-end flow test
run_full_flow_test.sh # E2E test runner script
run_full_onboarding.sh # Full onboarding runner
run_onboarding_test.sh # Onboarding test runner
test_scenario_sophie.py # Onboarding scenario test
test_tools_plan.py # Tool mapping test
seed_roadmap.py # Roadmap data seeding
| Model | Size | Used for |
|---|---|---|
mistral-large-2512 |
Large | Orchestrator, onboarding, CRM |
magistral-medium-2509 |
Medium | Workflow (analysis, mapping, roadmap), finance, legal specialist |
magistral-small-2509 |
Small | Simple sub-agents (goals, budget, admin, calendar, roadmap) |
ministral-8b-2512 |
8B | Tool descriptions, invoice parsing |
ministral-3b-2512 |
3B | Available, not currently used |
ministral-14b-2512 |
14B | Available, not currently used |