1. Quick Start

Mindstory uses an OpenAI-compatible API. Any OpenAI SDK client works out of the box.

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://azurekong.hertzai.com/v1",
    api_key="your-mindstory-key"
)

response = client.chat.completions.create(
    model="hevolve",
    messages=[{"role": "user", "content": "Explain quantum computing simply"}]
)
print(response.choices[0].message.content)

JavaScript / TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://azurekong.hertzai.com/v1',
  apiKey: 'your-mindstory-key'
});

const response = await client.chat.completions.create({
  model: 'hevolve',
  messages: [{ role: 'user', content: 'Hello from Mindstory SDK' }]
});

cURL

curl -X POST https://azurekong.hertzai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-mindstory-key" \
  -d '{
    "model": "hevolve",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

2. API Reference

POST /v1/chat/completions

OpenAI-compatible chat completions endpoint.

• model: "hevolve" (required)
• messages: Array of {role, content} (required)
• temperature: 0.0-2.0 (default: 0.7)
• max_tokens: Max output tokens (default: 512)
• stream: Boolean for streaming (default: false)

Response

{
  "id": "chatcmpl-abc123",
  "model": "hevolve",
  "choices": [{
    "message": {"role": "assistant", "content": "..."},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 50,
    "total_tokens": 70
  },
  "epistemic": {
    "confidence": 0.95,
    "uncertainty": 0.08,
    "should_defer": false
  }
}

The epistemic field is unique to HevolveAI — intrinsic confidence computed during the forward pass at zero additional cost.

Multimodal Input (Image + Text)

{
  "model": "hevolve",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "What do you see?"},
      {"type": "image_url", "image_url": {
        "url": "data:image/jpeg;base64,..."
      }}
    ]
  }]
}

POST /v1/corrections

Expert feedback — teach the model. It learns immediately with zero catastrophic forgetting.

{
  "original_response": "The capital of France is London",
  "corrected_response": "The capital of France is Paris",
  "expert_id": "developer-123",
  "confidence": 0.99,
  "explanation": "Factual correction"
}

GET /v1/stats

Learning statistics — experiences stored, corrections received, memory usage.

POST /v1/chat/completions (Streaming)

Set stream: true for Server-Sent Events:

data: {"id":"chatcmpl-1","choices":[{"delta":{"content":"Hello"}}]}
data: {"id":"chatcmpl-1","choices":[{"delta":{"content":" world"}}]}
data: [DONE]

Error Codes

Error response body: {"error": {"code": "rate_limited", "message": "...", "retry_after": 30}}

Rate Limits

Rate limit headers: X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After (seconds).

Authentication Flow

1. Register: POST to /register_student with name, email, phone
2. Login: POST to /login with email or phone — receives OTP
3. Verify OTP: POST to /verify_otp — receives OAuth2 token
4. Use token: Include Authorization: Bearer YOUR_TOKEN in all API calls
5. Kong API Key: For SDK access, use apikey: YOUR_MINDSTORY_KEY header (simpler, no OTP)

Webhooks / Callbacks

For async operations (video generation, long inference), configure a webhook URL:

POST /v1/chat/completions
{
  "model": "hevolve",
  "messages": [...],
  "webhook_url": "https://your-server.com/callback",
  "webhook_secret": "your-hmac-secret"
}

// Your server receives:
POST /callback
X-Webhook-Signature: sha256=...
{
  "id": "chatcmpl-abc123",
  "status": "completed",
  "choices": [...],
  "usage": {...}
}

For Pupit video generation, real-time progress is delivered via WAMP WebSocket on topic com.hertzai.pupit.{uid} — no polling needed.

SDK Versioning

The API follows semantic versioning. Breaking changes only in major versions. Current: v1. All endpoints are prefixed with /v1/.

• v1 — Current stable (chat completions, corrections, stats)
• v2 — Planned (streaming corrections, multi-turn memory, tool use)

Changelog is published at /v1/changelog and in the GitHub releases.

2.5 Hevolve Agent Extension

React works today. The script tag does not. The components are real and this page is running them: the floating chat pill in the corner is NunbaChatPill. Use the React snippet below and it works. The <script> route needs a single-file bundle that nothing currently builds, so that URL 404s, and @hertzai/mindstory is not on npm yet, so import the components from the repo rather than installing the package. Full reference in the Website widget guide.

Add the Hevolve AI agent as a floating chat helper on any page — the same widget you see on this docs page. It connects to your HART OS backend and can answer questions, generate videos, and run agent tasks conversationally.

Script Tag (Simplest)

<script>
var script = document.createElement('script');
script.src = "https://hevolve.hertzai.com/hevolve-widget.js";
script.onload = function() {
  HevolveWidget.init({
    agentName: 'Radha',        // or any agent name
    authToken: 'YOUR_TOKEN',   // from /verify_otp
    userId: 'USER_ID',
    emailAddress: 'user@example.com'
  });
};
document.body.appendChild(script);
</script>

React Component (For React Apps)

import { NunbaChatProvider, NunbaChatPill, NunbaChatPanel }
  from '@hertzai/mindstory/NunbaChat';

function App() {
  return (
    <NunbaChatProvider>
      <YourApp />
      <NunbaChatPill />
      <NunbaChatPanel />
    </NunbaChatProvider>
  );
}

Custom Events

// Open chat with a specific agent
window.dispatchEvent(new CustomEvent('nunba:selectAgent', {
  detail: { agentId: '49', agentName: 'Speech Therapy Agent' }
}));

// Widget events
widgetInstance.on('open', () => console.log('opened'));
widgetInstance.on('close', () => console.log('closed'));
widgetInstance.on('message', (data) => console.log(data));

Features

• Floating pill with typewriter greetings (desktop + mobile)
• Full chat panel with agent switching, TTS, @mentions
• Persistent message history (localStorage)
• Automatic retry with exponential backoff
• Diverse seeded avatars per agent
• Conversational video downloads — ask for a video, get inline player + download
• Works offline (local mode) and online (cloud mode)

3. SDKs & Libraries

4. Distribution Channels

• Nunba — Web/desktop app with built-in playground
• Mindstory (Play Store) — Mobile app with camera, voice, local-first inference
• Pupit Player — AI-powered talking head video generation
• Website Plugin — Drop-in chat widget for any website

5. Revenue Model (90/9/1)

All SDK usage fees flow through the 90/9/1 split:

SDK access is free forever. Developers pay per-token for API calls. Local inference is free — run HevolveAI on your own hardware.

6. Security

• All API traffic encrypted (TLS 1.3)
• API keys scoped per project
• Edge privacy: user data never leaves device unless explicitly shared
• Constitutional governance: 33 immutable terms enforced cryptographically
• No data used for training without explicit consent

7. Agentic Developer Onboarding

HART OS includes a built-in MCP (Model Context Protocol) server that lets Claude Code — or any MCP-compatible tool — orchestrate the entire platform agentically. Developers get an AI coding partner that understands the full stack.

Step 1: Connect Claude Code to HARTOS

# In your Claude Code MCP settings (~/.claude/mcp_servers.json):
{
  "mcpServers": {
    "hartos": {
      "command": "python",
      "args": ["-m", "integrations.mcp.mcp_server"],
      "cwd": "/path/to/HARTOS"
    }
  }
}

Step 2: Onboard into Kong (One Command)

# Via MCP tool (agentic — Claude does it for you):
> Use the onboard_kong tool

# Or via CLI:
python -m integrations.gateway.kong_onboard

# Queries existing Kong config, creates/updates:
# - Service: hevolve-completions → localhost:8000
# - Routes: /v1/chat/completions, /v1/corrections, /v1/stats
# - Plugins: key-auth, rate-limiting, cors, request-size-limiting

Step 3: Start Building

Available MCP tools for developers:

8. Premium Features & Pricing

Free Tier (Forever)

• SDK access and development
• Local inference (run HevolveAI on your hardware)
• Basic completions API (rate limited)
• Community support

Premium Features

Monetization

• Per-token API billing — metered through Kong, settled via 90/9/1
• Premium subscriptions — unlocks HD video, unlimited Pupit, priority compute
• Google AdMob — integrated in Hevolve Android app (free tier ad-supported)
• Peer-witnessed ad impressions — federated ad verification, no fraud

All revenue flows through the 90/9/1 split. Compute providers earn 90%. Premium features fund infrastructure (9%) and platform governance (1%).

9. Products

• HevolveAI Multimodal API — Text, image, audio, video inference. OpenAI-compatible. Epistemic confidence scoring. Expert corrections.
• Pupit Player — AI talking head video generation. Image + text/audio in, realistic lip-synced video out. Avatar warm-up, chunked streaming, vtoonify.
• Mindstory — Story video generation. Create narrative videos from text prompts. Download or share. Premium: longer videos, HD, no watermark.
• Hevolve Website Plugin — Drop-in chat widget for any website. Customizable themes. Streaming responses. Multimodal input.
• Hevolve Mobile (Play Store) — Published as "Mindstory". Camera input, voice I/O, local-first inference, Google AdMob for free tier.
• Nunba Desktop — Web/desktop app with built-in playground, developer portal, SDK package downloads.