SentinelMeshAI Documentation

Complete reference for the SentinelMeshAI AI Gateway — multi-model routing, self-learning optimisation, and enterprise-grade orchestration.

Core Concepts

Before integrating, these five concepts explain what SentinelMeshAI does differently from a direct LLM API call.

Request Lifecycle

Strategies

A strategy defines which models to call and how to combine their answers. The router automatically selects the best strategy per request based on learned performance. You can also request a strategy explicitly.

Tenancy & API Keys

Every API key maps to a tenant. Each tenant has its own rate limit, usage budget, billing tier, learning state, and WorldModel. Keys look like sm_live_... (production) or sm_test_... (testing, never billed).

Quickstart 5 min

Sign up at app.sentinelmeshai.com → Dashboard → API Keys → New Key. Your key starts with sm_live_.

bashCopycurl -X POST https://api.sentinelmeshai.com/run \
  -H "Authorization: Bearer sm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Explain quantum entanglement in one paragraph."}'

pythonCopyimport os, sentinelmeshai as sm

sm.api_key = os.getenv("SENTINELMESHAI_API_KEY")

result = sm.run("Explain quantum entanglement in one paragraph.")
print(result["output"])
# → "Quantum entanglement is a phenomenon..."
print(f"Model : {result['models_used']}")
print(f"Cost  : ${result['cost_usd']:.6f}")
print(f"Latency: {result['latency_ms']}ms")

javascriptCopyimport SentinelMeshAI from 'sentinelmeshai';

const sm = new SentinelMeshAI({ apiKey: process.env.SENTINELMESHAI_API_KEY });

const result = await sm.run("Explain quantum entanglement in one paragraph.");
console.log(result.output);
console.log(`Cost: $${result.cost_usd.toFixed(6)}`);
console.log(`Models: ${result.models_used.join(', ')}`);

goCopypackage main

import (
    "fmt"
    sm "github.com/sentinelmeshai/go-sdk"
)

func main() {
    client := sm.New(sm.Config{APIKey: os.Getenv("SENTINELMESHAI_API_KEY")})
    result, _ := client.Run("Explain quantum entanglement in one paragraph.")
    fmt.Println(result.Output)
    fmt.Printf("Cost: $%.6f\n", result.CostUSD)
}

{
  "output": "Quantum entanglement is a phenomenon where two particles...",
  "models_used": ["anthropic:claude-3-5-sonnet-20241022"],
  "strategy_used": "standard",
  "cost_usd": 0.000843,
  "latency_ms": 412,
  "confidence": 0.97,
  "cached": false,
  "trace_id": "tr_8f3a2b91c4d05e67"
}

Authentication

All requests require a Bearer token in the Authorization header.

httpCopyAuthorization: Bearer sm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Platform Architecture

AI Router — Bandit + Reinforcement Learning

The router uses a contextual LinUCB bandit to select the strategy for each request. After the response is returned, it observes a reward signal (response quality × inverse cost) and updates arm weights. Over time, it learns which strategies work best for your specific workload — automatically.

pythonCopy# Request a specific strategy explicitly (overrides the router)
result = await router.route(
    prompt    = "Debug this Python traceback...",
    strategy  = "code_specialist",   # pin to Codestral
    context   = {"temperature": 0.1, "max_tokens": 2048},
    tenant_id = "ten_abc123",
)

POST /run

POST /run-with-memory

pythonCopySESSION = "user_12345_chat_001"

# Turn 1
r1 = sm.run_with_memory("My name is Alex.", session_id=SESSION)

# Turn 2 — model remembers "Alex"
r2 = sm.run_with_memory("What's my name?", session_id=SESSION)
print(r2["output"])  # "Your name is Alex."

POST /run-cached

pythonCopy# First call — goes to LLM
r1 = sm.run_cached("What is the capital of France?")
print(r1["cached"])  # False, cost_usd: 0.000120

# Semantically similar call — served from cache
r2 = sm.run_cached("Tell me the capital city of France")
print(r2["cached"])  # True, cost_usd: 0.000000

POST /run-stream

pythonCopyimport asyncio, sentinelmeshai as sm

sm.api_key = "sm_live_..."

async def stream_example():
    async for chunk in sm.astream("Write a 200-word essay on recursion."):
        print(chunk, end="", flush=True)

asyncio.run(stream_example())

javascriptCopyconst sm = new SentinelMeshAI({ apiKey: process.env.SENTINELMESHAI_API_KEY });

const stream = await sm.stream("Write a 200-word essay on recursion.");
for await (const chunk of stream) {
  process.stdout.write(chunk);
}

GET /usage

Semantic Caching

SentinelMeshAI embeds every prompt using sentence-transformers/all-MiniLM-L6-v2 and compares cosine similarity against the cache. Hits with similarity > 0.92 are returned instantly at zero cost. The cache is per-tenant and persists for 24 hours.

pythonCopy# Use /run-cached endpoint, or add "use_cache": true to /run body
result = requests.post(API_URL + "/run-cached", ...)

# Check if cached
if result.json()["cached"]:
    print("Free! Served from semantic cache.")
else:
    print(f"LLM call — cost: ${result.json()['cost_usd']:.6f}")

Memory & Sessions

Sessions are identified by session_id. SentinelMeshAI stores the conversation window in a vector store (SQLite + in-memory embeddings) and prepends relevant context on each turn. Sessions expire after 7 days of inactivity.

Streaming Responses

Use the /run-stream endpoint for any response longer than ~100 tokens. Streaming reduces perceived latency to near-zero and allows progressive rendering in UI components.

Vision & Multimodal

Send images alongside prompts using base64 encoding. The vision pipeline routes to OpenAI GPT-4o (default) or Google Gemini 2.0 Flash depending on task type.

pythonCopyimport base64, requests

with open("chart.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

result = requests.post(
    "https://api.sentinelmeshai.com/vision/analyze",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "image": image_b64,
        "prompt": "Extract all data from this bar chart as JSON.",
        "vision_model": "gpt-4o"  # or "gemini-2.0-flash"
    }
).json()
print(result["output"])

Function Calling

Define tools as Python functions and register them with the ToolRegistry. The model decides when to call tools, SentinelMeshAI executes them and feeds results back — automatically, with loop protection (max 5 rounds).

pythonCopyfrom core.tools.base_tool  import BaseTool
from core.tools.tool_registry import ToolRegistry
from core.agents.tool_agent   import ToolAgent
from app import router

class WeatherTool(BaseTool):
    name        = "get_weather"
    description = "Get current weather for a city"
    async def execute(self, city: str) -> str:
        # Call your weather API here
        return f"72°F, sunny in {city}"

registry = ToolRegistry()
registry.register(WeatherTool())

agent = ToolAgent("assistant", router=router, tool_registry=registry)
result = await agent.run("What's the weather in Lagos right now?")
print(result.output)  # "It is currently 72°F and sunny in Lagos."

Webhooks

SentinelMeshAI can push events to your endpoint when key things happen: model training completes, usage thresholds are crossed, or benchmarks detect regressions.

pythonCopy# Register a webhook (POST /admin/webhook — requires X-Admin-Key)
requests.post(
    "https://api.sentinelmeshai.com/admin/webhook",
    headers={"X-Admin-Key": ADMIN_KEY},
    json={
        "url":    "https://yourapp.com/webhooks/sentinelmeshai",
        "events": ["model.trained", "usage.threshold", "benchmark.regression"],
        "secret": "your_webhook_secret"
    }
)

Error Codes

Retries & Timeouts

pythonCopyimport httpx, time

def call_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            r = httpx.post(
                "https://api.sentinelmeshai.com/run",
                headers={"Authorization": f"Bearer {API_KEY}"},
                json={"prompt": prompt},
                timeout=30.0
            )
            if r.status_code == 429:
                wait = int(r.headers.get("Retry-After", 2 ** attempt))
                time.sleep(wait)
                continue
            r.raise_for_status()
            return r.json()
        except httpx.TimeoutException:
            if attempt == max_retries - 1: raise
            time.sleep(2 ** attempt)
    raise RuntimeError("Max retries exceeded")

Model Catalog

📚 SentinelMeshAI Docs · Last updated April 2026 · v1.0.0
Tutorials · SDK Reference · Dashboard