stacgis-ai-react — Overview

Modern React components and hooks for the stacgis-ai geospatial AI agent harness. Drop a fully-styled chat UI — with a live ReAct reasoning feed, geometry attachment panel, human-in-the-loop approval modal, voice input, text-to-speech, persistent chat history and automatic capacity queuing — into any React app, or use the headless useAgent hook to build your own.

• ✅ AgentChat — complete, themeable chat component (dark & light)
• ✅ useAgent — headless hook: streaming SSE, blocking chat, cancellation, HitL approvals, frontend tool events, **server-capacity queueing (HTTP 503
  • auto-retry)**
• ✅ GeometryInput — point / polyline / polygon attachment with canvas
• ✅ ApprovalModal — approve/reject sensitive tool calls (with countdown and optional rejection reason)
• ✅ SuggestedPrompts — welcome screen with clickable starter prompts
• ✅ ChatHistory + useChatSessions — localStorage-backed session history (search, rename, delete, restore)
• ✅ useVoiceInput — microphone dictation (Web Speech API)
• ✅ useTextToSpeech — read-aloud for messages + optional autoSpeak
• ✅ Per-message actions — copy to clipboard, read aloud, export as PDF
• ✅ renderChart — render ```chart markdown blocks with your own chart library
• ✅ locked — auth / feature-gate overlay for the whole chat
• ✅ Zero required UI dependencies — plain React 18/19, scoped CSS (no CSS leakage); jspdf / html-to-image are lazy-loaded only for PDF export
• ✅ Ships ES + CJS builds and TypeScript declarations

Exports

Export	Kind	Description
<AgentChat />	component	Complete chat UI (see AgentChat component)
<GeometryInput />	component	Point / polyline / polygon drawing panel (see GeometryInput)
<ApprovalModal />	component	HitL approve/reject modal (rendered automatically by AgentChat)
<SuggestedPrompts />	component	Welcome screen with clickable starter prompts
<ChatHistory />	component	Slide-over session history (search, rename, delete, new chat)
<MessageBubble />	component	Single message with markdown, copy / read-aloud / PDF export, steps feed
<MarkdownRenderer /> (+ parseBlocks)	component	Lightweight markdown (code, tables, lists, chart blocks)
<ChatQueueOverlay />	component	Server-at-capacity queue (usage ring, retry countdown, cancel)
<AgentActivityFeed /> / <ActivityFeed />	component	Live ReAct step feed (thinking / acting / observing / responding)
<TypingIndicator /> / <GradientArc />	component	Streaming affordances
useAgent	hook	Headless agent state & actions (see useAgent hook)
useChatSessions	hook	Persist/restore chat sessions in localStorage
useVoiceInput	hook	Capture speech from the microphone (Web Speech API)
useTextToSpeech	hook	Speak text / assistant responses (Web Speech API)
types	TS	AgentState, AgentStep, Message, ApprovalRequest, FrontendToolEvent, GeoPoint, GeoPolyline, GeoPolygon, GeoGeometry, GeoFeature, MessageAttachment, QueueInfo, ChatSession, SuggestedPrompt, AgentChatHandle, …

Quick start

import { AgentChat } from "stacgis-ai-react";
import "stacgis-ai-react/dist/index.css";   // required

export function App() {
  return (
    <AgentChat
      apiBaseUrl="http://localhost:8000/api/v1"
      title="GeoAgent"
      placeholder="Ask me to geocode places, compute routes, find POIs…"
      onFrontendEvent={(event) => console.log(event.event_name, event.payload)}
    />
  );
}

apiBaseUrl must point at the FastAPI app including the router prefix (the component appends /agent/chat, /agent/stream, …).

info

The full chat experience is shown in the demo app under frontend/example/ — see Demo app.