Skip to content

About

Spec-first scaffold for a portable chat-agent widget. OpenAPI + TS/Python types + package layout, awaiting first consumer commitment. Pattern: github.com/kmoy007/design-patterns/blob/main/chat-api-pattern.md

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

chat-widget

Status: Spec-frozen skeleton. No implementations yet.

The wire format for a portable chat agent widget — backend-agnostic, framework-agnostic. This repo exists so the spec can stabilise before any consumer commits a wire format. Lesson learned the hard way from bug-report-widget: once three apps have shipped a chat surface with their own field names, retroactive standardisation is expensive. So this time we publish the contract first.

The design rationale lives at design-patterns/chat-api-pattern.md. Read that for the why. This repo is the what: a formal OpenAPI spec, typed DTOs, and scaffolded packages waiting for a real consumer to motivate implementation.

What this delivers (when done)

A portable, self-injecting chat widget that any web app can drop in:

<script src="/lib/chat-widget.js" defer></script>

…and a backend the widget posts to, in your stack of choice:

# Python (Flask)
from chat_widget import create_chat_blueprint
app.register_blueprint(create_chat_blueprint(
    agent_loop=your_agent_loop,        # callable: (messages, tools) -> turn result
    store=your_conversation_store,     # optional; stateless if omitted
    preflight=your_gate,               # optional; auth + rate + budget
))
// Node (Express)
import { createChatRouter } from "chat-widget-node";
app.use("/api/chat", createChatRouter({
  agentLoop: yourAgentLoop,
  store: yourStore,                    // optional
  preflight: yourGate,                 // optional
}));

The agent loop is injected. The package is wire-format plumbing — it never picks the model provider (Anthropic / OpenAI / etc.) or owns the tools. That's the seam.

What's in the box

Package Status Purpose
packages/spec ✅ Real OpenAPI 3.1 + TS types + Python types. The contract.
packages/widget 🟡 Scaffold Vanilla JS self-injecting chat panel. Waiting for first consumer.
packages/backend-python 🟡 Scaffold Flask blueprint + Store Protocol + AgentLoop Protocol.
packages/backend-node 🟡 Scaffold Express router + Store interface + AgentLoop interface.
packages/cli 🟡 Scaffold chat CLI for one-shot turns — useful for smoke tests + scripts.
e2e/ 🟡 Scaffold Cross-stack contract suite — same scenarios against both backends.

Who's expected to use it

Per the chat-api-pattern doc, three existing chat agents:

  • pikpak-platform — closest fit (SSE primary, conversations endpoints, in-flight cancellation, hard tool-loop cap). Migrating pikpak first would prove the abstraction.
  • leap-timesheet — needs cost guardrails / kill switch / prompt caching to come along as configurable preflight steps; Conversations table needs a Store adapter.
  • katja-schedule — stateless-server case; the package's persistence interface must genuinely be optional. Client sends full trimmed history each turn.

Plus future apps (claude-tmux-dashboard could grow a chat surface for tmux-Claude debugging, for example).

Implementation begins when two of those three commit to consuming the package. Until then, this repo is documentation — the spec, typed, in code form, ready to be reviewed.

Quick spec summary

One endpoint, content-negotiated:

POST /api/chat
  Accept: application/json   → buffered TurnResponse
  Accept: text/event-stream  → SSE stream of typed events

GET    /api/chat/conversations            (404 if persistence off)
POST   /api/chat/conversations            (create)
GET    /api/chat/conversations/{id}/messages   (rehydrate)
GET    /api/chat/health                   (cheap probe)

Messages are Anthropic-shaped: {role, content} where content is either a string or an array of typed blocks (text / image / document). Server owns the tool loop; client renders typed SSE events (text_delta, tool_use, tool_result, done, error).

Full spec: packages/spec/openapi.yaml.

License

MIT. See LICENSE.

About

Spec-first scaffold for a portable chat-agent widget. OpenAPI + TS/Python types + package layout, awaiting first consumer commitment. Pattern: github.com/kmoy007/design-patterns/blob/main/chat-api-pattern.md

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages