thomasskarp/autoapp-agent-graph

🚗 AutoApp — Production Agentic State Machine Blueprint

System Card & Architecture Blueprint: An enterprise-ready, deterministic multi-agent state machine designed for automotive B2B workflows. Deconstructs monolithic LLM prompts into isolated, typed worker nodes, adversarial evaluation gates, and Human-in-the-Loop (HITL) checkpoints.

• GitHub Repository: thomasskarp/autoapp
• Living Architecture Map: AGENT_GRAPH.md

---

📌 Context: Deconstructing the Monolithic Mega-Prompt

In automotive retail, dealership sales reps submit inventory data via informal messages ("Just took in a 2021 Toyota Corolla XEI with 45k km, clean title, asking 22M ARS").

Early prototypes that used a single monolithic prompt to extract data, estimate official market prices, enforce 20% dealership margins, and write ads broke down due to the non-linear failure trap: $$\mathbf{P}(\text{success})=\prod _{i=1}^n{p}_i\backslash mathbf\{P\}(\backslash text\{success\})\; =\; \backslash prod\_\{i=1\}^\{n\}\; p\_i$$ Without intermediate verification, errors in early reasoning compound across the entire pipeline.

---

🗺️ State Machine Flow

[User Input] 
     │
     ▼
[1. Intent Router (< 15ms)] ──(Add Stock)──► [2. Spec Extractor (Gemini + Zod)]
                                                        │
                                                        ▼
                                             [3. Relational Valuator]
                                             (PostgreSQL pg_trgm GIN in < 5ms)
                                                        │
                                                        ▼
                                             [4. Concurrent Fan-Out]
                                             (Parallel copy: IG, FB, MeLi, WhatsApp)
                                                        │
                                                        ▼
                                             [5. Quality & Margin Checker]
                                             (Adversarial Gate: Margin 15-25%)
                                                        │
                                                        ▼
                                             [6. Human-in-the-Loop Gate]
                                             (Awaits human approval)
                                                        │
                                                        ▼
                                             [7. Transactional Dispatcher]
                                             (Serial write to PostgreSQL & APIs)

---

⚙️ Key Architectural Principles

1. Harness Engineering ("Humans Steer, Agents Execute"): Software engineers define constraints, typed schemas, and invariant gates. The model performs execution within bounded sandboxes.
2. Adversarial Verification: An agent should never grade its own homework. Generative copywriters and extractors are audited by an independent, non-generative Quality Checker gate.
3. Clean-Context Workers: Each node executes with isolated, minimal context, eliminating cognitive drift and cutting unnecessary token usage.
4. Relational Grounding over Vector Search: Numerical catalog valuations are performed via PostgreSQL pg_trgm GIN inverted indexes (< 5ms) rather than asking the LLM to recall numbers.
5. Serial Mutations vs. Parallelized Reads: Multichannel copywriting runs in parallel (fan-out); database updates and marketplace publications run strictly serially.

---

📦 Typed State Interface (AutoAppState)

export interface AutoAppState {
  sessionId: string
  inputMessage: string
  intent?: 'ADD_STOCK' | 'APPRAISAL' | 'LEAD_CRM' | 'GENERAL_FAQ'
  draftVehicle?: {
    marca: string
    modelo: string
    anio: number
    km: number
    precio_venta: number
  }
  officialValuation?: {
    tablePrice: number
    marginPercent: number
    source: 'POSTGRES_PG_TRGM'
  }
  generatedCopies?: {
    instagram?: { caption: string; hashtags: string[] }
    facebook?: { title: string; description: string }
    mercadolibre?: { title: string; description: string }
    whatsapp?: { chat_pitch: string }
  }
  validation: {
    passed: boolean
    errors: string[]
  }
  requiresConfirmation: boolean
}

---

🔬 Benchmark & Latency Telemetry

Node	Mechanism	Latency	Guardrail
Router	Regex + Semantic classification	< 15ms	Fallback to GENERAL_FAQ
Extractor	Gemini 2.5 Flash + Zod	~250ms	Strict schema validation
Valuator	PostgreSQL pg_trgm GIN	< 5ms	Grounded against official books
Copy Fan-Out	Asynchronous concurrency	~2.2s	Platform character limits
Quality Checker	Deterministic business rules	< 2ms	Rejects margin < 15%
HITL Gate	Suspended state checkpoint	Human	Explicit confirmation button

---

📄 License & Attribution

Developed by Thomas Skarp as part of the AutoApp Automotive B2B SaaS platform. Distributed under the MIT License.