llm-multiverse/implementation-plans/issue-072.md

Implementation Plan — Issue #72: Scaffold Orchestrator Python project

Metadata

Field	Value
Issue	#72
Title	Scaffold Orchestrator Python project
Milestone	Phase 9: Orchestrator
Labels	—
Status	COMPLETED
Language	Python
Related Plans	issue-015.md, issue-045.md
Blocked by	#17

Acceptance Criteria

• Python project created (services/orchestrator/)
• Dependency on generated Python proto stubs
• grpcio server boilerplate runs
• Configuration loading (address, port, service endpoints, agent configs)
• Health check endpoint responds (stub ProcessRequest returns COMPLETE)
• setuptools for dependency management (matches search service pattern)

Implementation Steps

1. Project structure

• pyproject.toml with setuptools, grpcio, protobuf, pyyaml dependencies
• src/orchestrator/ package with __init__.py, __main__.py, config.py, service.py
• tests/ with test_config.py, test_service.py

2. Configuration (config.py)

• Config dataclass with service endpoints (model_gateway, tool_broker, memory, search, audit)
• AgentConfig dataclass for per-agent settings (max_iterations, timeout, max_tokens)
• YAML loading with env var fallback (ORCHESTRATOR_CONFIG)
• Port 50058 (follows convention: audit=52, secrets=53, memory=54, gateway=55, search=56, broker=57)

3. gRPC service (service.py)

• OrchestratorServiceImpl extending OrchestratorServiceServicer
• Stub ProcessRequest that yields a single COMPLETE response
• Full implementation deferred to issues #73-#80

4. Server entry point (__main__.py)

• Async gRPC server with graceful shutdown (SIGINT/SIGTERM)
• Console script entry point: orchestrator

5. Tests (11 tests)

• 8 config tests: defaults, YAML, partial YAML, empty YAML, env var, listen_addr
• 3 service tests: stub response, message truncation, full gRPC integration

Files to Create/Modify

File	Action	Purpose
services/orchestrator/pyproject.toml	Create	Project configuration
services/orchestrator/src/orchestrator/__init__.py	Create	Package init
services/orchestrator/src/orchestrator/__main__.py	Create	gRPC server entry point
services/orchestrator/src/orchestrator/config.py	Create	Configuration loading
services/orchestrator/src/orchestrator/service.py	Create	gRPC service stub
services/orchestrator/tests/__init__.py	Create	Test package
services/orchestrator/tests/test_config.py	Create	Config tests
services/orchestrator/tests/test_service.py	Create	Service tests

Deviation Log

(No deviations)