[P0][Phase 1][Agent] Build Enterprise-Grade Hourly Tracking Agent

[vakrahul]

Overview

Build the flagship Hourly Tracking / reconciliation agent for finance teams.

Every hour the agent:

1. Pulls timesheet and billing data from multiple sources (APIs, CSVs)
2. Normalizes disparate formats using AI
3. Checks math — do hours billed match hours worked? Any fee gaps?
4. Fixes discrepancies — validate → correct → validate loop (automated); human approval is v2

This is the primary demo for investors and the first workflow sold to clients.

Status: v1 shipped via PR #9 (merged). Template: examples/templates/hourly_tracking/
Related: #10 Docs / auto-correction

---

Ticket metadata

Field	Value
Phase	Phase 1 — Pilot / GTM
Priority	P0 — Critical path
Type	Vertical agent
State	Closed — v1 scaffold complete; HITL follow-up tracked separately

---

Why this matters

• Proves EngineX handles production business workflows
• Finance reconciliation delivers measurable ROI (fewer manual hours, fewer billing errors)
• Demonstrates timer agents and validate → fix graph loops (v1)

---

Who uses it

Persona	What they do
Finance ops	Reviews results in dashboard (v2: approve exceptions via HITL)
Engineering	Builds agent, connects client data sources via MCP/tools
Investor / client	Observes hourly run and dashboard during demo

---

Architecture (v1 — as shipped)

graph TD
 subgraph trigger [1. Trigger]
 T1[Hourly timer]
 end

 subgraph ingest [2. Ingest]
 I1[Fetch API data]
 I2[Read CSV / ledger]
 I1 --> I3[Aggregate raw inputs]
 I2 --> I3
 end

 subgraph ai [3. AI processing]
 I3 --> P1[LLM extract + normalize]
 P1 --> P2[Structured records]
 end

 subgraph validate [4. Validate and fix loop]
 P2 --> V1{Reconciliation OK?}
 V1 -->|No| V2[Correct transactions step]
 V2 --> V1
 end

 subgraph output [5. Output]
 V1 -->|Yes| O1[Store verified results]
 O1 --> O2[Report + dashboard SSE]
 end

 T1 --> I1
 T1 --> I2

Loading

v1 note: pause_nodes = [] — no human approval gate in this template yet. Auto-correction uses the graph loop (validate_transactions → correct_transactions → validate_transactions), not dashboard HITL. For human review patterns see agreement_analysis or log_monitor.

Platform features used in v1:

• Timer entry — AsyncEntryPointSpec (same family as log_monitor --daemon)
• Graph loop — conditional edges on validation_passed
• Judge RETRY — missing output_keys inside steps (see [P0][Phase 1][Docs] Goal vs node criteria, audit auto-correction, improvement gaps #10)

v2 (not in v1):

• Human review — add pause_nodes when exception needs approver in dashboard

---

Engineering deliverables

Agent scaffold — done (PR #9)

• Template: examples/templates/hourly_tracking/
• agent.py — Goal with success criteria
• nodes/ — fetch, process, validate, correct, store
• edges/ — validate → fix loop on failure; success → store

Data & tools — partial

• tools.py with mock/validation helpers
• Production broker API credentials (mock first — see out of scope)
• Pydantic schemas in lib/schemas.py

Validation — done

• Math checks: inputs = outputs + fees
• On failure: route to correct_transactions with discrepancy context
• Per-step retry limit (loop_config.max_iterations)

Human-in-the-loop — v2 / not shipped

• pause_nodes on exceptions that need human sign-off
• Approver accept/reject in web dashboard (inject_input)

Ops & demo — done

• README with workflow description
• Runs on hourly timer; compatible with --daemon pattern
• CI: engine validate examples/templates/hourly_tracking

---

Reference templates

Template	Pattern to reuse
log_monitor	Timer + daemon + conditional edges + human review
agreement_analysis	HITL pause + judge RETRY (for v2 HITL)
#10 docs	Goal vs step retry vs graph loop

---

Definition of done

v1 (closed)

• Agent validates cleanly (engine validate)
• Hourly trigger configured (AsyncEntryPointSpec)
• Validation catches mismatch and routes through fix loop
• README covers workflow
• PR Build Enterprise-Grade Hourly Tracking Agent (#2) #9 merged with CI green

v2 (follow-up — open work)

• Human can approve a flagged exception in web dashboard
• Production data source integrations

---

Out of scope (v1)

• Production broker API credentials (use mocks for demo)
• Multi-tenant isolation (#4)
• Desktop install (#5)

[pravinmishra672]

Ticket metadata

Field	Value
Phase	Phase 1 — Pilot / GTM
Priority	P0 — Critical path (do now)
Type	Agent (vertical)
Target	First flagship demo + design partner
Depends on	—
Blocks	Investor pitch, first paying client

Suggested labels (admin): phase-1, priority-p0, type-agent

Why P0: Flagship agent — proves business value (finance reconciliation). PR #9 tracks implementation.