The official inference shell SDKs for Python, JavaScript/TypeScript, and Swift.
All SDKs unwrap the { "data", "messages" } response envelope and raise RFC 9457 errors — see REST overview — response format.
Installation
1# Installation2pip install inferencesh34# With async support5pip install inferencesh[async]Quick Start
1from inferencesh import inference23client = inference(api_key="inf_your_key")45# Run an app and wait for result6result = client.tasks.run({7 "app": "infsh/flux",8 "input": {"prompt": "A sunset over mountains"}9})1011print(result["output"])Client structure
All SDKs expose namespaced APIs on the client. The JavaScript SDK covers the full REST surface; Python currently ships the core run/chat namespaces; Swift ships tasks, files, agents, chats, apps, sockets, and search.
| Namespace | Purpose | Python | JavaScript | Swift |
|---|---|---|---|---|
tasks | Run, get, cancel, list, and stream app tasks | ✓ | ✓ | ✓ |
files | Upload, list, get, and delete files | ✓ | ✓ | ✓ |
agents | Create agents and send messages | ✓ | ✓ | ✓ |
sockets / live() | Run a stream function and hold its socket | ✓ (async client) | ✓ | ✓ |
sessions | List, inspect, keepalive, and end sessions | ✓ | ✓ | — |
apps | List, create, and manage deployed apps | — | ✓ | ✓ |
chats | List and manage chats; getTrace() for agent observability | — | ✓ | ✓ (no getTrace) |
engines | List, drain, update, and extend cloud engine rentals | — | ✓ | — |
flows / flowRuns | Flow definitions (flows.updateVisibility) and run lifecycle (flowRuns.create, stream, streamTasks) | — | ✓ | — |
search | Programmatic /suggest and /search | — | ✓ | ✓ |
knowledge / skills | Knowledge and skill CRUD | — | ✓ | — |
teams, secrets, apiKeys, credentials, projects, mcpServers | Workspace and connector management | — | ✓ | — |
Top-level run() / uploadFile() (JavaScript) and run() / upload_file() (Python) are legacy aliases for tasks.run() and files.upload().
When a namespace is JavaScript-only, call the equivalent REST endpoint from Python or Swift until the SDK adds helpers.
Inspect and observability (JavaScript)
| Method | REST endpoint | Description |
|---|---|---|
client.tasks.getLogs(id) | GET /tasks/{id}/logs | Structured task log lines |
client.tasks.getTimings(id) | GET /tasks/{id}/timings | Phase durations from status events |
client.tasks.getTelemetry(id) | GET /tasks/{id}/telemetry | Time-series CPU, RAM, GPU, and volume samples |
client.chats.getTrace(id) | GET /chats/{id}/trace | Agent execution graph (nodes, edges, step counts) |
→ Tasks REST API · Agents REST API · Observability
Use inferencesh ≥ v0.7.8 or @inferencesh/sdk ≥ v0.6.12 for the full JavaScript REST surface (knowledge, workspaces, search, task observability helpers, agents.getA2ACard, and related namespaces).
→ Python SDK · JavaScript SDK · Swift SDK · REST overview — response format
What's in the SDK?
Running Apps
Execute AI apps on inference shell infrastructure.
- Running Apps — Basic task execution
- Streaming — Real-time progress updates
- Files — File uploads and downloads
Agent SDK
Build and interact with AI agents programmatically.
- Agent SDK Overview — Introduction
- Template Agents — Use existing agents
- Ad-hoc Agents — Create agents on-the-fly
- Building Tools — Define custom tools (client, app, HTTP/call, webhook, MCP)
Server Proxy
Protect API keys in frontend applications.
- Server Proxy — Proxy setup for all frameworks
- Vercel Deployment — Deploy with Vercel integration
Building Apps
Create your own apps to run on inference shell. → See Extend overview or Extending Apps for the app development guide.
Environment Variables
1from inferencesh import inference23client = inference() # reads INFERENCE_API_KEYTypeScript Support
The JavaScript SDK includes full TypeScript definitions:
1import type { Task, ApiTaskRequest, InferenceConfig } from '@inferencesh/sdk';Browser & Node.js
The JavaScript SDK works in both environments:
1// Node.js (CommonJS, Node 22.12+, @inferencesh/sdk >= 0.23.0)2const { inference } = require('@inferencesh/sdk');34// ES Modules / TypeScript5import { inference } from '@inferencesh/sdk';67// Browser (ESM CDN)8import { inference } from 'https://esm.sh/@inferencesh/sdk';Note: Never expose API keys in client-side code. Use the Server Proxy in production.
Requirements
- Python 3.8+
requestsfor sync clientaiohttpfor async client (optional)
- Node.js 22.12.0+ (npm
engines; required by theeventsource5.x dependency used for SSE streaming) - Modern browsers with
fetchsupport
- Swift 5.9+
- iOS 17+ / macOS 14+
- Linux (Foundation + FoundationNetworking)
Language references
- JavaScript SDK — Full TypeScript/JavaScript API
- Python SDK — Full Python API
- Swift SDK — Full Swift API (iOS, macOS, Linux)