Bluwing/Docsv0.9.0
Operational
API ReferenceConsole

Get started

  • Introduction
  • Quickstart
  • How it works

Build

  • Tool format
  • Matching hints
  • Toolsets and builds
  • Versions and live

Call

  • Resolve a request
  • Reading responses
  • OpenAI and Anthropic compatibility

Account

  • Authentication
  • Credits and billing
  • Limits
  • Errors
  • Security and data
  • FAQ

Call

OpenAI and Anthropic compatibility

Keep your SDK. Point it at Bluwing with model: "bluwing" for instant zero-overhead tool calling.

If your code already calls OpenAI's Chat Completions or Anthropic's Messages API with tools, you can switch tool selection and parameter extraction to Bluwing by simply changing your base_url and model. Responses return in the exact shape your code already parses.


#1. Unified Model: model: "bluwing" (Recommended)

When you specify model: "bluwing" (or "bluwing-router", "rednet"), you pass your inline tools array directly. Bluwing uses its high-speed in-house routing engines (MASON and MORTAR) without calling any third-party LLMs:

python
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.bluwing.si/v1",
    api_key=os.environ["BLUWING_API_KEY"],
)

completion = client.chat.completions.create(
    model="bluwing",
    messages=[
        {"role": "user", "content": "Charge customer cus_99214 for $250.00 USD"}
    ],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "payments_create_charge",
                "description": "Charge a customer payment method for a specified amount and currency.",
                "parameters": {
                    "type": "object",
                    "required": ["amount", "currency", "customer_id"],
                    "properties": {
                        "amount": {"type": "number", "description": "Charge amount in major currency units"},
                        "currency": {"type": "string", "enum": ["usd", "eur", "gbp"], "description": "ISO currency code"},
                        "customer_id": {"type": "string", "description": "Customer identifier e.g. cus_123"},
                    },
                },
            },
        }
    ],
)

for call in completion.choices[0].message.tool_calls or []:
    print(call.function.name, call.function.arguments)

Dynamic Tool Masking & Subsets

You do not need to create a new brick whenever you pass a different subset of tools:

  • Automatic Matching: The gateway hashes incoming tool schemas (name and 32-byte content hash) and searches your account's ready bricks in under 1 millisecond.
  • Instant Subset Routing: If your incoming tools are a subset ($T_{\text{in}} \subseteq T_{\text{brick}}$) of an existing 70-tool brick, Bluwing immediately executes on that pre-compiled brick in 35 milliseconds, with zero compilation delay.
  • Dynamic Masking: Tools not present in the current request's tools array are strictly masked out from MASON candidate retrieval and MORTAR grounding. The model cannot hallucinate or invoke unpassed tools.

Just-In-Time (JIT) Ephemeral Compilation

If you send a novel combination of tools that has never been compiled before:

  • Bluwing automatically triggers on-the-fly compilation via Kiln.
  • Resolves and returns your tool calls in that same single HTTP request.
  • Caches the compiled artifact for your account, giving all subsequent requests with those tools sub-40ms response times.

#2. Explicit Brick Pinning: model: "brick:<id>@<version>"

For production systems with pre-compiled, version-pinned catalogs, you can target a specific brick directly. In this mode, tools can be omitted because the brick already contains the catalog:

python
completion = client.chat.completions.create(
    model="brick:brk_7m2q9xk4hd3vfc8r@live",
    messages=[{"role": "user", "content": "Book Nok for four people tomorrow at 7pm"}],
)
javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.bluwing.si/v1",
  apiKey: process.env.BLUWING_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "brick:brk_7m2q9xk4hd3vfc8r@live",
  messages: [{ role: "user", content: "Book Nok for four people tomorrow at 7pm" }],
});

#3. How the Request is Processed

  • Input Prompt: The text is extracted from the last user message.
  • Multi-turn Context: Preceding user and assistant messages are preserved for context resolution.
  • Context Facts: Facts can be injected via a system or developer message starting with facts: followed by JSON:

``json {"role": "system", "content": "facts: {\"user_id\": \"usr_9421\", \"currency\": \"usd\"}"} ``

  • Tool Results: When following up after running tool calls, pass the results back with role: "tool" and the matching tool_call_id. Bluwing completes the turn with finish_reason: "stop" in ~40ms.
  • Sampling Parameters: Parameters like temperature, top_p, and seed are ignored because tool selection and parameter extraction are mathematically deterministic.
  • Streaming: stream: true is fully supported using standard Server-Sent Events (SSE).

#4. Response Mapping

Engine StateOpenAI Chat ResponseDescription
tool_callsfinish_reason: "tool_calls"Selected tools in message.tool_calls with schema-ordered JSON string arguments.
needs_inputfinish_reason: "stop"Missing parameter clarification question in message.content.
no_toolfinish_reason: "stop"Empty content / no tool calls. Fallback to conversational generation.
completefinish_reason: "stop"Received tool results, conversation turn concluded.

The full native metadata (calibrated confidence, grounding character offsets, latency timing) is attached as an extra top-level field rednet:

json
{
  "id": "chatcmpl-res_01m761t5pfe7p9tbx7wbfcyw0e",
  "object": "chat.completion",
  "created": 1794838695,
  "model": "bluwing",
  "choices": [ ... ],
  "usage": { "prompt_tokens": 18, "completion_tokens": 0, "total_tokens": 18 },
  "rednet": {
    "status": "complete",
    "timing_us": { "gateway": 210, "mason": 18450, "mortar": 2310, "total": 20970 }
  }
}

#5. Anthropic Messages Compatibility

POST /v1/messages accepts Anthropic's request schema (model, messages, system, tools, tool_choice) and replies with standard tool_use content blocks:

python
import anthropic, os

# Pass auth_token to populate "Authorization: Bearer <key>"
client = anthropic.Anthropic(
    base_url="https://api.bluwing.si",
    auth_token=os.environ["BLUWING_API_KEY"],
)

msg = client.messages.create(
    model="brick:brk_7m2q9xk4hd3vfc8r@live",
    max_tokens=256,
    messages=[{"role": "user", "content": "Refund order 4412"}],
)

for block in msg.content:
    if block.type == "tool_use":
        print(block.name, block.input)
Note

Bluwing reads your API key from Authorization: Bearer <KEY>. In Anthropic SDKs, pass it as auth_token (Python) or authToken (TypeScript).

PreviousReading responsesNext Authentication

Something unclear or missing? Write to [email protected] and we'll fix the page.

On this page

  • 1. Unified Model: model: "bluwing" (Recommended)
  • 2. Explicit Brick Pinning: model: "brick:<id>@<version>"
  • 3. How the Request is Processed
  • 4. Response Mapping
  • 5. Anthropic Messages Compatibility