gskinnerteam/flutter-hatcha-app/ai-system

AI System — Developer Guide

This skill covers the full AI communication architecture: Flutter conversation configs, Python agent routing, prompt files, and the protocols connecting them.

Working on the background image builder? Use the image-builder skill instead — it is the focused guide for editing the refiner prompt, the pixel system instruction, and running the local iteration loop.

When to Use

• Adding a new ControllerConfig (GenUI widget-rendering)
• Adding a new GeminiConversationConfig (text-only AI)
• Creating or modifying a Python agent in agents/hatcha_agent/
• Working with system prompts in agents/hatcha_agent/prompts/
• Debugging AI routing or session issues
• Understanding the TextProxyAgent pattern

1. Two-Layer AI Architecture

Every AI request routes through the Python hatcha_agent A2A server. No direct Gemini API calls in Flutter.

Flutter App
├── GenUI (ControllerConfig)
│     └── A2A request → RoutingExecutor → {feature}Agent → widget JSON
│
└── GeminiService (GeminiConversationConfig)
      └── A2A request ("System Instruction: {prompt}\n\n{msg}")
                      → TextProxyAgent → Gemini → text response

2. GeminiService (Text Conversations)

File: lib/core/genui/gemini_service.dart

Each GeminiConversationConfig creates its own GeminiService instance via GeminiServiceLogic.

How messages reach Python

$gemini.getById(conversationId).sendMessage(message);
// Sends: "System Instruction: {systemPrompt}\n\n{message}"
// Python TextProxyAgent extracts systemPrompt, calls Gemini, returns text

Key methods

Batching

When enableBatching: true (default), messages within a 1-second window are concatenated. Batch-handling instructions are auto-injected into the system prompt.

3. GeminiConversationConfig

Base class for text-only AI conversations. Subclasses live in lib/features/*/generative/.

abstract class GeminiConversationConfig {
  String get groupId;         // Groups related conversations
  String get conversationId;  // Unique per instance
  String get systemPrompt;    // Sent as "System Instruction: {prompt}"
  GeminiConfig get config;    // Model params
}

All conversation configs

4. GenUI Controllers (ControllerConfig)

Base class for widget-rendering. Subclasses live in lib/features/*/genui/.

abstract class ControllerConfig {
  String get groupId;
  String get contextSuffix;       // Combined → contextId (session key)
  Catalog get catalog;            // Widget catalogue for this context
  Transport get transport;        // Points at A2A server (was ContentGenerator)
  // Optional: maxInstances, enableAutoRetry, maxRetryAttempts, retryDelay
}

contextId = "{groupId}_{contextSuffix}" — used for sticky session routing in Python.

All controllers

5. Context ID Patterns

Context IDs are session keys for sticky routing:

6. Python Agent Architecture

All code in agents/hatcha_agent/.

Key files

Agent types

• GenUI agents (use_ui=True): Respond with text + ---a2ui_JSON--- block containing surfaceUpdate objects
• Text agents (use_ui=False): Return plain text. TextProxyAgent is the only text agent

Routing (RoutingExecutor)

1. First message to a contextId: agent detected from message prefix pattern
2. Agent stored in _session_routes[context_id]
3. All subsequent messages with same contextId → same agent (sticky)

Agent routing table

Prompt files

All in agents/hatcha_agent/prompts/: