TimeTalk: Conversational Timesheet Copilot
Enterprise conversational timesheet copilot combining multi-provider natural language extraction, strict project catalogue grounding, 6 hybrid anomaly guardrails, inline AI explainability, and real-time single-source-of-truth ROI telemetry.
Problem
Enterprise consulting organizations suffer substantial revenue leakage and audit risk from manual weekly timesheets. Consultants delay logging until Friday afternoons, enter identical flat 8-hour blocks from memory, misclassify internal work as billable hours, or inadvertently charge time against closed client engagements.
Generic chat wrappers that simply pass text to an LLM fail in enterprise operations because they hallucinate project codes, auto-commit risky financial entries without human oversight, and hide the real unit economics behind token costs versus actual operational value.
Architectural Thesis: Separating Probabilistic Understanding from Deterministic Rules
Let the LLM extract structured conversational intent, but enforce project identity, compliance policies, and ledger writes with strict deterministic and statistical code.
TimeTalk uses a three-tier resilient extraction pipeline (backend/app/engine/extractor.py) paired with strict server-side validation:
- Primary Extraction: Groq (
openai/gpt-oss-20b) operating in strict JSON mode with Pydantic schema validation and an automatic single-retry repair loop if formatting fails. - Failover 1: Google Gemini (
gemini-2.5-flash) with JSON mode and usage metadata token telemetry extraction. - Failover 2: Deterministic local NLP fallback parser handling compound clauses, relative dates (yesterday, today, weekdays), and Monday-Friday week spans with zero external API dependency.
- Catalogue Grounding (
matcher.py): Grounds every hint strictly againstmock_catalogue.json. If match confidence drops below 80% or multiple projects match (for example, "2 hours on Acme development"), the copilot halts and renders clickable clarification chips instead of guessing.
The 6 Hybrid Anomaly Guardrails
Before any draft reaches the user for approval, anomalies.py evaluates six compliance and statistical checks against project status and historical baseline data:
| Rule Code | Detection Logic | Inline 1-Click Remediation |
|---|---|---|
CLOSED_PROJECT |
Blocks billing on closed engagements (e.g., INITECH-AUD closed Oct 31) |
Move to internal (INT-OPS) |
BILLABLE_INTERNAL |
Flags billable time logged to internal non-billable cost centers | Switch to non-billable |
UNUSUAL_HOURS |
Statistical Z-score outlier check against 8-week baseline (mean 8.2h, std dev 1.1h, threshold > 10.4h) | Set hours to 8h baseline |
WEEKEND_HOLIDAY |
Detects entries logged on weekends or company holidays | Requires justification override |
BUDGET_BURN |
Warns when staged hours push client budget utilization above 90% | Verify scope & budget alert |
DUPLICATE |
Catches duplicate (date, project_code, task) entries across active drafts and committed entries | 1-click Remove duplicate |
Key Product & UX Decisions
Zero Auto-Commit Invariant
Nothing writes to timesheets.json without explicit consultant confirmation. Bulk action Confirm all strictly processes clean Draft rows; flagged Needs review rows require an explicit 1-click fix or a documented justification via Confirm anyway (which tags the committed row with an Override audit badge).
Inline "Why?" Explainability on Every Row
Every staged row carries an expandable Why? drawer displaying the exact raw input snippet, project matching rationale, confidence score, token count, inference latency in milliseconds, and logged override reasons.
Single-Source-of-Truth ROI & Team View Governance
Both the live executive header KPI cards and the Team view modal read from a unified React telemetry store (MetricsProvider). Disputed billing prevented starts at ₹0 and increments only when the user actively fixes or discards flagged anomalies. Once 3+ entries are confirmed, Fully loaded ROI projects over a 20-day working month against a ₹40/user/month fully loaded cost baseline, while explicitly surfacing Token ROI alongside the note: "Token cost is negligible; fully loaded cost is the real test."
Verification & Stack
- Frontend: React 19, Vite 8, Tailwind CSS v4, Lucide Icons, single-screen 1440x900 executive layout with Seeded and Start Empty demo modes.
- Backend & Deployment: FastAPI, Uvicorn, Pydantic v2, multi-stage Docker build deployed on Railway.
- Automated Acceptance Tests: Validated end-to-end across three backend test suites (
test_phase1.py,test_phase2.py,test_phase3.py) and Vite production builds.