Osaurus

https://docs.osaurus.ai
Admin
Osaurus is a native macOS LLM server that runs local language models on Apple Silicon with...
Tokens:53,346
Snippets:387
Trust Score:5
Update:10 months ago
Show doc for...
Tokens:
Raw
### Test the API

Source: https://docs.osaurus.ai/quickstart

Verify your Osaurus installation by sending a test request to the chat completions endpoint.

```APIDOC
## POST /v1/chat/completions

### Description
Endpoint to get chat completions from a language model.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **model** (string) - Required - The model to use for generating completions.
- **messages** (array) - Required - A list of message objects, each with a 'role' and 'content'.
- **max_tokens** (integer) - Optional - The maximum number of tokens to generate.
- **stream** (boolean) - Optional - Whether to stream the response.

### Request Example
```json
{
  "model": "llama-3.2-3b-instruct-4bit",
  "messages": [{"role":"user","content":"Hello! Tell me a fun fact about dinosaurs."}
  ],
  "max_tokens": 100
}
```

### Response
#### Success Response (200)
- **choices** (array) - A list of completion choices.
  - **message** (object) - The generated message.
    - **role** (string) - The role of the author (e.g., 'assistant').
    - **content** (string) - The content of the message.

#### Response Example
```json
{
  "id": "chatcmpl-12345",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "llama-3.2-3b-instruct-4bit",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Did you know that the Stegosaurus had a brain the size of a walnut?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 25,
    "total_tokens": 45
  }
}
```
```

--------------------------------

### Manual CLI Setup for Osaurus

Source: https://docs.osaurus.ai/installation

Sets up the Osaurus command-line interface (CLI) after a direct download installation. This involves creating a symbolic link to the CLI executable or adding it to the system's PATH.

```shell
# Create symlink to CLI
sudo ln -sf /Applications/Osaurus.app/Contents/MacOS/osaurus /usr/local/bin/osaurus

# Verify installation
osaurus --version
```

```shell
echo 'export PATH="/Applications/Osaurus.app/Contents/MacOS:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

--------------------------------

### Osaurus Command Line Interface Commands

Source: https://docs.osaurus.ai/quickstart

Provides essential commands for managing the Osaurus server from the terminal, including starting, stopping, checking status, and opening the UI.

```shell
# Start server
osaurus serve --port 1337

# Enable LAN access
osaurus serve --port 1337 --expose

# Check status
osaurus status

# Stop server
osaurus stop

# Open UI
osaurus ui
```

--------------------------------

### JavaScript/TypeScript Installation for OpenAI

Source: https://docs.osaurus.ai/sdk-examples

Provides instructions for installing the `openai` npm package using either npm or yarn. This is a prerequisite for using the JavaScript/TypeScript examples for Osaurus AI.

```bash
npm install openai
# or
yarn add openai
```

--------------------------------

### Streaming Responses Example

Source: https://docs.osaurus.ai/quickstart

Demonstrates how to receive streaming responses from the Osaurus API using curl, suitable for applications requiring real-time output. The '-N' flag prevents buffering.

```shell
curl -N http://127.0.0.1:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.2-3b-instruct-4bit",
    "messages": [{"role":"user","content":"Explain quantum computing in simple terms"}],
    "stream": true
  }'
```

--------------------------------

### Install Python OpenAI SDK

Source: https://docs.osaurus.ai/sdk-examples

Installs the 'openai' Python package, which is used to interact with the Osaurus AI's OpenAI-compatible API. This is a prerequisite for running the subsequent Python examples.

```shell
pip install openai  
```

--------------------------------

### Verify Osaurus Installation

Source: https://docs.osaurus.ai/installation

Commands to verify the Osaurus installation by checking the CLI version, starting the server, checking its status, and stopping the server.

```shell
# Check CLI version
osaurus --version

# Test server startup
osaurus serve

# In another terminal, check status
osaurus status

# Stop server
osaurus stop
```

--------------------------------

### Quick Start Commands for Osaurus CLI

Source: https://docs.osaurus.ai/cli

Provides essential commands for initial setup and usage of the Osaurus CLI, including starting the server, accessing the UI, checking status, and running interactive chat sessions.

```bash
# Start the server  osaurus serve  

# Open the UI  osaurus ui  

# Check status  osaurus status  

# Interactive chat  osaurus run llama-3.2-3b-instruct-4bit  
```

--------------------------------

### Install Plugin Locally

Source: https://docs.osaurus.ai/plugin-authoring

Install the built and signed plugin to the Osaurus tools directory.

```APIDOC
## Install Plugin Locally

### Description
Installs the current plugin to the local Osaurus tools directory for development and testing.

### Method
CLI Command

### Endpoint
n/a

### Parameters
#### CLI Arguments
- **osaurus tools install .** (string) - Required - Installs the plugin from the current directory.

### Request Example
```bash
osaurus tools install .
```

### Response
#### Success Response
Installs the plugin to:
```
~/Library/Application Support/com.dinoki.osaurus/Tools/<plugin_id>/<version>/
```
```

--------------------------------

### Creative Writing Example Request

Source: https://docs.osaurus.ai/quickstart

Generates a haiku about coding late at night using the Osaurus API via curl. It specifically extracts the content of the AI's response.

```shell
curl -s http://127.0.0.1:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.2-3b-instruct-4bit",
    "messages": [{"role":"user","content":"Write a haiku about coding late at night"}]
  }' | jq -r '.choices[0].message.content'
```

--------------------------------

### JavaScript Integration with Osaurus Fetch API

Source: https://docs.osaurus.ai/quickstart

Shows how to make API calls to Osaurus from JavaScript using the Fetch API. This example sends a chat completion request and logs the response content.

```javascript
const response = await fetch("http://127.0.0.1:1337/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "llama-3.2-3b-instruct-4bit",
    messages: [{ role: "user", content: "What's the weather like on Mars?" }],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);
```

--------------------------------

### List Available Models

Source: https://docs.osaurus.ai/quickstart

Retrieve a list of all available models that can be used with the Osaurus API.

```APIDOC
## GET /v1/models

### Description
Lists all the models available for use with the Osaurus API, including system models like 'foundation' if available.

### Method
GET

### Endpoint
/v1/models

### Parameters
None

### Request Example
```bash
curl -s http://127.0.0.1:1337/v1/models | jq
```

### Response
#### Success Response (200)
- **data** (array) - An array of model objects.
  - **id** (string) - The unique identifier of the model (e.g., 'llama-3.2-3b-instruct-4bit', 'foundation').
  - Other model-specific details...

#### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "llama-3.2-3b-instruct-4bit",
      "object": "model",
      "created": 1700000000,
      "owned_by": "user",
      "permission": []
    },
    {
      "id": "foundation",
      "object": "model",
      "created": 1700000000,
      "owned_by": "apple",
      "permission": []
    }
  ]
}
```
```

--------------------------------

### Example Tool with System Requirement

Source: https://docs.osaurus.ai/plugin-authoring

An example of a tool definition in `manifest.json` that requires the `automation` system permission.

```APIDOC
## Example Tool with System Requirement

### Description
Demonstrates how to define a tool in `manifest.json` that requires the `automation` permission to execute AppleScript commands.

### Method
JSON Object

### Endpoint
n/a

### Parameters
#### JSON Fields
- **id** (string) - Required - `"run_applescript"`.
- **description** (string) - Required - `"Execute AppleScript commands"`.
- **parameters** (object) - Required - Defines the input parameters.
  - **type**: `"object"`
  - **properties**: Defines the `script` parameter.
    - **script** (object)
      - **type**: `"string"`
      - **description**: `"The AppleScript code to execute"`
  - **required**: `["script"]`
- **requirements** (array) - Required - `["automation"]`.
- **permission_policy** (string) - Optional - `"ask"`.
```

--------------------------------

### System Prompt Configuration Example

Source: https://docs.osaurus.ai/models

Demonstrates how to configure a system prompt for a specific request. System prompts help define the behavior and persona of the AI model.

```APIDOC
## System Prompt Configuration Example

### Description
This example illustrates how to include a system prompt within your API request to guide the model's responses. System prompts are particularly useful for setting the AI's persona, defining its task, or providing high-level instructions.

### Parameters
#### Request Body
- **model** (string) - Required - The model ID to use (e.g., `"llama-3.2-3b-instruct-4bit"`).
- **messages** (array) - Required - An array of message objects.
  - **role** (string) - Required - The role of the message sender. For system prompts, this must be `"system"`.
  - **content** (string) - Required - The content of the system prompt.
  - **role** (string) - Required - The role of the user message sender (`"user"`).
  - **content** (string) - Required - The content of the user's message.

### Request Example
```json
{
  "model": "llama-3.2-3b-instruct-4bit",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful, concise assistant."
    },
    {
      "role": "user",
      "content": "Explain quantum computing"
    }
  ]
}
```
```

--------------------------------

### Build Osaurus from Source

Source: https://docs.osaurus.ai/installation

Guides through cloning the Osaurus repository and building the application using Xcode, suitable for development or customization. It requires Xcode, Command Line Tools, and Git.

```shell
# Clone the repository
git clone https://github.com/dinoki-ai/osaurus.git
cd osaurus

# Open in Xcode
open osaurus.xcworkspace

# Build and run the "osaurus" scheme
# Or use Xcode: Product → Build (⌘B)
```

--------------------------------

### Install Osaurus using Homebrew

Source: https://docs.osaurus.ai/installation

Installs the Osaurus application, its command-line interface (CLI), and sets up automatic updates via Homebrew. This is the recommended installation method.

```shell
brew install --cask osaurus
```

--------------------------------

### Code Generation Example Request

Source: https://docs.osaurus.ai/quickstart

Requests Python code for reversing a string without built-in functions from Osaurus using curl. The output is the generated code.

```shell
curl -s http://127.0.0.1:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.2-3b-instruct-4bit",
    "messages": [{"role":"user","content":"Write a Python function to reverse a string without using built-in functions"}]
  }' | jq -r '.choices[0].message.content'
```

--------------------------------

### Install Plugin Locally

Source: https://docs.osaurus.ai/plugin-authoring

Command to install the locally built and signed plugin into the Osaurus application support directory. It shows the typical installation path.

```bash
osaurus tools install .

```

```text
~/Library/Application Support/com.dinoki.osaurus/Tools/<plugin_id>/<version>/

```

--------------------------------

### Manual Installation and PATH Setup for Osaurus CLI

Source: https://docs.osaurus.ai/cli

Instructions for manually setting up the Osaurus CLI if the 'osaurus' command is not found after installation. This involves creating a symbolic link or adding the CLI to the system's PATH.

```bash
# Quick symlink  
ln -sf "/Applications/Osaurus.app/Contents/MacOS/osaurus" "$(brew --prefix)/bin/osaurus"  

# Or add to PATH  
echo 'export PATH="/Applications/Osaurus.app/Contents/MacOS:$PATH"' >> ~/.zshrc  
source ~/.zshrc  
```

--------------------------------

### Build and Copy Plugin Binary (Swift)

Source: https://docs.osaurus.ai/plugin-authoring

Steps to compile a Swift plugin in release mode and copy the resulting dynamic library to the project root for signing and installation.

```bash
swift build -c release

# Copy the built dylib
cp .build/release/libMyPlugin.dylib ./libMyPlugin.dylib

```

--------------------------------

### Manifest Tool Definition Example (JSON)

Source: https://docs.osaurus.ai/plugin-authoring

An example of a tool definition within the manifest.json, showcasing the use of system requirements like 'automation' for executing AppleScript.

```json
{
  "id": "run_applescript",
  "description": "Execute AppleScript commands",
  "parameters": {
    "type": "object",
    "properties": {
      "script": { "type": "string" }
    },
    "required": ["script"]
  },
  "requirements": ["automation"],
  "permission_policy": "ask"
}

```

--------------------------------

### Osaurus Plugin Development Workflow

Source: https://docs.osaurus.ai/cli

A step-by-step guide for plugin development using Osaurus. It covers creating a new plugin, building it, installing it locally for testing, and verifying its installation.

```bash
# Create a new plugin  osaurus tools create MyTool --language swift  
cd MyTool  

# Build and test  
swift build -c release  osaurus tools install .  

# Check it's installed  osaurus tools list  
```

--------------------------------

### Check and Use Apple Foundation Model

Source: https://docs.osaurus.ai/quickstart

Shows how to check for the availability of Apple's 'foundation' model and then use it for chat completions via curl. Requires macOS 13 Tahoe or later.

```shell
# Check availability
curl -s http://127.0.0.1:1337/v1/models | jq '.data[] | select(.id=="foundation")'

# Use foundation model
curl -s http://127.0.0.1:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "foundation",
    "messages": [{"role":"user","content":"What makes Apple Silicon special?"}]
  }' | jq
```

--------------------------------

### OllamaKit (Swift)

Source: https://docs.osaurus.ai/integrations

Example of using OllamaKit to interact with the Osaurus API for chat completions.

```APIDOC
## Chat Completion (OllamaKit)

### Description
Uses the OllamaKit library to perform chat completions with an Osaurus instance.

### Method
POST

### Endpoint
/v1/chat/completions (via OllamaKit)

### Parameters
- **baseURL** (URL) - Required - The base URL of the Osaurus instance.
- **model** (string) - Required - The name of the model to use.
- **messages** (array of OllamaKit.Message) - Required - The conversation history.

### Request Example
```swift
let client = OllamaKit(baseURL: URL(string: "http://127.0.0.1:1337")!)
let response = try await client.chat(
    model: "llama-3.2-3b-instruct-4bit",
    messages: [.user("Hello!")]
)
```

### Response
#### Success Response
- **message** (OllamaKit.Message) - The model's response.
  - **content** (string) - The generated text.
```

--------------------------------

### Example Model Naming Convention

Source: https://docs.osaurus.ai/models

Illustrates the standard naming convention used by Osaurus for its models. This format helps in identifying the model family, version, size, variant, and quantization.

```Text
{model-family}-{version}-{size}-{variant}-{quantization}
```

--------------------------------

### Sign with Minisign and Publish Release

Source: https://docs.osaurus.ai/plugin-authoring

This snippet demonstrates how to install Minisign, generate a key pair, sign a zip archive, and structure a plugin manifest JSON file for publishing a release. It includes steps for uploading artifacts and submitting a pull request for validation.

```shell
# Install Minisign
brew install minisign

# Generate key pair (once)
minisign -G -p minisign.pub -s minisign.key

# Sign the zip
minisign -S -s minisign.key -m mytool-macos-arm64.zip
```

```json
{
  "plugin_id": "com.yourcompany.mytool",
  "name": "My Tool",
  "homepage": "https://github.com/yourcompany/mytool",
  "license": "MIT",
  "authors": ["Your Name"],
  "capabilities": {
    "tools": [{"name": "my_tool", "description": "Does something"}]
  },
  "public_keys": {
    "minisign": "RWxxxxxxxxxxxxxxxx"
  },
  "versions": [{
    "version": "1.0.0",
    "release_date": "2025-01-15",
    "notes": "Initial release",
    "requires": {"osaurus_min_version": "0.5.0"},
    "artifacts": [{
      "os": "macos",
      "arch": "arm64",
      "url": "https://github.com/yourcompany/mytool/releases/download/v1.0.0/mytool-macos-arm64.zip",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "minisign": {
        "signature": "RWxxxxxxxxxxxxxxxx",
        "key_id": "xxxxxxxx"
      }
    }]
  }]
}
```

--------------------------------

### Scaffold, Build, and Install Osaurus Swift Plugin

Source: https://docs.osaurus.ai/developer

Commands to scaffold a new Swift plugin using the Osaurus CLI, build it in release mode, and install it locally. This process is for extending Osaurus with custom tools.

```shell
# Scaffold a new Swift plugin  osaurus tools create MyPlugin --language swift  
cd MyPlugin  
  
# Build  
swift build -c release  
  
# Install locally  osaurus tools install .  

```

--------------------------------

### Osaurus Development Setup Workflow

Source: https://docs.osaurus.ai/cli

A common workflow for setting up a development environment with Osaurus. It includes starting the server on a custom port, checking available models via API, and running an interactive chat session for testing.

```bash
# Start server with custom port  osaurus serve --port 8080  

# In another terminal, check available models  
curl http://127.0.0.1:8080/v1/models | jq  

# Interactive chat for testing  osaurus run llama-3.2-3b-instruct-4bit  
```

--------------------------------

### Chat Completions API (Apple Foundation Models)

Source: https://docs.osaurus.ai/models

Example of how to use Apple Foundation Models via the OpenAI-compatible API. This endpoint allows for chat-based interactions with system-integrated models.

```APIDOC
## POST /v1/chat/completions

### Description
This endpoint allows you to interact with Apple Foundation Models using a chat-based interface. The `model` parameter should be set to `"foundation"` to utilize these system-integrated models.

### Method
POST

### Endpoint
`http://127.0.0.1:1337/v1/chat/completions`

### Parameters
#### Request Body
- **model** (string) - Required - The model ID to use. For Apple Foundation Models, this should be `"foundation"`.
- **messages** (array) - Required - An array of message objects representing the conversation history.
  - **role** (string) - Required - The role of the message sender (e.g., `"user"`, `"system"`, `"assistant"`).
  - **content** (string) - Required - The content of the message.

### Request Example
```json
{
  "model": "foundation",
  "messages": [{"role": "user", "content": "Hello"}]
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the completion.
- **object** (string) - Type of object returned (e.g., `"chat.completion"`).
- **created** (integer) - Unix timestamp of creation.
- **model** (string) - The model used for the completion.
- **choices** (array) - An array of completion choices.
  - **message** (object) - The message content from the model.
    - **role** (string) - The role of the message sender (`"assistant"`).
    - **content** (string) - The generated message content.
  - **finish_reason** (string) - The reason the model stopped generating tokens (e.g., `"stop"`, `"length"`).
  - **index** (integer) - Index of the choice.
- **usage** (object) - Usage statistics for the request.
  - **prompt_tokens** (integer) - Number of tokens in the prompt.
  - **completion_tokens** (integer) - Number of tokens in the completion.
  - **total_tokens** (integer) - Total tokens used.

#### Response Example
```json
{
  "id": "chatcmpl-12345",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "foundation",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}
```
```

--------------------------------

### Python Integration with Osaurus OpenAI SDK

Source: https://docs.osaurus.ai/quickstart

Demonstrates how to use the OpenAI Python SDK to interact with a locally running Osaurus server. It configures the client for the local endpoint and makes a chat completion request.

```python
from openai import OpenAI

# Configure for local server
client = OpenAI(
    base_url="http://127.0.0.1:1337/v1",
    api_key="not-needed"
)

# Make a request
response = client.chat.completions.create(
    model="llama-3.2-3b-instruct-4bit",
    messages=[
        {"role": "user", "content": "Write a joke about programming"}
    ]
)

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

--------------------------------

### React - POST /v1/chat/completions

Source: https://docs.osaurus.ai/integrations

Example of making a chat completion request from a React application using the fetch API.

```APIDOC
## POST /v1/chat/completions (React)

### Description
Initiates a chat completion request from a React frontend using the fetch API.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The name of the model to use for generation.
- **messages** (array) - Required - An array of message objects representing the conversation history.
  - **role** (string) - Required - The role of the author ('user' or 'assistant').
  - **content** (string) - Required - The content of the message.

### Request Example
```javascript
async function chat(message) {
  const response = await fetch('http://127.0.0.1:1337/v1/chat/completions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      model: 'llama-3.2-3b-instruct-4bit',
      messages: [{ role: 'user', content: message }]
    })
  });

  const data = await response.json();
  return data.choices[0].message.content;
}
```

### Response
#### Success Response (200)
- **choices** (array) - A list of completion choices.
  - **message** (object) - The message content from the model.
    - **content** (string) - The generated text response.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "content": "Hello there! How can I help you today?"
      }
    }
  ]
}
```
```

--------------------------------

### LangChain Integration with Chains

Source: https://docs.osaurus.ai/integrations

Build complex LLM chains with LangChain by integrating Osaurus. This example demonstrates a simple translation chain using a prompt template, the Osaurus LLM, and an output parser.

```python
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful translator."),
    ("human", "Translate to French: {text}")
])

chain = prompt | llm | StrOutputParser()
result = chain.invoke({"text": "Hello, world!"})
```

--------------------------------

### Osaurus Server Starting Configuration Schema

Source: https://docs.osaurus.ai/shared-configuration

This JSON schema represents the minimal metadata published by the Osaurus server when it is in the 'starting' state. It includes a unique instance ID, the last update timestamp, and the current health status. This configuration is used by other applications to detect that an Osaurus instance is initializing.

```json
{
  "instanceId": "f26f8b59-2b64-4c57-8c5a-5a1ce9f9b4a8",
  "updatedAt": "2025-09-08T12:34:56Z",
  "health": "starting"
}
```

--------------------------------

### Python Chat Completion with System Prompt using Osaurus

Source: https://docs.osaurus.ai/sdk-examples

Illustrates how to use a system prompt in Python for chat completions with Osaurus. The system prompt guides the AI's behavior, in this case, acting as a helpful coding tutor. It includes parameters for temperature and max tokens.

```python
response = client.chat.completions.create(  
    model="llama-3.2-3b-instruct-4bit",  
    messages=[  
        {"role": "system", "content": "You are a helpful coding tutor. Explain concepts simply."},  
        {"role": "user", "content": "What is recursion?"}  
    ],  
    temperature=0.7,  
    max_tokens=300  
)  
  
print(response.choices[0].message.content)  
```

--------------------------------

### Plugin Manifest Structure (JSON)

Source: https://docs.osaurus.ai/plugin-authoring

Example JSON structure for a plugin's manifest file, defining its ID, version, description, and tool capabilities with parameters and requirements.

```json
{
  "plugin_id": "com.example.mytool",
  "version": "1.0.0",
  "description": "My awesome tool",
  "capabilities": {
    "tools": [
      {
        "id": "my_tool",
        "description": "Does something useful",
        "parameters": {
          "type": "object",
          "properties": {
            "input": {
              "type": "string",
              "description": "The input to process"
            }
          },
          "required": ["input"]
        },
        "requirements": [],
        "permission_policy": "ask"
      }
    ]
  }
}

```

--------------------------------

### Clone and Build Osaurus Project

Source: https://docs.osaurus.ai/developer

Instructions to clone the Osaurus repository using Git, open the project in Xcode, and build the application. Assumes Git is installed and the user has the necessary permissions.

```shell
# Clone the repository  
git clone https://github.com/dinoki-ai/osaurus.git  
cd osaurus  
  
# Open in Xcode  
open osaurus.xcworkspace  
  
# Build and run the "osaurus" scheme  
# Press ⌘R or Product → Run  

```

--------------------------------

### Oosaurus AI Plugin Manifest with Publishing Metadata

Source: https://docs.osaurus.ai/plugin-authoring

An example `manifest.json` file for an Oosaurus AI plugin, extended with metadata required for publishing to the registry. Includes fields like homepage, license, and authors alongside the core plugin details and capabilities.

```json
{
  "plugin_id": "com.yourcompany.mytool",
  "version": "1.0.0",
  "description": "My tool description",
  "homepage": "https://github.com/yourcompany/mytool",
  "license": "MIT",
  "authors": ["Your Name"],
  "capabilities": { ... }
}
```

--------------------------------

### Scaffold and Install a New Swift Plugin

Source: https://docs.osaurus.ai/tools

Demonstrates the process of creating a new plugin using Swift. It includes scaffolding the plugin, building it locally, and then installing it into the Osaurus environment.

```bash
# Scaffold a new Swift pluginosaurus tools create MyPlugin --language swift

# Build and install locally
cd MyPlugin
swift build -c releaseosaurus tools install .
```

--------------------------------

### Test Osaurus API with Curl

Source: https://docs.osaurus.ai/quickstart

Verifies the Osaurus installation by sending a chat completion request to the local server using curl. It expects a JSON response containing the model's answer.

```shell
curl -s http://127.0.0.1:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.2-3b-instruct-4bit",
    "messages": [{"role":"user","content":"Hello! Tell me a fun fact about dinosaurs."}]
  }' | jq
```

--------------------------------

### MCP Server Integration

Source: https://docs.osaurus.ai/integrations

Osaurus acts as a full Model Context Protocol (MCP) server. Connect MCP clients to grant AI agents access to your installed tools. Configuration examples are provided for Cursor, Claude Desktop, and generic MCP clients.

```APIDOC
## MCP Server Integration

Osaurus provides a Model Context Protocol (MCP) server for connecting AI agents to installed tools.

### Cursor MCP Configuration

Add the following to your Cursor MCP settings (Settings → Features → MCP Servers):

```json
{
  "mcpServers": {
    "osaurus": {
      "command": "osaurus",
      "args": ["mcp"]
    }
  }
}
```

Alternatively, edit `~/.cursor/mcp.json` directly.

### Claude Desktop MCP Configuration

Add the following to your Claude Desktop configuration at `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "osaurus": {
      "command": "osaurus",
      "args": ["mcp"]
    }
  }
}
```

### Other MCP Clients Configuration

For any MCP client supporting stdio transport:

```json
{
  "mcpServers": {
    "osaurus": {
      "command": "osaurus",
      "args": ["mcp"]
    }
  }
}
```

The `osaurus mcp` command proxies the MCP protocol over stdio, auto-launches Osaurus if needed, and exposes all installed tools.
```

--------------------------------

### System Prompts with Foundation Model (Python Example)

Source: https://docs.osaurus.ai/models/apple-intelligence

Illustrates how to use system prompts with the 'foundation' model via the OpenAI Python client, ensuring consistent assistant behavior.

```APIDOC
## System Prompts with Foundation Models

### Description
Foundation Models support system prompts to guide the AI's behavior and ensure consistent responses. This example uses the OpenAI Python client to demonstrate setting a system prompt.

### Method
N/A (Illustrative Code)

### Endpoint
N/A (Uses existing Chat Completions endpoint)

### Parameters
N/A

### Request Example
```python
from openai import OpenAI

# Configure the client to use the local Osaurus endpoint
client = OpenAI(base_url="http://127.0.0.1:1337/v1", api_key="not-needed")

# Make a chat completion request with a system prompt
response = client.chat.completions.create(
    model="foundation",
    messages=[
        {"role": "system", "content": "You are a helpful coding assistant. Always include comments in code examples."},
        {"role": "user", "content": "Write a Python function to calculate factorial"}
    ]
)

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

### Response
#### Success Response (200)
- The response will be a chat completion object containing the assistant's message, which adheres to the system prompt instructions.

#### Response Example (Conceptual)
```python
# Factorial function with comments as requested by the system prompt
def factorial(n):
    """Calculates the factorial of a non-negative integer."""
    if n == 0:
        return 1  # Base case: factorial of 0 is 1
    else:
        return n * factorial(n-1) # Recursive step

# Example usage:
# print(factorial(5)) # Output: 120
```
```

--------------------------------

### Renderer Process Usage of Osaurus Instance

Source: https://docs.osaurus.ai/shared-configuration

Example code for the Electron renderer process to connect to an Osaurus AI instance using the IPC bridge exposed by the preload script. It calls 'window.osaurus.getInstance()' to get instance details, then logs connection information and makes an example fetch request to the Osaurus API. Requires Node.js 18+ for global fetch or alternative libraries like axios.

```javascript
// renderer/index.js
async function connectToOsaurus() {
  const inst = await window.osaurus.getInstance();
  if (!inst) {
    console.log("Osaurus not running");
    return;
  }
  console.log("Osaurus at", inst.url, "LAN:", !!inst.exposeToNetwork);
  // Example request (Node 18+ has global fetch in Electron; otherwise use axios/node-fetch)
  const resp = await fetch(new URL("/v1/models", inst.url));
  const models = await resp.json();
  console.log(models);
}

connectToOsaurus();

```

--------------------------------

### MCP Server Configuration Example

Source: https://docs.osaurus.ai/index

This JSON snippet illustrates how to configure an MCP server, specifically for Osaurus, detailing the command and arguments to initiate the MCP service.

```json
{
  "mcpServers": {
    "osaurus": {
      "command": "osaurus",
      "args": ["mcp"]
    }
  }
}
```

--------------------------------

### Install osaurus-emacs Plugin

Source: https://docs.osaurus.ai/tools

Installs the osaurus-emacs plugin, which enables AI agents to interact with an Emacs instance by executing Emacs Lisp code. This is an example of installing a community-contributed tool.

```bash
osaurus tools install osaurus.emacs
```

--------------------------------

### Conventional Commit Message Examples

Source: https://docs.osaurus.ai/developer

Examples of commit messages following the conventional commits specification, used for maintaining a consistent and understandable commit history in Osaurus.

```markdown
feat: Add support for new model architecture  
fix: Resolve memory leak in streaming responses  
docs: Update API documentation  
test: Add integration tests for tool calling  
refactor: Simplify router implementation  

```

--------------------------------

### Build the Plugin

Source: https://docs.osaurus.ai/plugin-authoring

Compile your plugin code and copy the resulting dynamic library.

```APIDOC
## Build the Plugin

### Description
Compiles the plugin using `swift build` and copies the dynamic library to the project root.

### Method
CLI Command

### Endpoint
n/a

### Parameters
#### CLI Arguments
- **swift build -c release** (string) - Required - Compiles the project in release mode.
- **cp .build/release/libMyPlugin.dylib ./libMyPlugin.dylib** (string) - Required - Copies the built library to the current directory.

### Request Example
```bash
swift build -c release
cp .build/release/libMyPlugin.dylib ./libMyPlugin.dylib
```

### Response
#### Success Response
Creates `libMyPlugin.dylib` in the current directory.
```

--------------------------------

### Plugin ABI - Entry Point

Source: https://docs.osaurus.ai/plugin-authoring

Defines the required C-compatible entry point function for Osaurus plugins.

```APIDOC
## Plugin ABI - Entry Point

### Description
Specifies the single C-compatible exported symbol (`osaurus_plugin_entry`) that Osaurus looks for to load and initialize a plugin.

### Method
C Function Signature

### Endpoint
n/a

### Parameters
#### Function Signature
- **osr_plugin_api* osaurus_plugin_entry(void);** - Required - This function must be exported by the plugin binary. It returns a pointer to a struct containing function pointers for interacting with the plugin.
```

--------------------------------

### GET /mcp/tools

Source: https://docs.osaurus.ai/api

Retrieves a list of all available MCP tools that are installed via plugins.

```APIDOC
## GET /mcp/tools

### Description
List all available MCP tools from installed plugins.

### Method
GET

### Endpoint
/mcp/tools

### Parameters
#### Query Parameters
None

### Response
#### Success Response (200)
- **tools** (array) - A list of available MCP tools.
  - **name** (string) - The name of the tool.
  - **description** (string) - A brief description of the tool's functionality.
  - **inputSchema** (object) - The JSON schema defining the expected input for the tool.
    - **type** (string) - The type of the input schema (usually 'object').
    - **properties** (object) - An object defining the properties of the input.
      - **path** (string) - Description of the path property.
      - **url** (string) - Description of the url property.
    - **required** (array) - An array of strings indicating the required properties.

### Response Example
```json
{
  "tools": [
    {
      "name": "read_file",
      "description": "Read contents of a file",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Path to the file"
          }
        },
        "required": ["path"]
      }
    },
    {
      "name": "browser_navigate",
      "description": "Navigate to a URL in the browser",
      "inputSchema": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "URL to navigate to"
          }
        },
        "required": ["url"]
      }
    }
  ]
}
```
```

--------------------------------

### Uninstall Osaurus via Homebrew

Source: https://docs.osaurus.ai/installation

Removes the Osaurus application using the Homebrew package manager.

```shell
brew uninstall --cask osaurus
```

--------------------------------

### Discover Osaurus Instances and Make API Requests (Swift)

Source: https://docs.osaurus.ai/integrations

Demonstrates how to use the shared configuration to discover running Osaurus instances and make an API request for chat completions in Swift for macOS. It requires the Foundation framework.

```swift
import Foundation

// Discover Osaurus
let instance = try OsaurusDiscoveryService.discoverLatestRunningInstance()

// Make API request
let url = instance.url.appendingPathComponent("v1/chat/completions")
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")

let body: [String: Any] = [
    "model": "llama-3.2-3b-instruct-4bit",
    "messages": [["role": "user", "content": "Hello!"]]
]
request.httpBody = try JSONSerialization.data(withJSONObject: body)

let (data, _) = try await URLSession.shared.data(for: request)

```

--------------------------------

### Python (Ollama Format)

Source: https://docs.osaurus.ai/integrations

Example of using Python requests to send a chat completion request in Ollama format.

```APIDOC
## POST /api/chat (Python requests)

### Description
Sends a chat completion request to the Osaurus API using the Python 'requests' library, mimicking Ollama's API format.

### Method
POST

### Endpoint
/api/chat

### Parameters
#### Request Body
- **model** (string) - Required - The name of the model to use for generation.
- **messages** (array) - Required - An array of message objects representing the conversation history.
  - **role** (string) - Required - The role of the author ('user' or 'assistant').
  - **content** (string) - Required - The content of the message.
- **stream** (boolean) - Optional - Whether to stream the response (defaults to false).

### Request Example
```python
import requests

response = requests.post(
    "http://127.0.0.1:1337/api/chat",
    json={
        "model": "llama-3.2-3b-instruct-4bit",
        "messages": [{"role": "user", "content": "Hello!"}],
        "stream": False
    }
)

print(response.json()["message"]["content"])
```

### Response
#### Success Response (200)
- **message** (object) - The message object from the model.
  - **content** (string) - The generated text response.
```

--------------------------------

### Manual Uninstallation of Osaurus

Source: https://docs.osaurus.ai/installation

Provides instructions for manually uninstalling Osaurus by quitting the application, deleting its files, and removing the CLI symlink.

```shell
# Remove CLI symlink
rm /usr/local/bin/osaurus

# Optional — Remove data
# Models
rm -rf ~/MLXModels

# App data and tools
rm -rf ~/Library/Application\ Support/com.dinoki.osaurus
```

--------------------------------

### Python SDK - Chat Completion Example

Source: https://docs.osaurus.ai/api

A Python code snippet demonstrating a basic chat completion request using the OpenAI SDK. It initializes the client and prints the assistant's response content.

```python
from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:1337/v1", api_key="osaurus")

response = client.chat.completions.create(
    model="llama-3.2-3b-instruct-4bit",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
```

--------------------------------

### Set Osaurus Model Directory

Source: https://docs.osaurus.ai/installation

Specifies how to set or override the directory where Osaurus stores its models using the `OSU_MODELS_DIR` environment variable.

```shell
export OSU_MODELS_DIR=/Volumes/External/MLXModels
```

--------------------------------

### Next.js API Route - POST /api/chat

Source: https://docs.osaurus.ai/integrations

Example of creating a Next.js API route to handle chat completion requests and forward them to the Osaurus API.

```APIDOC
## POST /api/chat (Next.js API Route)

### Description
Defines a Next.js API route that accepts chat messages and forwards them to the Osaurus API for processing.

### Method
POST

### Endpoint
/api/chat (within your Next.js app)

### Parameters
#### Request Body (from client to Next.js API route)
- **message** (string) - Required - The user's chat message.

### Request Example (from client to Next.js API route)
```json
{
  "message": "Tell me a joke."
}
```

### Internal API Call (Next.js to Osaurus)
#### Method
POST

#### Endpoint
/v1/chat/completions

#### Request Body (from Next.js to Osaurus)
- **model** (string) - Required - The name of the model to use.
- **messages** (array) - Required - The conversation history.

#### Request Example (Next.js to Osaurus)
```javascript
// app/api/chat/route.js
export async function POST(request) {
  const { message } = await request.json();

  const response = await fetch('http://127.0.0.1:1337/v1/chat/completions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      model: 'llama-3.2-3b-instruct-4bit',
      messages: [{ role: 'user', content: message }]
    })
  });

  return Response.json(await response.json());
}
```

### Response (from Next.js API route to client)
Returns the JSON response from the Osaurus API.
```

--------------------------------

### Node.js Basic Usage with Osaurus AI

Source: https://docs.osaurus.ai/sdk-examples

Demonstrates basic chat completion in a Node.js environment using the `openai` library. It sends a user message and prints the AI's response. Requires a local Osaurus instance and the `openai` package.

```javascript
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'http://127.0.0.1:1337/v1',
  apiKey: 'not-needed',
});

async function main() {
  const completion = await openai.chat.completions.create({
    model: 'llama-3.2-3b-instruct-4bit',
    messages: [
      { role: 'user', content: 'Explain JavaScript closures' }
    ],
  });

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

main();
```
Tokens:
Raw