How sii-research/legal-world works
LEGALWORLD is an interactive legal-agent simulation spanning consultation, document drafting, first-instance trial, appeal, and second-instance proceedings. A run enters through the WebSocket/API service, which coordinates case scenarios and agents; the life-cycle pipeline supplies staged execution and Tool/Skill resolution. Supporting capabilities include simulation frontend messaging, human evaluation, legal retrieval, and reflective Skill growth. The README also documents dataset construction utilities, represented as a distinct reproducibility branch. Several subsystem links are documented by README rather than inspected implementation; unsampled runtime links are omitted.
Main entry points: scenario_orchestrator.py Scenario orchestrator · ws_server.py API & WebSocket · agents Legal agent wrappers · pipeline.py Lifecycle pipeline
Components 25
Service & coordination
- API & WebSocket
backend/ws_server.py - Case lifecycle FSM
backend/src/orchestration/case_fsm.py - Scenario orchestrator
backend/src/orchestration/scenario_orchestrator.py - Agent registry
backend/src/orchestration/agent_registry.py
Legal case lifecycle
- Case data loader
backend/src/data/data_loader.py - Lifecycle pipeline
backend/src/pipeline/pipeline.py - Stage Tool resolver
backend/src/pipeline/stage_tool_resolver.py - Legal scenarios
backend/src/scenarios
Agents & legal tools
- Legal agent wrappers
backend/src/agents - Prompt assembly
backend/src/prompts/prompt_assembler.py - Legal Tool suite
backend/src/tools/legal - Skill library
backend/legal-skillhub/public - Player lawyer adapter
backend/src/player_lawyer/agent.py
State & simulation
- Event bus
backend/src/core/event_bus.py - Case file storage
backend/src/core/file_storage_manager.py - WebSocket simulation
backend/src/simulation/ws_frontend_engine.py - Mock map engine
backend/src/simulation/map_engine.py
Research utilities
- Human evaluation
backend/src/human_eval/routes.py - Evaluation pipeline
backend/src/eval/eval_pipeline.py - Reflective Skill growth
backend/gitskill/pipeline.py - Case dataset builder
dataset_builder/case_dataset_builder/pipeline.py
Other components
- User / client
- PostgreSQL
- Model provider
- Simulation frontend
Connections 27
- User / client → API & WebSocket: requests cases
- API & WebSocket → Case lifecycle FSM: routes lifecycle
backend/ws_server.py - API & WebSocket → Scenario orchestrator: starts scenarios
backend/ws_server.py - API & WebSocket → Human evaluation: serves evaluation routes
backend/ws_server.py - API & WebSocket → PostgreSQL: persists service data
- Case lifecycle FSM → Event bus: publishes events
backend/src/orchestration/case_fsm.py - Scenario orchestrator → Event bus: subscribes and publishes
backend/src/orchestration/scenario_orchestrator.py - Scenario orchestrator → Agent registry: looks up agents
backend/src/orchestration/scenario_orchestrator.py - Scenario orchestrator → Case data loader: loads case data
backend/src/orchestration/scenario_orchestrator.py - Scenario orchestrator → Prompt assembly: builds prompts
backend/src/orchestration/scenario_orchestrator.py - Agent registry → Legal agent wrappers: instantiates wrappers
backend/src/orchestration/agent_registry.py - Agent registry → Case file storage: reads agent configs
backend/src/orchestration/agent_registry.py - Lifecycle pipeline → Case data loader: loads cases
backend/src/pipeline/pipeline.py - Lifecycle pipeline → Stage Tool resolver: resolves stage tools
backend/src/pipeline/pipeline.py - Lifecycle pipeline → Legal scenarios: runs lifecycle stages
backend/src/pipeline/pipeline.py - Stage Tool resolver → Legal Tool suite: selects tools
backend/src/pipeline/stage_tool_resolver.py - Legal agent wrappers → Prompt assembly: assembles prompts
backend/src/agents/client_agent.py - Legal agent wrappers → Legal Tool suite: invokes tools
- Legal agent wrappers → Skill library: uses Skills
- Scenario orchestrator → Player lawyer adapter: adapts player counsel
backend/src/orchestration/scenario_orchestrator.py - Scenario orchestrator → Case file storage: records case outputs
backend/src/orchestration/scenario_orchestrator.py - WebSocket simulation → Simulation frontend: sends simulation messages
- WebSocket simulation → Mock map engine: uses fallback behavior
backend/src/simulation/ws_frontend_engine.py - Human evaluation → PostgreSQL: stores ratings
- Evaluation pipeline → Case data loader: loads evaluation cases
backend/src/eval/eval_pipeline.py - Reflective Skill growth → Legal agent wrappers: creates reflection lawyer
backend/gitskill/pipeline.py - Case dataset builder → Model provider: generates profiles and questions
dataset_builder/case_dataset_builder/pipeline.py