A2UI Local Gemma Spike

Local feasibility spike for rendering AJKit-governed A2UI surfaces from local and CLI model providers.

AJKit supplies the generation profiles, validation, visual direction, style tokens, and recovery policy. A2UI stays the portable surface contract/runtime: the app asks a selected provider for compact intent JSON, validates it against AJKit authority, deterministically compiles it into A2UI v0.9 messages, and renders the result with the React A2UI renderer.

Available experiments:

• Restaurant: generates a restaurant-booking surface from a restaurant request.
• Travel: generates a weekend city itinerary surface from a travel request.
• Candidate review: generates a hiring review surface.
• Issue triage: generates an engineering triage surface.
• Event ops: generates an event operations runbook surface.
• Lesson plan: generates an adaptive lesson planning surface.
• Home project: generates a home project planning surface.

Requirements

• Node.js 22+
• npm
• Codex CLI for the default codex-cli provider
• AJKit checkout at /Users/mike/AgenticJudgmentKit, or set AJKIT_PATH
• Optional: LM Studio local server running at http://localhost:1234/v1
• Optional: LM Studio model available as google/gemma-4-e2b

Provider and AJKit defaults can be overridden with:

AJKIT_PATH=/Users/mike/AgenticJudgmentKit
A2UI_LLM_PROVIDER=codex-cli
A2UI_CODEX_MODEL=gpt-5.5
A2UI_CODEX_REASONING_EFFORT=medium

A2UI_LLM_PROVIDER=lmstudio
LM_STUDIO_BASE_URL=http://localhost:1234/v1
A2UI_LMSTUDIO_MODEL=google/gemma-4-e2b

Run

Install dependencies if needed:

npm install

Check that LM Studio is reachable and the model is loaded:

npm run preflight

Start the local app and API:

npm run dev

Open the app:

http://127.0.0.1:5173/

The dev command starts:

• AJKit loopback MCP server: http://127.0.0.1:8765/mcp
• Vite web app: http://127.0.0.1:5173/
• Local API proxy: http://127.0.0.1:8787/

npm run dev runs the API with A2UI_AJKIT_REQUIRE_LOOPBACK=1, A2UI_AJKIT_CACHE=1, and A2UI_LOCAL_INTENT_CACHE=1 so the default product path exercises live AJKit governance instead of stdio fallback.

Test And Build

Run unit tests:

npm test

Build the app:

npm run build

Experiment Flow

1. Choose an experiment mode.
2. Enter a prompt:
   • Restaurant: Book a table for 2 tomorrow at 7 near Hayes Valley for Italian food.
   • Travel: Plan a 3-day weekend trip to Portland for two people, relaxed pace, good food and walkable neighborhoods, budget around $900.
   • Candidate review: Review three senior product design candidates for a growth role.
   • Issue triage: Triage frontend checkout issues for next sprint.
   • Event ops: Plan staffing and runbook risks for a 300-person launch event.
   • Lesson plan: Create a 45-minute middle school fractions lesson for mixed skill levels.
   • Home project: Plan a weekend pantry shelving project under $400.
3. Click Generate.
4. The backend requests structured JSON from local Gemma through LM Studio.
5. The response is validated as an experiment-specific intent object.
6. The compiler emits A2UI v0.9 messages.
7. The React A2UI renderer displays the generated surface.
8. Clicking generated action buttons adds A2UI client events to the action log.

The API stays backward compatible. Missing experiment defaults to restaurant:

{
  "prompt": "Plan a 3-day weekend trip to Portland for two people.",
  "experiment": "travel"
}

Supported experiment values are restaurant, travel, candidate-review, issue-triage, event-ops, lesson-plan, and home-project.

AJKit Proof Commands

Profile and manifest checks:

npm run proof:fetch-ajkit-profile
npm run proof:extract-manifest
npm run proof:extract-storybook-manifest

Runtime/value proofs:

npm run proof:visual
npm run proof:value
npm run proof:hero
npm run proof:travel
npm run benchmark:providers

Proof results are written under output/ and are intentionally ignored by git.

Project Layout

server/   Local Express API, provider clients, AJKit profile transport
shared/   Intent schemas and A2UI compilers
src/      React app and diagnostics UI
scripts/  Proof and benchmark runners
tests/    Schema, compiler, API, and visual tests