mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
716 lines
26 KiB
HTML
716 lines
26 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>hip-0011</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/hip-0011.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/hip-0011">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/hip-0011.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>hip-0011</h1><p class="lede">HIP-11: Chat Interface Standard. Status Draft. Hanzo's own standard — read this before implementing against it.</p><h1>HIP-0011: Chat Interface Standard</h1>
|
|
<h2>Abstract</h2>
|
|
<p>This proposal defines the comprehensive chat interface standard for AI model interactions across the Hanzo ecosystem. It establishes the canonical implementation for conversational AI, including message formats, session management, streaming protocols, multimodal support, and Model Context Protocol (MCP) integration. All chat applications in the Hanzo ecosystem MUST implement this interface to ensure consistency and interoperability.</p>
|
|
<p><strong>Repository</strong>: <a href="https://github.com/hanzoai/chat">github.com/hanzoai/chat</a> <strong>Port</strong>: 3081 <strong>Status</strong>: Production-ready (LibreChat fork with Hanzo extensions)</p>
|
|
<h2>Specification</h2>
|
|
<h3>Core Data Models</h3>
|
|
<h4>Message Format</h4>
|
|
<pre><code class="lang-typescript">interface Message {
|
|
// Unique identifier
|
|
id: string;
|
|
|
|
// Message role in conversation
|
|
role: "user" | "assistant" | "system" | "function" | "tool";
|
|
|
|
// Message content (text, structured data, or multimodal)
|
|
content: string | MessageContent[];
|
|
|
|
// Metadata
|
|
timestamp: number;
|
|
model?: string;
|
|
tokens?: {
|
|
prompt: number;
|
|
completion: number;
|
|
total: number;
|
|
};
|
|
|
|
// Optional fields
|
|
name?: string; // For function/tool messages
|
|
function_call?: { // AI requesting function execution
|
|
name: string;
|
|
arguments: string;
|
|
};
|
|
tool_calls?: ToolCall[]; // Multiple tool invocations
|
|
|
|
// Multimodal attachments
|
|
attachments?: Attachment[];
|
|
|
|
// User feedback
|
|
feedback?: {
|
|
rating: number; // 1-5 stars
|
|
comment?: string;
|
|
};
|
|
}
|
|
|
|
interface MessageContent {
|
|
type: "text" | "image" | "file" | "code";
|
|
text?: string;
|
|
image_url?: {
|
|
url: string;
|
|
detail?: "low" | "high" | "auto";
|
|
};
|
|
file?: {
|
|
url: string;
|
|
mime_type: string;
|
|
name: string;
|
|
size: number;
|
|
};
|
|
code?: {
|
|
language: string;
|
|
content: string;
|
|
};
|
|
}
|
|
|
|
interface Attachment {
|
|
id: string;
|
|
type: "image" | "document" | "audio" | "video" | "code";
|
|
url: string;
|
|
name: string;
|
|
size: number;
|
|
mime_type: string;
|
|
metadata?: Record<string, any>;
|
|
}
|
|
|
|
interface ToolCall {
|
|
id: string;
|
|
type: "function";
|
|
function: {
|
|
name: string;
|
|
arguments: string;
|
|
};
|
|
}</code></pre>
|
|
<h4>Session Model</h4>
|
|
<pre><code class="lang-typescript">interface ChatSession {
|
|
id: string;
|
|
title: string;
|
|
messages: Message[];
|
|
model: string;
|
|
|
|
// Timestamps
|
|
created: number;
|
|
updated: number;
|
|
|
|
// User management
|
|
user_id: string;
|
|
shared_with?: string[]; // User IDs with access
|
|
public?: boolean; // Publicly accessible
|
|
|
|
// Configuration
|
|
settings: {
|
|
temperature?: number;
|
|
max_tokens?: number;
|
|
top_p?: number;
|
|
frequency_penalty?: number;
|
|
presence_penalty?: number;
|
|
stop_sequences?: string[];
|
|
system_prompt?: string;
|
|
};
|
|
|
|
// MCP tools
|
|
enabled_tools?: string[]; // Tool IDs from MCP registry
|
|
|
|
// Metadata
|
|
tags?: string[];
|
|
folder_id?: string;
|
|
archived?: boolean;
|
|
|
|
// Usage tracking
|
|
usage?: {
|
|
total_tokens: number;
|
|
total_cost: number; // In cents
|
|
message_count: number;
|
|
};
|
|
}
|
|
|
|
interface Folder {
|
|
id: string;
|
|
name: string;
|
|
user_id: string;
|
|
parent_id?: string; // For nested folders
|
|
created: number;
|
|
updated: number;
|
|
}</code></pre>
|
|
<h3>API Endpoints</h3>
|
|
<h4>Session Endpoints</h4>
|
|
<pre><code class="lang-yaml"># Create new session
|
|
POST /api/chat/sessions
|
|
Body:
|
|
title?: string
|
|
model: string
|
|
settings?: SessionSettings
|
|
Response:
|
|
session: ChatSession
|
|
|
|
# List sessions with pagination
|
|
GET /api/chat/sessions
|
|
Query:
|
|
page?: number (default: 1)
|
|
limit?: number (default: 20, max: 100)
|
|
folder_id?: string
|
|
archived?: boolean
|
|
search?: string
|
|
Response:
|
|
sessions: ChatSession[]
|
|
total: number
|
|
page: number
|
|
pages: number
|
|
|
|
# Get specific session
|
|
GET /api/chat/sessions/:id
|
|
Response:
|
|
session: ChatSession
|
|
|
|
# Update session
|
|
PATCH /api/chat/sessions/:id
|
|
Body:
|
|
title?: string
|
|
settings?: SessionSettings
|
|
tags?: string[]
|
|
folder_id?: string
|
|
archived?: boolean
|
|
Response:
|
|
session: ChatSession
|
|
|
|
# Delete session
|
|
DELETE /api/chat/sessions/:id
|
|
Response:
|
|
success: boolean
|
|
|
|
# Share session
|
|
POST /api/chat/sessions/:id/share
|
|
Body:
|
|
user_ids?: string[]
|
|
public?: boolean
|
|
Response:
|
|
share_url?: string</code></pre>
|
|
<h4>Message Operations</h4>
|
|
<pre><code class="lang-yaml"># Send message (streaming response)
|
|
POST /api/chat/sessions/:id/messages
|
|
Headers:
|
|
Accept: text/event-stream # For SSE streaming
|
|
Body:
|
|
content: string | MessageContent[]
|
|
attachments?: Attachment[]
|
|
tools?: string[] # MCP tool IDs to enable
|
|
Response:
|
|
Stream of SSE events (see Streaming Protocol)
|
|
|
|
# Edit message
|
|
PATCH /api/chat/messages/:id
|
|
Body:
|
|
content: string | MessageContent[]
|
|
Response:
|
|
message: Message
|
|
|
|
# Delete message
|
|
DELETE /api/chat/messages/:id
|
|
Response:
|
|
success: boolean
|
|
|
|
# Regenerate response
|
|
POST /api/chat/messages/:id/regenerate
|
|
Body:
|
|
model?: string # Override model
|
|
settings?: SessionSettings # Override settings
|
|
Response:
|
|
Stream of SSE events</code></pre>
|
|
<h4>File Operations</h4>
|
|
<pre><code class="lang-yaml"># Upload file for attachment
|
|
POST /api/chat/files
|
|
Headers:
|
|
Content-Type: multipart/form-data
|
|
Body:
|
|
file: File
|
|
session_id?: string
|
|
Response:
|
|
attachment: Attachment
|
|
|
|
# Get file
|
|
GET /api/chat/files/:id
|
|
Response:
|
|
File content with appropriate Content-Type
|
|
|
|
# Delete file
|
|
DELETE /api/chat/files/:id
|
|
Response:
|
|
success: boolean</code></pre>
|
|
<h3>Streaming Protocol</h3>
|
|
<p>Server-Sent Events (SSE) format for real-time streaming:</p>
|
|
<pre><code class="lang-typescript">// Token streaming
|
|
event: token
|
|
data: {"content": "Hello", "index": 0}
|
|
|
|
event: token
|
|
data: {"content": " world", "index": 1}
|
|
|
|
// Tool use
|
|
event: tool_call
|
|
data: {"id": "call_123", "name": "calculator", "arguments": "{\"expression\": \"2+2\"}"}
|
|
|
|
event: tool_result
|
|
data: {"id": "call_123", "result": "4"}
|
|
|
|
// Completion metadata
|
|
event: done
|
|
data: {
|
|
"message_id": "msg_456",
|
|
"model": "claude-3-opus",
|
|
"tokens": {
|
|
"prompt": 10,
|
|
"completion": 2,
|
|
"total": 12
|
|
},
|
|
"cost": 0.0024 // In dollars
|
|
}
|
|
|
|
// Error handling
|
|
event: error
|
|
data: {"code": "rate_limit", "message": "Rate limit exceeded"}</code></pre>
|
|
<h3>Model Context Protocol (MCP) Integration</h3>
|
|
<pre><code class="lang-typescript">interface MCPTool {
|
|
id: string;
|
|
name: string;
|
|
description: string;
|
|
parameters: JSONSchema;
|
|
handler: (params: any) => Promise<any>;
|
|
}
|
|
|
|
// Tool registration
|
|
POST /api/chat/tools
|
|
Body:
|
|
tool: MCPTool
|
|
Response:
|
|
id: string
|
|
|
|
// Tool execution (internal)
|
|
interface ToolExecution {
|
|
tool_id: string;
|
|
call_id: string;
|
|
parameters: any;
|
|
result?: any;
|
|
error?: string;
|
|
duration_ms: number;
|
|
}</code></pre>
|
|
<h3>WebSocket Support</h3>
|
|
<p>Alternative to SSE for bidirectional communication:</p>
|
|
<pre><code class="lang-javascript">// WebSocket connection
|
|
ws://localhost:3081/api/chat/ws
|
|
|
|
// Client → Server messages
|
|
{
|
|
"type": "session.join",
|
|
"session_id": "sess_123"
|
|
}
|
|
|
|
{
|
|
"type": "message.send",
|
|
"content": "Hello",
|
|
"attachments": []
|
|
}
|
|
|
|
{
|
|
"type": "message.stop" // Cancel generation
|
|
}
|
|
|
|
// Server → Client messages
|
|
{
|
|
"type": "token",
|
|
"content": "Hello"
|
|
}
|
|
|
|
{
|
|
"type": "message.complete",
|
|
"message": Message
|
|
}
|
|
|
|
{
|
|
"type": "error",
|
|
"error": {
|
|
"code": "invalid_session",
|
|
"message": "Session not found"
|
|
}
|
|
}</code></pre>
|
|
<h3>Authentication & Authorization</h3>
|
|
<pre><code class="lang-typescript">interface AuthContext {
|
|
user_id: string;
|
|
email: string;
|
|
roles: string[];
|
|
permissions: string[];
|
|
api_key?: string;
|
|
oauth_provider?: string;
|
|
}
|
|
|
|
// JWT-based authentication
|
|
interface JWTPayload {
|
|
sub: string; // User ID
|
|
email: string;
|
|
roles: string[];
|
|
exp: number;
|
|
iat: number;
|
|
}
|
|
|
|
// API key authentication
|
|
interface APIKey {
|
|
id: string;
|
|
key: string; // Hashed
|
|
name: string;
|
|
user_id: string;
|
|
permissions: string[];
|
|
created: number;
|
|
last_used?: number;
|
|
expires?: number;
|
|
}</code></pre>
|
|
<h3>Rate Limiting</h3>
|
|
<pre><code class="lang-yaml">Tiers:
|
|
free:
|
|
requests_per_minute: 20
|
|
requests_per_day: 500
|
|
max_tokens_per_request: 2000
|
|
concurrent_sessions: 3
|
|
|
|
pro:
|
|
requests_per_minute: 60
|
|
requests_per_day: 5000
|
|
max_tokens_per_request: 4000
|
|
concurrent_sessions: 10
|
|
|
|
enterprise:
|
|
requests_per_minute: 300
|
|
requests_per_day: unlimited
|
|
max_tokens_per_request: 32000
|
|
concurrent_sessions: unlimited</code></pre>
|
|
<h3>Error Handling</h3>
|
|
<pre><code class="lang-typescript">interface ErrorResponse {
|
|
error: {
|
|
code: string;
|
|
message: string;
|
|
details?: any;
|
|
timestamp: number;
|
|
request_id: string;
|
|
};
|
|
}
|
|
|
|
// Standard error codes
|
|
enum ErrorCode {
|
|
// Client errors (4xx)
|
|
INVALID_REQUEST = "invalid_request",
|
|
UNAUTHORIZED = "unauthorized",
|
|
FORBIDDEN = "forbidden",
|
|
NOT_FOUND = "not_found",
|
|
RATE_LIMITED = "rate_limited",
|
|
INVALID_MODEL = "invalid_model",
|
|
CONTEXT_LENGTH_EXCEEDED = "context_length_exceeded",
|
|
|
|
// Server errors (5xx)
|
|
INTERNAL_ERROR = "internal_error",
|
|
MODEL_ERROR = "model_error",
|
|
GATEWAY_ERROR = "gateway_error",
|
|
SERVICE_UNAVAILABLE = "service_unavailable"
|
|
}</code></pre>
|
|
<pre><code> │ File Storage │
|
|
│ (S3/Local) │
|
|
└──────────────┘</code></pre>
|
|
<h3>Deployment Configuration</h3>
|
|
<pre><code class="lang-yaml"># docker-compose.yml
|
|
version: '3.8'
|
|
|
|
services:
|
|
chat:
|
|
image: hanzoai/chat:latest
|
|
ports:
|
|
- "3081:3081"
|
|
environment:
|
|
- DATABASE_URL=postgresql://user:pass@db:5432/chat
|
|
- REDIS_URL=redis://redis:6379
|
|
- LLM_GATEWAY_URL=http://gateway:4000
|
|
- JWT_SECRET=${JWT_SECRET}
|
|
- S3_BUCKET=${S3_BUCKET}
|
|
depends_on:
|
|
- db
|
|
- redis
|
|
- gateway
|
|
|
|
db:
|
|
image: postgres:16
|
|
volumes:
|
|
- chat_data:/var/lib/postgresql/data
|
|
environment:
|
|
- POSTGRES_DB=chat
|
|
- POSTGRES_USER=user
|
|
- POSTGRES_PASSWORD=pass
|
|
|
|
redis:
|
|
image: redis:7-alpine
|
|
command: redis-server --appendonly yes
|
|
volumes:
|
|
- redis_data:/data
|
|
|
|
gateway:
|
|
image: hanzoai/llm-gateway:latest
|
|
ports:
|
|
- "4000:4000"
|
|
environment:
|
|
- OPENAI_API_KEY=${OPENAI_API_KEY}
|
|
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
|
|
# ... other provider keys
|
|
|
|
volumes:
|
|
chat_data:
|
|
redis_data:</code></pre>
|
|
<h3>Quick Start</h3>
|
|
<pre><code class="lang-bash"># Clone repository
|
|
git clone https://github.com/hanzoai/chat
|
|
cd chat
|
|
|
|
# Configure environment
|
|
cp .env.example .env
|
|
# Edit .env with your configuration
|
|
|
|
# Start with Docker
|
|
docker compose up -d
|
|
|
|
# Or start development server
|
|
npm install
|
|
npm run dev
|
|
|
|
# Access at http://localhost:3081</code></pre>
|
|
<h2>Security Considerations</h2>
|
|
<ol><li><strong>Input Validation</strong>: Sanitize all user inputs to prevent injection attacks</li><li><strong>Rate Limiting</strong>: Prevent abuse and ensure fair resource usage</li><li><strong>Authentication</strong>: Require authentication for all non-public endpoints</li><li><strong>Encryption</strong>: Use TLS for all communications, encrypt sensitive data at rest</li><li><strong>Audit Logging</strong>: Log all significant actions for compliance</li><li><strong>Content Filtering</strong>: Optional content moderation for enterprise deployments</li><li><strong>CORS Policy</strong>: Strict CORS configuration for API endpoints</li><li><strong>File Scanning</strong>: Scan uploaded files for malware</li><li><strong>Token Management</strong>: Secure storage and rotation of API keys</li><li><strong>Session Security</strong>: Implement session timeouts and secure cookies</li></ol>
|
|
<h2>Testing</h2>
|
|
<h3>Unit Tests</h3>
|
|
<pre><code class="lang-bash">npm run test:unit</code></pre>
|
|
<h3>Integration Tests</h3>
|
|
<pre><code class="lang-bash">npm run test:integration</code></pre>
|
|
<h3>Load Testing</h3>
|
|
<pre><code class="lang-bash"># Using k6
|
|
k6 run tests/load/chat-api.js</code></pre>
|
|
<h3>Security Testing</h3>
|
|
<pre><code class="lang-bash"># OWASP ZAP scan
|
|
npm run test:security</code></pre>
|
|
<h2>Compliance</h2>
|
|
<ul><li><strong>GDPR</strong>: User data deletion, export capabilities</li><li><strong>SOC 2</strong>: Audit trails, access controls</li><li><strong>HIPAA</strong>: Optional encryption and access controls for healthcare</li><li><strong>CCPA</strong>: California privacy requirements</li></ul>
|
|
<h2>Performance Targets</h2>
|
|
<ul><li><strong>Latency</strong>: < 100ms to first token</li><li><strong>Throughput</strong>: > 1000 concurrent sessions</li><li><strong>Availability</strong>: 99.9% uptime SLA</li><li><strong>Message Storage</strong>: Unlimited with pagination</li><li><strong>File Size</strong>: Up to 100MB per attachment</li></ul>
|
|
<h2>References</h2>
|
|
<ol><li><a href="./hip-4.md">HIP-4: LLM Gateway Standard</a></li><li><a href="./hip-10.md">HIP-10: Model Context Protocol</a></li><li><a href="https://docs.librechat.ai">LibreChat Documentation</a></li><li><a href="https://platform.openai.com/docs/api-reference/chat">OpenAI Chat Completions API</a></li><li><a href="https://docs.anthropic.com/claude/reference/messages">Anthropic Messages API</a></li></ol>
|
|
<h2>Copyright</h2>
|
|
<p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/hip-0011.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div>
|
|
</body></html> |