1. Initialiser le projet

Objectif: créer le projet Arclith minimal, installer les dépendances et préparer les fichiers de base qui resteront dans le dépôt.

Depuis le dossier qui contiendra les projets de test:

mkdir -p ~/Perso/projets/demo-arclith
cd ~/Perso/projets/demo-arclith

uv tool upgrade arclith-cli
arclith-cli init

Répondre au prompt:

Projet (ex : my-recipe-service, meal-planner)
  Nom du projet: todo-list-service

Entrer dans le projet et installer les dépendances:

cd todo-list-service
uv sync

Le projet démarre avec repository: memory:

# config/adapters/adapters.yaml
logger: console
repository: memory
observability:
  enabled: []

Fichiers de base

Vérifier ou créer .gitignore:

.DS_Store
.idea/
.langgraph_api/
.playwright-cli/
__pycache__/
*.py[cod]
.venv/
.env
/secrets.yaml
.coverage
htmlcov/
.pytest_cache/
.mypy_cache/
.ruff_cache/
dist/
*.egg-info/

Créer README.md:

# Arclith POC Todo

POC Arclith montrant qu'un même coeur applicatif peut être exposé par FastAPI, FastMCP et LangGraph.

## Ce que le POC démontre

- `Todo`, `CreateTodoPort` et `ListTodosPort` restent dans le coeur métier.
- FastAPI adapte HTTP vers les ports inbound.
- FastMCP expose les mêmes use cases sous forme de tools MCP.
- LangGraph orchestre une conversation, mais appelle les mêmes ports que l'API et le MCP.
- Les intent-interpreters séparent la classification d'action (`TodoActionInterpreter`) de
  l'extraction de champs (`TodoConversationInterpreter`).
- Le runtime utilise MongoDB pour partager les données entre processus.
- Les tests utilisent une config `memory` temporaire pour rester rapides et déterministes.

## Installer

```bash
uv sync
uv run python -m pytest
```

## Lancer les tests

```bash
uv run python -m pytest
```

La suite de tests copie `config/` dans un dossier temporaire et remplace `repository: mongodb` par
`repository: memory`. Cela permet de tester le coeur, le MCP et l'agent sans démarrer MongoDB.

## Configurer MongoDB pour le runtime

`config/secrets.yaml` déclare le mapping attendu. Créez un fichier local `secrets.yaml` à la racine:

```yaml
adapters:
  mongodb:
    uri: "mongodb://arclith:arclith@127.0.0.1:27017/todo_list_service?authSource=admin"
```

Ce fichier est ignoré par Git.

## Lancer l'API

```bash
MODE=api uv run python main.py
```

Swagger:

```text
http://127.0.0.1:8120/docs
```

## Lancer le MCP

```bash
MODE=mcp_http uv run python main.py
```

Endpoint MCP:

```text
http://127.0.0.1:8121/mcp
```

## Lancer LangGraph

LM Studio doit exposer un serveur OpenAI-compatible sur `http://127.0.0.1:1234/v1`.

```bash
uv run langgraph dev --no-browser --allow-blocking --port 2024
```

Le graphe est déclaré dans `langgraph.json`:

```text
todo_agent -> src/todo_list_service/adapters/inbound/langgraph/agent.py:agent
```

Si Studio n'est pas accessible, ouvrir l'API locale:

```text
http://127.0.0.1:2024/docs
```

Les commandes `curl` de validation hors ligne sont regroupées dans
[Validation IA locale et hors ligne](../../learning/local-ai-validation.md).

## Découpage principal

```text
domain/models/todo.py
domain/ports/inbound/create_todo.py
domain/ports/inbound/list_todos.py
application/use_cases/create_todo.py
application/use_cases/list_todos.py
application/intent_interpreters/
adapters/inbound/fastapi/
adapters/inbound/fastmcp/
adapters/inbound/langgraph/
adapters/outbound/mongodb/
infrastructure/containers/todo_container.py
```

Le container est le seul endroit qui choisit le repository concret. Les adapters inbound ne parlent
qu'aux ports applicatifs.

La configuration applicative créée par le scaffold contient les fichiers suivants.

config/app.yaml:

name: todo-list-service
version: "0.1.0"
description: "todo-list-service — built with Arclith"

config/http.yaml:

idempotency:
  enabled: true
  ttl_seconds: 86400
  required: false

etag:
  enabled: true

cache_control:
  get_single_max_age: 300
  get_list_max_age: 60

config/soft_delete.yaml:

retention_days: 30

config/adapters/inbound/probe.yaml:

host: 0.0.0.0
port: 9000
enabled: true

Créer le marqueur de typage Python:

touch src/todo_list_service/py.typed

Les fichiers __init__.py vides sont conservés dans les packages pour garder des imports explicites:

touch src/todo_list_service/__init__.py
touch src/todo_list_service/adapters/__init__.py
touch src/todo_list_service/adapters/inbound/__init__.py
touch src/todo_list_service/adapters/outbound/__init__.py
touch src/todo_list_service/application/__init__.py
touch src/todo_list_service/domain/__init__.py
touch src/todo_list_service/domain/models/__init__.py
touch src/todo_list_service/domain/ports/__init__.py
touch src/todo_list_service/domain/ports/inbound/__init__.py
touch src/todo_list_service/domain/ports/outbound/__init__.py
touch src/todo_list_service/infrastructure/__init__.py
touch src/todo_list_service/infrastructure/containers/__init__.py
touch tests/__init__.py

Les sous-packages créés dans les étapes API, MCP, LangGraph et MongoDB ajoutent leurs propres __init__.py avec la même règle: fichier vide quand aucun export n'est utile, fichier explicite quand un import public doit être stabilisé.

Tester

Le scaffold minimal contient un test de bootstrap. Il sera ajusté dans l'étape MCP pour utiliser une configuration memory temporaire.

uv run python -m pytest

Voie rapide

uv tool upgrade arclith-cli
arclith-cli init todo-list-service
cd todo-list-service
uv sync
uv run python -m pytest

Étape suivante: créer l'entité Todo.