SDKs & Libraries

Python SDK

The NeuroCLI Python SDK provides convenient access to the NeuroCLI API from applications written in Python. It includes both synchronous and asynchronous clients, built-in retry mechanisms with exponential backoff via tenacity, and automatic JSON schema generation for function calling.

Note: The SDK was completely rewritten in version 0.2.1 to support asynchronous I/O and strict type hinting via Pydantic. Ensure you are on the latest version.

Installation

You can install the official NeuroCLI SDK directly from PyPI. Ensure you are using Python 3.7 or newer.

bash

pip install --upgrade neurocli-sdk

Authentication & Advanced Scopes

The SDK needs to be configured with your account's secret API key. You can generate one in your API Key Dashboard.

Advanced Scopes: NeuroCLI now supports highly granular API keys. You can restrict keys to neurocli-nano Only, neurocli medical gamma Only, or Read-Only Analytics to secure your production environments and control costs.

You can pass the key explicitly when instantiating the client:

python

from neurocli import NeuroCLI

client = NeuroCLI(
    api_key="PASTE_API_KEY_HERE"
)

Synchronous Client

The standard NeuroCLI client blocks the thread until the response is received. This is ideal for simple scripts or data-processing loops.

python

from neurocli import NeuroCLI

client = NeuroCLI(api_key="PASTE_API_KEY_HERE")

response = client.chat.completions.create(
    model="neurocli-delta",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the speed of light?"}
    ]
)

print(response.choices[0].message.content)

Async Client

For high-throughput web applications (like FastAPI or Sanic), we highly recommend using AsyncNeuroCLI. Under the hood, it utilizes httpx for non-blocking network I/O.

python

import asyncio
from neurocli import AsyncNeuroCLI

async def main():
    client = AsyncNeuroCLI(api_key="PASTE_API_KEY_HERE")

    response = await client.chat.completions.create(
        model="neurocli medical gamma",
        messages=[
            {"role": "user", "content": "Solve 24 * 72 step by step."}
        ]
    )
    print(response.choices[0].message.content)

asyncio.run(main())

Streaming Responses

Instead of waiting for the entire generation to complete, you can stream tokens back to your client exactly as they are generated by passing stream=True.

python

import asyncio
from neurocli import AsyncNeuroCLI

async def stream_chat():
    client = AsyncNeuroCLI(api_key="PASTE_API_KEY_HERE")

    stream = await client.chat.completions.create(
        model="neurocli-nano",
        messages=[{"role": "user", "content": "Write a poem about space."}],
        stream=True
    )

    async for chunk in stream:
        if chunk.choices[0].delta.content is not None:
            print(chunk.choices[0].delta.content, end="", flush=True)

asyncio.run(stream_chat())

Function Calling (Tools)

NeuroCLI seamlessly integrates with external tools. To make it incredibly easy, the SDK provides a wrap_function utility that automatically inspects your Python functions, reads their docstrings and type hints, and converts them into the exact JSON schema required by the API.

python

from neurocli import NeuroCLI, wrap_function

def get_current_weather(location: str, unit: str = "celsius"):
    """Get the current weather in a given location."""
    return f"The weather in {location} is 22 {unit}."

# Wrap the function to generate the tool schema
weather_tool = wrap_function(get_current_weather)

client = NeuroCLI(api_key="PASTE_API_KEY_HERE")

response = client.chat.completions.create(
    model="neurocli medical gamma",
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    tools=[weather_tool]
)

print(response.choices[0].message.tool_calls)

Prompt Registry

NeuroCLI allows you to decouple your system prompts from your codebase. Define prompts in your dashboard and call them via ID to update agent behaviors without redeploying code.

python

response = client.chat.completions.create(
    prompt_id="pr_123456789",
    model="neurocli-delta",
    messages=[
        {"role": "user", "content": "Tell me a joke."}
    ]
)

A/B Testing Models

Compare the quality, speed, or cost of two different models by using an A/B test routing ID. NeuroCLI handles the traffic splitting automatically based on your dashboard configuration.

python

response = client.chat.completions.create(
    model="abtest_abc123", # This will automatically route to Model A or Model B
    messages=[
        {"role": "user", "content": "Generate a report."}
    ]
)

Multi-Agent Swarm API

The Swarm API orchestrates a debate between three agents (Doctor, Critic, and Judge) behind a single endpoint to provide maximally safe and hallucination-free outputs.

python

response = client.swarm.chat(
    model="neurocli-swarm-engine",
    messages=[
        {"role": "user", "content": "Is it safe to mix Lisinopril and Spironolactone?"}
    ]
)

print("Final Answer:", response.choices[0].message.content)

# The transcript provides full transparency of the internal debate
for turn in response.transcript:
    print(f"[{turn.agent}] {turn.content}")

Platform Management (Logs, Alerts & Organizations)

The NeuroCLI Dashboard has been significantly upgraded to help you manage your SDK deployments:

Detailed Request Logs: Every request made through the SDK is logged. The dashboard features a new View Payload button that reveals the exact JSON request sent by the SDK, simplifying debugging.
Usage Alerts & Notifications: Set an alert threshold (e.g., 80%) in the dashboard. The backend tracks the usage from your SDK clients and will automatically trigger notifications when approaching your limits.
Organizations: You can now invite team members to share workspaces. API keys used in the SDK and their associated logs are securely tied to your Organization's shared billing account.
Streaming Playground with History: Before writing SDK code, you can use the newly upgraded Interactive Playground to test SSE streaming in real-time, save your prompts to local browser history, and copy the parameters to your Python/Node app.

Example: Testing a Webhook (Python)

python

from neurocli import NeuroCLI

client = NeuroCLI(api_key="PASTE_API_KEY_HERE")

# Programmatically trigger a retry for a specific webhook
response = client.webhooks.retry(webhook_id="wh_12345")
print(response)

Example: Inviting to Organization (Node.js)

typescript

import { NeuroCLI } from 'neurocli-sdk';

const client = new NeuroCLI({ apiKey: process.env.NEUROCLI_API_KEY });

async function inviteUser() {
  const org = await client.organizations.invite({
    orgId: 'org_9876',
    email: 'developer@example.com'
  });
  console.log('Invitation sent successfully');
}

Node.js / TypeScript SDK

The official NeuroCLI Node.js library provides convenient access to the NeuroCLI API from JavaScript and TypeScript applications. It provides fully typed request/response schemas and uses modern fetch under the hood.

Installation

Install the package via NPM, Yarn, or pnpm:

bash

npm install neurocli-sdk

Basic Usage

You can initialize the client with your API key and create chat completions using async/await.

typescript

import { NeuroCLI } from 'neurocli-sdk';

const client = new NeuroCLI({
  apiKey: process.env.NEUROCLI_API_KEY, // Automatically defaults to this env var
});

async function main() {
  const completion = await client.chat.completions.create({
    model: 'neurocli-delta',
    messages: [{ role: 'user', content: 'Explain quantum computing.' }],
  });

  console.log(completion.choices[0].message.content);
}

main();

Streaming Responses

The SDK supports AsyncIterables for streaming responses. Set stream: true and iterate over the chunks.

typescript

async function streamChat() {
  const stream = await client.chat.completions.create({
    model: 'neurocli-delta',
    messages: [{ role: 'user', content: 'Count to 10.' }],
    stream: true,
  });

  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content || '');
  }
}

streamChat();