AGENTS

MILTON.Clustering Service Context

You are working in the MILTON.Clustering service — the code analysis and architectural clustering microservice.

Responsibilities

• Static code analysis: Tree-sitter AST parsing, module detection, Leiden community detection.
• Python FastAPI microservice performs the actual analysis over shared volume repository paths.
• C# FastEndpoints proxy endpoints in MILTON/Features/Clustering/ orchestrate calls from the React client, manage caching, and drive optional LLM-powered cluster naming.

Owned Paths

• MILTON.Clustering/src/ — Python FastAPI service
• MILTON/Features/Clustering/ — C# proxy endpoints in the main API

Key Technologies & Architecture

• Python FastAPI: Tree-sitter AST parsing + Leiden community detection algorithms.
• Inter-service Communication: C# API communicates via typed HttpClient using Aspire service discovery (services__clustering__http__0). NEVER launch Python scripts via Process.Start().
• Shared Repository Volume: Repositories are accessed directly on shared volume at {baseReposPath}/{tenantId}/{projectId}/{repoName}. Never pass full repository source files in HTTP request bodies.
• C# Proxy Layer: FastEndpoints layer (MILTON/Features/Clustering/) proxies requests from React client and handles caching and LLM cluster naming.

Working Rules

1. Load and follow milton-tdd for both Python and C# changes.
2. For C# proxy endpoints: follow the MILTON API vertical slice conventions (milton-vertical-slice).
3. Keep Python analysis logic in MILTON.Clustering/src/; do not inline clustering algorithms into the C# proxy.
4. Always communicate with the Python service over HTTP (HttpClient), never via direct process execution.

Verification

• Python service tests pass.
• C# proxy builds and tests pass in MILTON.Tests/.
• React client can reach clustering endpoints via proxy.