Files
skills/public/hip-0011.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&#x27;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: &quot;user&quot; | &quot;assistant&quot; | &quot;system&quot; | &quot;function&quot; | &quot;tool&quot;;
// 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: &quot;text&quot; | &quot;image&quot; | &quot;file&quot; | &quot;code&quot;;
text?: string;
image_url?: {
url: string;
detail?: &quot;low&quot; | &quot;high&quot; | &quot;auto&quot;;
};
file?: {
url: string;
mime_type: string;
name: string;
size: number;
};
code?: {
language: string;
content: string;
};
}
interface Attachment {
id: string;
type: &quot;image&quot; | &quot;document&quot; | &quot;audio&quot; | &quot;video&quot; | &quot;code&quot;;
url: string;
name: string;
size: number;
mime_type: string;
metadata?: Record&lt;string, any&gt;;
}
interface ToolCall {
id: string;
type: &quot;function&quot;;
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: {&quot;content&quot;: &quot;Hello&quot;, &quot;index&quot;: 0}
event: token
data: {&quot;content&quot;: &quot; world&quot;, &quot;index&quot;: 1}
// Tool use
event: tool_call
data: {&quot;id&quot;: &quot;call_123&quot;, &quot;name&quot;: &quot;calculator&quot;, &quot;arguments&quot;: &quot;{\&quot;expression\&quot;: \&quot;2+2\&quot;}&quot;}
event: tool_result
data: {&quot;id&quot;: &quot;call_123&quot;, &quot;result&quot;: &quot;4&quot;}
// Completion metadata
event: done
data: {
&quot;message_id&quot;: &quot;msg_456&quot;,
&quot;model&quot;: &quot;claude-3-opus&quot;,
&quot;tokens&quot;: {
&quot;prompt&quot;: 10,
&quot;completion&quot;: 2,
&quot;total&quot;: 12
},
&quot;cost&quot;: 0.0024 // In dollars
}
// Error handling
event: error
data: {&quot;code&quot;: &quot;rate_limit&quot;, &quot;message&quot;: &quot;Rate limit exceeded&quot;}</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) =&gt; Promise&lt;any&gt;;
}
// 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
{
&quot;type&quot;: &quot;session.join&quot;,
&quot;session_id&quot;: &quot;sess_123&quot;
}
{
&quot;type&quot;: &quot;message.send&quot;,
&quot;content&quot;: &quot;Hello&quot;,
&quot;attachments&quot;: []
}
{
&quot;type&quot;: &quot;message.stop&quot; // Cancel generation
}
// Server → Client messages
{
&quot;type&quot;: &quot;token&quot;,
&quot;content&quot;: &quot;Hello&quot;
}
{
&quot;type&quot;: &quot;message.complete&quot;,
&quot;message&quot;: Message
}
{
&quot;type&quot;: &quot;error&quot;,
&quot;error&quot;: {
&quot;code&quot;: &quot;invalid_session&quot;,
&quot;message&quot;: &quot;Session not found&quot;
}
}</code></pre>
<h3>Authentication &amp; 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 = &quot;invalid_request&quot;,
UNAUTHORIZED = &quot;unauthorized&quot;,
FORBIDDEN = &quot;forbidden&quot;,
NOT_FOUND = &quot;not_found&quot;,
RATE_LIMITED = &quot;rate_limited&quot;,
INVALID_MODEL = &quot;invalid_model&quot;,
CONTEXT_LENGTH_EXCEEDED = &quot;context_length_exceeded&quot;,
// Server errors (5xx)
INTERNAL_ERROR = &quot;internal_error&quot;,
MODEL_ERROR = &quot;model_error&quot;,
GATEWAY_ERROR = &quot;gateway_error&quot;,
SERVICE_UNAVAILABLE = &quot;service_unavailable&quot;
}</code></pre>
<pre><code> │ File Storage │
│ (S3/Local) │
└──────────────┘</code></pre>
<h3>Deployment Configuration</h3>
<pre><code class="lang-yaml"># docker-compose.yml
version: &#x27;3.8&#x27;
services:
chat:
image: hanzoai/chat:latest
ports:
- &quot;3081:3081&quot;
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:
- &quot;4000:4000&quot;
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>: &lt; 100ms to first token</li><li><strong>Throughput</strong>: &gt; 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>