About the project
🎯 The Idea
Problem: Wacky Wheels Co. is a just-in-time automaker with no parts inventory, so a late shipment, plant outage, or defective lot ripples into production schedules, dealers, loaner cars, and owners. Operations teams have to deal with:
Alerts written the way people write them: nicknames, relative dates like “next Wednesday,” and vague wording Single messages that contain several incidents Irrelevant noise that should get no action Unconfirmed rumors that should go to a human, not trigger changes Shared resources, like production slots and loaner pools, that must stay consistent across incidents A policy handbook that dictates what to do for each kind of event
Solution: A local control tower with one coordinating agent and three specialists. Supply Chain Planner owns delays, outages, and slots. Quality Containment owns lots, stop-sale, and owner notices. Dealer and Customer Care owns one notice per dealer and loaners. The agents read an event feed, trace each incident through a knowledge graph of company data, and apply the policy handbook through the enterprise tools.
Key Innovation: The reader understands the message, the graph decides what is affected, and the handbook decides what to do. The coordinator drops any planned call outside the owning agent’s tools, so only affected records change. Every event gets a graph path and reasoning trace, and event IDs are never used as an answer key.
Impact: A messy message becomes a set of correct, auditable actions. Noise is left alone, unconfirmed reports go to a human, and a dashboard shows the whole story.
🌍 Who This Helps Operations controllers: One place to see events, impact, and actions Supply chain planners: Reschedules and transfers driven by the actual graph of orders and plants Dealers: One notice per dealer, instead of a flood of duplicate messages Owners: Timely contact and loaners when a quality hold affects their vehicle Quality and compliance teams: A full action log and trace for every hold and escalation Teams without cloud access: Everything runs on a laptop
🚀 What It Does
The tower reads each message and handles six event types: Supplier Delay, Plant Outage, Quality Hold, Noise, Unconfirmed Report, and Compound. For each one it:
Reads the text into incidents, with entities and dates Checks the reading: quoted phrases must appear in the message, and a failed check falls back to the rule reader, with the trace saying why Traces the incident through the knowledge graph over the company tables Hands off to the right specialist agent Checks each planned call against that agent’s tools, then runs the rest Records every action in an action log and a per-event trace Escalates unconfirmed reports, takes no action on noise, and logs failed writes without retrying them
A web dashboard, built in React, shows the Overview, Event feed, Tests, Knowledge graph, Logs, and a Guide.
🛠️ How We Built It
Event understanding. A local model through Ollama turns text into incidents. The default reader is Qwen3 1.7B (qwen3:1.7b), and the saved traces for the 15 events name Qwen2.5 0.5B (qwen2.5:0.5b). A rule-based reader checks every reading, and it runs alone when Ollama isn’t available. Swap the reader with TOWER_LLM_MODEL. A second model, TOWER_TOOL_MODEL (default qwen3:1.7b), may look up a missing name or date, at most six lookups.
Knowledge graph. The graph is built over the company CSVs. The affected set for an event $e$ is found by traversal:
$$\text{Affected}(e) = {\, v \in V : \exists\ \text{path } e \rightsquigarrow v \text{ along allowed relations} \,}$$
An ontology export is generated as part of the run.
Multi-agent orchestration. The coordinator hands incidents to the three specialists, and shared resources are tracked centrally so compound incidents stay consistent:
$$\sum_{i} \text{loaners assigned}_i \le \text{pool size}$$
Tools. The enterprise tools are available in process and over local HTTP (GET /events, POST /act). Only the coordinator calls them. Specialists plan.
Testing. python start.py runs the tower on the 15 given events, grades them with tests/run_given.py against docx TC1–TC6, and checks failed calls with tests/test_failures.py. tests/run_model.py is the optional run of the model on its own, with no rule reader. Beyond the 15 given events, the repo has generated (100 cases), held-out, stress, and accuracy suites.
Dashboard and extras. The React UI is served from the Python server. There’s also an Electron wrapper and a documented live channel feed for Gmail, Outlook, Slack, Teams, and outbound notices. Everything runs from one command, python start.py, using the Python standard library with no pip packages.
📐 Design Card
Architecture. One coordinator and three specialists. The coordinator reads the message, routes each real incident, checks every planned call, and is the only component that calls a tool.
GET /events → Coordinator
- Understand local model proposes, rule reader checks → incidents
- Hand off Supply Chain Planner mes.reschedule, mes.transfer (handbook 1–3) Quality quality.hold_lot, dealer.stop_sale, crm.notify_customer (handbook 6) Dealer Network & Customer Care dealer.notify, crm.assign_loaner (handbook 4–5)
- Validate drop any call outside that agent's tool list
- POST /act action_log.jsonl + one trace per event → dashboard
Each event gets a fresh plant schedule, a fresh loaner pool, and a fresh enterprise world. Noise and unconfirmed reports never reach a specialist. The coordinator’s own tool is escalate (handbook 7–10).
LLM versus code. The model labels a section and copies phrases for the plant, part, supplier, lot, shipment, and the two dates. It does not return ids or computed dates. Code checks that each phrase appears in the message, resolves names through aliases.csv, turns “next Friday” into a date from the day the event was received, and runs the rule reader as the check. If the model gives no usable answer, or it disagrees with the rules, the rules decide and the trace says why. Graph traversal, slot search, loaner assignment, and the handbook are code.
Guardrails. Noise writes nothing. An unconfirmed report is escalate only. Confirmed incidents change only the affected records. A planned call outside that agent’s tool list is refused before it runs, and the refusal is recorded. A failed write is logged and not retried. A confirmed incident that ends with no successful write is escalated. The same write is not sent twice in one event.
Evaluation. On the 15 given events, with the rule check, the rule reader, Qwen2.5 0.5B, Qwen3 0.6B, and Qwen3 1.7B each score 15/15. The saved log is 768 calls and 0 failed. Noise has no calls. Each unconfirmed report is one escalate. The latest saved run of Qwen3 1.7B on its own, where code only resolves the phrases the model quoted, is also 15/15. An earlier run of that same check was 5/15, which is why the rule reader stays in the path.
What we would improve. Slot choice is the earliest feasible day, which is what the handbook asks for. An optimizer could cut transfers when several disruptions want the same days. A failed call is not retried, and a short retry would separate a transient failure from one that should be escalated. The rule reader is a word-list referee, so a blind set of new wording, frozen after the reader, would show what the models do on language they have not seen.
🤖 Models
All of these ran locally through Ollama. No cloud model was used.
Qwen2.5 0.5B (Ollama tag qwen2.5:0.5b, 494M parameters). The small local reader named in the saved traces for the 15 events. Qwen Team, Qwen2.5 Technical Report, arXiv:2412.15115, 2024.
Qwen3 1.7B (Ollama tag qwen3:1.7b). The default reader and the default tool model, which may look up a missing name or date. Qwen Team, Qwen3 Technical Report, arXiv:2505.09388, 2025.
Qwen3 0.6B (Ollama tag qwen3:0.6b). Graded on the same 15 events with the rule check, 15/15. Same Qwen3 report.
A reading from any of them is kept only when it matches the rule reader.
🧗 Challenges Messy language: Nicknames, relative dates, and vague wording had to resolve to exact entities and dates Small local model: Qwen2.5 0.5B is small and, on its own, fills few fields, so every reading is verified by the rule reader and the trace says when the model was set aside Compound messages: Several incidents in one message needed consistent use of shared slots and loaner pools Precision: Acting on everything affected, and nothing else, depended on strict graph traversal and per-agent tool limits Rumors vs. real events: Unconfirmed reports had to escalate with no operational change Failed calls: Failed writes are logged rather than silently dropped Explainability: A graph path and reasoning trace for every event, visible in the dashboard No answer key: Expected answers weren’t shared, so we built our own test suites and used the policy handbook as ground truth
📚 What We Learned Splitting understanding (reader), impact (graph), and action (policy) makes an agent system easier to trust and debug Verifying LLM output against a rule-based reader makes a tiny local model usable. Qwen3 1.7B alone scored 5/15 in an earlier run, which is why the rule reader stays in the path Restricting each agent to its own tools is a strong guardrail Knowing when not to act (noise) or when to hand off (escalation) matters as much as acting correctly Building generated and held-out tests keeps you from overfitting to the 15 given events
🔮 What’s Next Live deployment on real mail and chat channels, which is already scaffolded Retry and recovery logic for failed writes, to separate transient failures from ones that should be escalated A slot optimizer that cuts transfers when several disruptions want the same days A blind set of new wording, frozen after the reader, to test the models on language they haven’t seen Richer what-if simulation before actions are committed Larger or fine-tuned local models for the reader