| --- |
| license: mit |
| pipeline_tag: text-generation |
| tags: |
| - agent |
| - agent-graph |
| - state-machine |
| - multi-agent-orchestration |
| - gemini-2.5-flash |
| - zod |
| - system-design |
| - production-ai |
| language: |
| - en |
| - es |
| library_name: nextjs |
| --- |
| |
| # 🚗 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](https://github.com/thomasskarp/autoapp) |
| * **Living Architecture Map:** [AGENT_GRAPH.md](https://github.com/thomasskarp/autoapp/blob/main/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$$ |
| 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`) |
|
|
| ```typescript |
| 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. |
|
|
