How dharmateja03/harmony-ai works
1. What this repo is
- A stateless production scheduling service that accepts one scheduling request, solves it once, and returns a feasible schedule optimized for minimum tardiness.
- The core architecture is a thin API wrapper around a constraint-programming solver.
2. Primary request flow
- The main path is: POST /schedule → request validation → client-specific parsing → canonical scheduling problem → CP-SAT solve → KPI calculation → JSON response.
- This flow is centered in app/main.py, app/adapters/client_a.py, app/scheduler/solver.py, and app/kpis/calculator.py.
3. API boundary
- app/models/api.py defines the external request/response schema used by the HTTP layer.
- app/main.py exposes the FastAPI app and is the integration point between HTTP and the scheduler pipeline.
4. Client adapter boundary
- app/adapters/client_a.py translates the incoming client JSON format into the internal scheduling model.
- This is the place where client-specific field names, validation assumptions, and support for objective modes are handled.
- The design intentionally isolates input formats so a second client can be added without changing the solver.
5. Canonical internal domain model
- app/models/internal.py holds the solver-facing dataclasses such as resources, products, route steps, time windows, changeover matrices, and objective config.
- The solver operates only on these typed internal objects, not on raw JSON or client-specific shapes.
- This boundary is the repository’s main “model translation” seam.
6. Constraint-solving core
- app/scheduler/solver.py builds the OR-Tools CP-SAT model.
- The model includes operation start variables, resource assignment booleans, window-fit logic, no-overlap constraints, changeover gaps, and precedence links between steps in a product route.
- The solver is the only place where scheduling feasibility is enforced.
7. Objective handling
- app/scheduler/objectives.py defines objective-building logic, with the active objective selected through a registry-style pattern.
- The README indicates the current optimization target is total tardiness, but the structure allows adding other objective modes without changing the solver’s overall flow.
8. Output and KPIs
- After solving, app/kpis/calculator.py derives operational KPIs from the chosen assignment list.
- This means the solver returns a schedule, and the KPI layer enriches it for the API response rather than influencing the feasibility model.
9. Auxiliary presentation tools
- app/ui.py and app/viz.py appear to support local viewing or visualization of schedules rather than the service’s main request path.
- They are adjacent utilities, not core scheduling dependencies.
10. Operational characteristics
- The service runs either in Docker or directly under Uvicorn with Python 3.12+.
- It is deterministic by design: single worker plus fixed seed, so the same input should produce the same schedule.
- There is no persistence, authentication, or external service dependency; each scheduling request is independent.
11. Feasibility and failure handling
- The adapter/solver path includes basic infeasibility checks, such as missing capability or operations that cannot fit in any working window.
- If the solver still proves infeasibility, the response is a generic infeasible result rather than detailed conflict analysis.
12. Testing surface
- The tests cover infeasible cases, invariants, and KPI correctness, which maps directly to the main architectural risks: feasibility, constraint correctness, and output interpretation.
- This supports the repo’s central contract: valid inputs should either yield a consistent feasible schedule or a clear infeasible outcome.
Main entry points: main.py Main API · solver.py CP-SAT solver · conftest.py Test setup · client_a.py Client adapter
Components 13
API layer
HTTP entrypoint and external contract
- Main API · Exposes POST /schedule and orchestrates the request pipeline
app/main.py - API models · External HTTP payload definitions
app/models/api.py
Domain model
Client translation and solver-facing types
- Client adapter · Maps client JSON into canonical scheduling input
app/adapters/client_a.py - Internal model · Canonical resources, routes, windows, changeovers, and objective config
app/models/internal.py
Optimization core
Constraint solving and objective selection
- Objectives · Builds objective terms such as total tardiness
app/scheduler/objectives.py - CP-SAT solver · Builds feasibility model and searches for a schedule
app/scheduler/solver.py
Output layer
KPI enrichment and local viewing utilities
- KPI calc · Computes operational KPIs from the solved assignment
app/kpis/calculator.py - UI helper · Ad hoc schedule presentation utility
app/ui.py - Viz helper · Schedule visualization utility
app/viz.py
Quality checks
Tests covering feasibility and output correctness
- Infeasible tests · Covers impossible schedules and failure handling
tests/test_infeasible.py - Invariant tests · Checks schedule consistency and constraint invariants
tests/test_invariants.py - KPI tests · Validates KPI calculations on solved schedules
tests/test_kpis.py - Test setup · Shared pytest fixtures and test wiring
tests/conftest.py
Connections 15
- Main API → API models: validates/serializes · HTTP layer uses the external request and response schema
- Main API → Client adapter: dispatches · Main endpoint hands request payload to the client adapter
- Client adapter → Internal model: builds · Adapter converts client JSON into canonical solver input
- Internal model → CP-SAT solver: feeds · Solver consumes typed internal scheduling objects
- CP-SAT solver → Objectives: selects objective · Solver asks the objective registry for the active optimization mode
- CP-SAT solver → KPI calc: returns solution · Solved assignment is passed to KPI computation
- KPI calc → Main API: enriches response · KPIs are added before the API response is returned
- Main API → UI helper: optional view · Local utility path for viewing schedules
- Main API → Viz helper: optional render · Local visualization support adjacent to the main service
- Infeasible tests → Client adapter: covers · Tests exercise parsing and infeasibility paths
- Invariant tests → CP-SAT solver: covers · Tests verify feasibility and scheduling invariants
- KPI tests → KPI calc: covers · Tests verify KPI derivation from solved schedules
- Test setup → Infeasible tests: supports · Shared fixtures support infeasibility scenarios
- Test setup → Invariant tests: supports · Shared fixtures support invariant checks
- Test setup → KPI tests: supports · Shared fixtures support KPI checks