starfish-fl: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

Starfish-FL is an agentic federated learning (FL) framework organized as a mono repo with three components:

• controller/ — Django app installed on every site; handles local ML training, Celery task queuing, and a web UI (port 8001); includes optional LLM agent hooks (controller/starfish/controller/agent/) for per-round summaries, convergence detection, outlier flagging, and failure triage
• router/ — Django REST Framework app acting as central coordination server; manages global state, message forwarding, and artifact storage (port 8000); includes an embedded LLM agent module (router/starfish/agent/) for adaptive aggregation, smart scheduling, and failure triage
• cli/ — Typer-based CLI (starfish command) that replicates web portal functionality for human and AI agent use; includes an LLM agent module (cli/starfish_cli/agent/) for autonomous FL orchestration via Claude tool use, with an autonomous experiment mode that can analyze datasets, auto-select models, run experiments end-to-end, interpret results, and iteratively refine
• workbench/ — Docker Compose orchestration for running all components together in development

Commands

Development Setup (Full Stack)

cd workbench
make build          # Build all Docker images
make up             # Start all services (detached)
make stop           # Stop services
make down           # Stop and remove containers

First-time initialization after make up:

./init_db.sh        # Create PostgreSQL database
docker-compose exec -it router bash
# Inside container:
poetry run python3 manage.py migrate
poetry run python3 manage.py createsuperuser

Running Tests

# Router (inside container or local venv)
cd router && python3 manage.py test

# Controller
cd controller && python3 manage.py test

# Via Docker
docker exec -it starfish-router poetry run python3 manage.py test
docker exec -it starfish-controller poetry run python3 manage.py test

# CLI Agent tests
cd cli && poetry install --extras agent && poetry run pytest tests/ -v