### Install Example Dependencies

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/README.md

Installs dependencies specific to an example. Replace <example_dir> with the relevant example directory name.

```bash
pip install -r examples/<example_dir>/requirements.txt
```

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

### Run FastAPI Example

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/README.md

Starts a FastAPI development server for AiCore integration examples. Use --reload for automatic restarts during development.

```bash
uvicorn examples.fastapi.main:app --reload
```

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

### Local Claude Code Provider Quickstart

Source: https://github.com/brunov21/aicore/blob/main/README.md

Quickstart example for using the local Claude Code provider with AiCore. No Anthropic API key is needed as authentication is handled by the CLI. Ensure AiCore is installed.

```python
from aicore.llm import Llm
from aicore.llm.config import LlmConfig

config = LlmConfig(
    provider="claude_code",
    model="claude-sonnet-4-5-20250929",
    # No api_key needed — auth is handled by the CLI
)

llm = Llm.from_config(config)
response = await llm.acomplete("List all Python files in this project")
print(response)
```

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

### Start AiCore Proxy Server

Source: https://github.com/brunov21/aicore/blob/main/README.md

Examples of starting the AiCore proxy server for remote Claude Code access. Shows minimal and fully configured command-line options, as well as starting via a Python module.

```bash
# Minimal — binds to 127.0.0.1:8080, prompts for tunnel choice interactively
aicore-proxy-server

# Fully configured
aicore-proxy-server \
  --host 0.0.0.0 \
  --port 8080 \
  --token my-secret-token \
  --tunnel none \
  --cwd /path/to/project \
  --log-level INFO

# Or via Python module
python -m aicore.scripts.claude_code_proxy_server --port 8080 --tunnel none
```

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

### Run Chainlit Example

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/README.md

Launches an interactive chat application using Chainlit. This command starts the specified Chainlit app.

```bash
chainlit run examples/chainlit/app/app.py
```

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

### Installation

Source: https://github.com/brunov21/aicore/blob/main/llms.txt

Instructions for installing the AiCore library and its optional dependencies.

```bash
pip install core-for-ai

# Install with all optional dependencies
pip install core-for-ai[all]

# Install with dashboard support (Plotly, Dash)
pip install core-for-ai[dashboard]

# Install with SQL support (SQLAlchemy, async drivers)
pip install core-for-ai[sql]

# Install the Claude Code proxy server (FastAPI + SSE)
pip install core-for-ai[claude-server]
```

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

### Configuration Example

Source: https://github.com/brunov21/aicore/blob/main/docs/llm/base_provider.md

Example of how to configure an LLM provider using the LlmConfig class.

```APIDOC
## Configuration Example

### `LlmConfig` Class

Used to configure LLM providers.

### Example Configuration:

```python
from aicore.llm.config import LlmConfig

config = LlmConfig(
    provider="openai",  # Provider name matching implementation
    api_key="your_api_key",
    model="gpt-4",
    temperature=0.7,
    max_tokens=1000,
    mcp_config="path/to/mcp_config.json",  # Optional MCP configuration
    timeout=30.0
)
```

### Configuration Fields:

- **provider** (str) - Required - The name of the LLM provider to use (e.g., "openai", "anthropic").
- **api_key** (str) - Required - The API key for authenticating with the provider.
- **model** (str) - Required - The specific model identifier to use (e.g., "gpt-4", "claude-3-opus").
- **temperature** (float) - Optional - Controls randomness in output. Lower values make output more deterministic. Defaults vary by provider.
- **max_tokens** (int) - Optional - The maximum number of tokens to generate in the response. Defaults vary by provider.
- **mcp_config** (Optional[str]) - Optional - Path to a JSON configuration file for MCP integration.
- **timeout** (float) - Optional - The timeout in seconds for API requests. Defaults to a provider-specific value.
```

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

### Install AiCore with Optional Features

Source: https://github.com/brunov21/aicore/blob/main/docs/quickstart/installation.md

Install AiCore with specific optional features like the observability dashboard or SQL integration. Use '[all]' to install all optional features.

```bash
pip install "core-for-ai[dashboard]"
```

```bash
pip install "core-for-ai[sql]"
```

```bash
pip install "core-for-ai[all]"
```

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

### Install AiCore from Source

Source: https://github.com/brunov21/aicore/blob/main/docs/quickstart/installation.md

Install the development version of AiCore directly from its GitHub repository.

```bash
pip install git+https://github.com/BrunoV21/AiCore@main
```

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

### Example YAML Configuration

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/simple_llm_call.md

An example of how an LLM configuration should be structured in a YAML file.

```yaml
llm:
  provider: "openai"
  api_key: "your_api_key_here"
  model: "gpt-4o"
  temperature: 0.7
  max_tokens: 1000
```

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

### Install AiCore with pip

Source: https://github.com/brunov21/aicore/blob/main/README.md

Install the AiCore framework using pip. The '[all]' option installs all optional dependencies.

```bash
pip install git+https://github.com/BrunoV21/AiCore
```

```bash
pip install git+https://github.com/BrunoV21/AiCore.git#egg=core-for-ai[all]
```

```bash
pip install core-for-ai[all]
```

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

### Complete LLM Call Example

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/simple_llm_call.md

A full example combining configuration, initialization, a synchronous completion call, and printing usage statistics. Remember to replace 'your_api_key_here' with your actual API key.

```python
from aicore.llm import Llm
from aicore.llm.config import LlmConfig

# Configuration
config = LlmConfig(
    provider="openai",
    api_key="your_api_key_here",
    model="gpt-4o",
    temperature=0.7,
    max_tokens=1000
)

# Initialize LLM
llm = Llm(config=config)

# Make completion
response = llm.complete("Explain quantum computing in simple terms")
print(response)

# Print usage
print("\nUsage Stats:")
print(llm.usage)
```

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

### Install AiCore

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/README.md

Installs the AiCore library using pip. Ensure you have Python and pip installed.

```bash
pip install core-for-ai
```

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

### Install AiCore Observability

Source: https://github.com/brunov21/aicore/blob/main/docs/observability/dashboard.md

Install the AiCore library with observability extras. This is a prerequisite for using the dashboard.

```bash
pip install core-for-ai[observability]
```

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

### Install FastAPI, Uvicorn, and AiCore

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/fastapi.md

Install the necessary packages for FastAPI and AiCore integration.

```bash
pip install fastapi uvicorn core-for-ai
```

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

### Install and Start Claude Code Proxy Server

Source: https://github.com/brunov21/aicore/blob/main/docs/news/claude-code-provider.md

Install the necessary package and start the FastAPI SSE service that wraps the Claude Agent SDK. This server exposes the SDK over HTTP with Bearer token authentication.

```bash
pip install core-for-ai[claude-server]
aicore-proxy-server --port 8080 --tunnel none
```

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

### Install Claude Code CLI and AiCore

Source: https://github.com/brunov21/aicore/blob/main/docs/providers/claude-code.md

Install the necessary tools for using the Claude Code provider locally. Ensure Node.js 18+ is installed.

```bash
# 1. Node.js 18+ and the Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 2. Authenticate once
claude login

# 3. Install AiCore
pip install core-for-ai
```

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

### Quickstart Remote Provider Configuration

Source: https://github.com/brunov21/aicore/blob/main/README.md

Instantiate an Llm object using a remote provider configuration. Ensure the proxy server is running and reachable.

```python
from aicore.llm import Llm
from aicore.llm.config import LlmConfig

config = LlmConfig(
    provider="remote_claude_code",
    model="claude-sonnet-4-5-20250929",
    base_url="http://your-proxy-host:8080",   # or a tunnel URL
    api_key="your_proxy_token",               # CLAUDE_PROXY_TOKEN from server startup
)

llm = Llm.from_config(config)
response = await llm.acomplete("Summarise this codebase")
print(response)
```

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

### Install core-for-ai with optional extras

Source: https://github.com/brunov21/aicore/blob/main/llms.txt

Install AiCore with specific optional dependencies like dashboard, SQL, or Claude server support.

```bash
# Install with all optional dependencies
pip install core-for-ai[all]
```

```bash
# Install with dashboard support (Plotly, Dash)
pip install core-for-ai[dashboard]
```

```bash
# Install with SQL support (SQLAlchemy, async drivers)
pip install core-for-ai[sql]
```

```bash
# Install the Claude Code proxy server (FastAPI + SSE)
pip install core-for-ai[claude-server]
```

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

### Install Project Dependencies

Source: https://github.com/brunov21/aicore/blob/main/examples/fastapi/README.md

Installs all required Python packages listed in the requirements.txt file.

```bash
pip install -r requirements.txt
```

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

### Run Python Script Example

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/README.md

Executes a Python script example. Replace <script_name> with the name of the script you want to run.

```bash
python examples/<script_name>.py
```

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

### Virtual Environment Setup

Source: https://github.com/brunov21/aicore/blob/main/examples/fastapi/README.md

Commands to create and activate a Python virtual environment for project dependencies.

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

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

### Setup Cloudflare Tunnel (Quick-tunnel)

Source: https://github.com/brunov21/aicore/blob/main/docs/claude_code_proxy_server_plan.md

Sets up a Cloudflare tunnel using 'cloudflared' in quick-tunnel mode. Requires 'cloudflared' binary in PATH.

```python
subprocess.Popen(["cloudflared", "tunnel", "--url", f"http://localhost:{port}"], stderr=subprocess.PIPE, text=True)
```

```regex
r'https://[a-z0-9-]+\.trycloudflare\.com'
```

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

### Install AiCore with Claude Server Extras

Source: https://github.com/brunov21/aicore/blob/main/README.md

Command to install AiCore with the necessary extras for the Claude server proxy. Also includes instructions to install and authenticate the Claude Code CLI.

```bash
# Install AiCore with the claude-server extras
pip install core-for-ai[claude-server]

# Also install the Claude Code CLI and authenticate
npm install -g @anthropic-ai/claude-code
claude login
```

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

### Async LLM Request Setup

Source: https://github.com/brunov21/aicore/blob/main/docs/quickstart/first-request.md

Demonstrates how to set up and run an asynchronous LLM request. Requires importing the asyncio module.

```python
import asyncio
from aicore.llm import Llm
from aicore.llm.config import LlmConfig

async def main():
    config = LlmConfig(
        provider="openai",
        api_key="your_api_key_here",
        model="gpt-4o"
    )
    llm = Llm(config=config)
    
    response = await llm.acomplete("Hello async world!")
    print(response)

asyncio.run(main())
```

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

### Start Proxy Server with Cloudflare Tunnel

Source: https://github.com/brunov21/aicore/blob/main/docs/quickstart/claude-code.md

Starts the AiCore proxy server and exposes it over the internet using Cloudflare's quick tunnel. Requires 'cloudflared' to be on the system's PATH.

```bash
# Cloudflare quick tunnel (cloudflared must be on PATH)
aicore-proxy-server --port 8080 --tunnel cloudflare
```

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

### Install Required Packages

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/chainlit.md

Install Chainlit and AiCore using pip. Ensure you have Python 3.8+.

```bash
pip install chainlit core-for-ai
```

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

### Install SQL Support for AICore

Source: https://github.com/brunov21/aicore/blob/main/llms.txt

Install the necessary package to enable SQL database support for AICore observability features. This command should be run in your project's environment.

```bash
# Install SQL support
pip install core-for-ai[sql]
```

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

### Example MCP Configuration

Source: https://github.com/brunov21/aicore/blob/main/README.md

An example JSON configuration file for MCP servers, defining various services like search and data processing with their respective transport types and commands.

```json
{
  "mcpServers": {
    "search-server": {
      "transport_type": "ws",
      "url": "ws://localhost:8080",
      "description": "WebSocket server for search functionality"
    },
    "data-server": {
      "transport_type": "stdio",
      "command": "python",
      "args": ["data_server.py"],
      "description": "Local data processing server"
    },
    "brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
        "BRAVE_API_KEY": "SUPER-SECRET-BRAVE-SEARCH-API-KEY"
      }
    }
  }
}
```

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

### Install AiCore with Claude Server Extras

Source: https://github.com/brunov21/aicore/blob/main/docs/quickstart/claude-code.md

Installs the AiCore Python package with the necessary extras for running the Claude server proxy.

```bash
pip install core-for-ai[claude-server]
```

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

### AiCore Configuration File Example (config.yml)

Source: https://github.com/brunov21/aicore/blob/main/README.md

Example configuration file for AiCore, specifying providers, API keys, and model parameters for both LLM and embeddings. The CONFIG_PATH environment variable should point to this file.

```yaml
# config.yml
embeddings:
  provider: "openai" # or "mistral", "groq", "gemini", "nvidia"
  api_key: "your_openai_api_key"
  model: "text-embedding-3-small" # Optional

llm:
  provider: "openai" # or "mistral", "groq", "gemini", "nvidia"
  api_key: "your_openai_api_key"
  model: "gpt-o4" # Optional
  temperature: 0.1
  max_tokens: 1028
  reasonning_effort: "high"
  mcp_config: "./mcp_config.json" # Path to MCP configuration
  max_tool_calls_per_response: 3 # Optional limit on tool calls
```

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

### Run FastAPI Application

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/fastapi.md

Start the FastAPI application using Uvicorn for development.

```bash
uvicorn main:app --reload
```

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

### Start Proxy Server with SSH Tunnel

Source: https://github.com/brunov21/aicore/blob/main/docs/quickstart/claude-code.md

Starts the AiCore proxy server and configures an SSH reverse tunnel. The command to establish the tunnel on your own VPS will be printed.

```bash
# SSH reverse tunnel (prints the ssh -R command for your own VPS)
aicore-proxy-server --port 8080 --tunnel ssh
```

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

### Start AiCore Proxy Server

Source: https://github.com/brunov21/aicore/blob/main/docs/quickstart/claude-code.md

Starts the AiCore proxy server on the specified host and port. The 'tunnel none' option indicates no tunneling is configured.

```bash
aicore-proxy-server --host 0.0.0.0 --port 8080 --tunnel none
```

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

### Start Proxy Server with Ngrok Tunnel

Source: https://github.com/brunov21/aicore/blob/main/docs/quickstart/claude-code.md

Starts the AiCore proxy server and exposes it over the internet using ngrok. The ngrok authentication token is managed securely.

```bash
# ngrok (auth token stored securely in OS credential store on first run)
aicore-proxy-server --port 8080 --tunnel ngrok
```

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

### Remote Provider Configuration File Example

Source: https://github.com/brunov21/aicore/blob/main/README.md

Example YAML configuration for the remote_claude_code provider. Optional parameters like permission_mode and cwd can be forwarded to the proxy server.

```yaml
# config/config_example_remote_claude_code.yml
llm:
  provider: "remote_claude_code"
  model: "claude-sonnet-4-5-20250929"
  base_url: "http://your-proxy-host:8080"   # or the ngrok / cloudflare tunnel URL
  api_key: "your_proxy_token"               # CLAUDE_PROXY_TOKEN printed at server startup

  # Optional — forwarded to the proxy server
  permission_mode: "bypassPermissions"
  cwd: "/path/to/project"                   # must be in server's --allowed-cwd-paths
  max_turns: 10
  allowed_tools:
    - "Bash"
    - "Read"
    - "Write"

  # Skip the GET /health connectivity check at startup
  skip_health_check: false
```

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

### Environment Configuration

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/README.md

Copies the example environment file and prompts to edit it with API keys. This is a crucial step for configuring AiCore providers.

```bash
cp .env-example .env
# Edit .env with your API keys
```

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

### Example Configuration for Remote Claude Code

Source: https://github.com/brunov21/aicore/blob/main/docs/remote_claude_code_provider_plan.md

Provides an example YAML configuration file (`config_example_remote_claude_code.yml`) for setting up and using the `remote_claude_code` LLM provider.

```yaml
llm:
  provider: remote_claude_code
  base_url: http://localhost:8000
  api_key: "YOUR_API_KEY"
  model: "claude-3-opus-20240229"
  skip_health_check: false
  # Optional fields:
  # permission_mode: sandbox
  # cwd: "/app"
  # max_turns: 10
  # allowed_tools: ["calculator", "web_search"]
  # cli_path: "/usr/local/bin/claude"
```

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

### MCP Configuration Example

Source: https://context7.com/brunov21/aicore/llms.txt

Example JSON structure for mcp_config.json, defining MCP servers with different transport types (stdio, ws, sse) and their configurations.

```json
{
  "mcpServers": {
    "brave-search": {
      "transport_type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {"BRAVE_API_KEY": "your_brave_api_key"}
    },
    "data-server": {
      "transport_type": "ws",
      "url": "ws://localhost:8080"
    },
    "sse-server": {
      "transport_type": "sse",
      "url": "http://localhost:3000/sse"
    }
  }
}

```

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

### MCP Configuration File Examples

Source: https://github.com/brunov21/aicore/blob/main/llms.txt

Define various MCP servers, including their commands, arguments, environment variables, and transport types (stdio, ws, sse).

```json
{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    },
    "codetide": {
      "command": "uvx",
      "args": ["--from", "codetide", "codetide-mcp-server"],
      "env": {
        "CODETIDE_WORKSPACE": "./"
      }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "exa": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.exa.ai/mcp?exaApiKey=your-exa-api-key"]
    },
    "websocket-server": {
      "transport_type": "ws",
      "url": "ws://localhost:8080",
      "description": "Custom WebSocket MCP server"
    },
    "sse-server": {
      "transport_type": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {"Authorization": "Bearer token"}
    }
  }
}
```

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

### Example Curl Command for Query

Source: https://github.com/brunov21/aicore/blob/main/docs/claude_code_proxy_server_plan.md

Provides an example curl command to send a query to the proxy server, including authorization and content type headers.

```bash
curl -N -H "Authorization: Bearer <your_token>" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "Hello"}' \
     http://127.0.0.1:{port}/query
```

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

### Example Logger Usage

Source: https://github.com/brunov21/aicore/blob/main/docs/observability/logger.md

Demonstrates how to log a message to a specific session and how to asynchronously iterate through session logs. Requires `.distribute()` to be run in the background.

```python
await _logger.log_chunk_to_queue("message", session_id="abc123")

async for log in _logger.get_session_logs("abc123"):
    print(log)
```

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

### Run Chainlit Application

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/chainlit.md

Start the Chainlit development server with hot-reloading enabled using this command.

```bash
chainlit run app.py -w
```

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

### Start Claude Code Proxy Server

Source: https://github.com/brunov21/aicore/blob/main/docs/providers/claude-code.md

Start the AiCore proxy server for Claude Code. This can be done with minimal configuration, prompting interactively, or with fully specified arguments.

```bash
# Minimal — prompts for tunnel choice interactively
aicore-proxy-server

# Fully configured
aicore-proxy-server \
  --host 0.0.0.0 \
  --port 8080 \
  --token my-secret-token \
  --tunnel none \
  --cwd /path/to/project

# Via Python module
python -m aicore.scripts.claude_code_proxy_server --port 8080 --tunnel none
```

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

### AICore Proxy Server CLI Reference

Source: https://github.com/brunov21/aicore/blob/main/README.md

Command-line flags and their default values for starting the AICore proxy server.

```APIDOC
## AICore Proxy Server CLI Reference

### CLI Flags

| Flag | Default | Description |
|---|---|---|
| `--host` | `127.0.0.1` | Bind address |
| `--port` | `8080` | TCP port |
| `--token` | *(auto-generated)* | Bearer token; also reads `CLAUDE_PROXY_TOKEN` env var |
| `--tunnel` | *(prompt)* | `none` / `ngrok` / `cloudflare` / `ssh` |
| `--tunnel-port` | same as `--port` | Remote port for SSH tunnels |
| `--cwd` | *(unrestricted)* | Force a working directory for all Claude sessions |
| `--allowed-cwd-paths` | *(any)* | Whitelist of `cwd` values clients may request |
| `--log-level` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
| `--cors-origins` | `*` | Allowed CORS origins |

### Tunnel Support

When `--tunnel` is omitted the server prompts interactively at startup.

| Mode | Requirement | Notes |
|---|---|---|
| `none` | — | Local network only |
| `ngrok` | `pip install pyngrok` | Auth token is stored in the OS credential store on first run and loaded automatically on subsequent runs |
| `cloudflare` | `cloudflared` binary on PATH | Quick tunnel, ephemeral URL |
| `ssh` | SSH access to a VPS | Prints the `ssh -R` command; no extra software needed |
```

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

### Configure LLM via YAML

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/simple_async_llm_call.md

Example configuration for OpenAI using a YAML file. Ensure your API key and model details are correctly set.

```yaml
# config.yml example for OpenAI
llm:
  provider: "openai"
  api_key: "your_api_key_here"
  model: "gpt-4o"
  temperature: 0.7
  max_tokens: 1000
```

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

### Setup ngrok Tunnel

Source: https://github.com/brunov21/aicore/blob/main/docs/claude_code_proxy_server_plan.md

Configures an ngrok tunnel if '--tunnel ngrok' is specified. Requires 'pyngrok' and optionally 'NGROK_AUTH_TOKEN'.

```python
import pyngrok.ngrok
```

```python
pyngrok.ngrok.connect(port, proto="http")
```

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

### MCP Integration Example

Source: https://github.com/brunov21/aicore/blob/main/README.md

Demonstrates initializing an LLM with MCP configuration and making an async request that can utilize MCP-connected tools. Ensure your MCP configuration file is correctly set up.

```python
from aicore.llm import Llm
from aicore.config import Config
import asyncio

async def main():
    # Load configuration with MCP settings
    config = Config.from_yaml("./config/config_example_mcp.yml")
    
    # Initialize LLM with MCP capabilities
    llm = Llm.from_config(config.llm)
    
    # Make async request that can use MCP-connected tools
    response = await llm.acomplete(
        "Search for latest news about AI advancements",
        system_prompt="Use available tools to gather information"
    )
    print(response)

asyncio.run(main())
```

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

### Initialize and Run Observability Dashboard

Source: https://github.com/brunov21/aicore/blob/main/README.md

Illustrates how to initialize the ObservabilityDashboard with a storage file and run the server on a specified port.

```python
from aicore.observability import ObservabilityDashboard

dashboard = ObservabilityDashboard(storage="observability_data.json")
dashboard.run_server(port=8050)
```

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

### Configure LLM Provider (OpenAI Example)

Source: https://github.com/brunov21/aicore/blob/main/docs/quickstart/first-request.md

Set up the configuration for the LLM client, specifying the provider, API key, and model. Ensure you replace 'your_api_key_here' with your actual API key.

```python
config = LlmConfig(
    provider="openai",
    api_key="your_api_key_here",
    model="gpt-4o"
)
```

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

### Use System Prompts

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/simple_llm_call.md

Provide a system prompt to guide the LLM's behavior or persona. This example sets the persona to a creative poet specializing in haikus.

```python
response = llm.complete(
    "Write a poem about technology",
    system_prompt="You are a creative poet specializing in haikus"
)
```

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

### Connection Error Message for Claude Code Proxy

Source: https://github.com/brunov21/aicore/blob/main/docs/remote_claude_code_provider_plan.md

This error message is raised when the client cannot connect to the Claude Code Proxy Server. It provides instructions on how to start the server and where to find setup documentation, and suggests skipping the health check if necessary.

```python
Cannot connect to the Claude Code Proxy Server at {base_url}.
Is it running? Start it with:
  python -m aicore.llm.providers.claude_code_proxy_server --port 8080
See docs/claude_code_proxy_server_plan.md for setup instructions.
To skip this check, set skip_health_check: true in your config.

```

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

### Configure and Use Local Claude Code Provider

Source: https://context7.com/brunov21/aicore/llms.txt

Set up and use the local Claude Code provider for LLM completions without an Anthropic API key. Ensure the Claude Code CLI is installed and logged in. This example demonstrates basic configuration, sync/async completions, and tool callback handling.

```python
from aicore.llm import Llm
from aicore.llm.config import LlmConfig
import asyncio

# Prerequisites:
# npm install -g @anthropic-ai/claude-code
# claude login
# pip install core-for-ai

# Basic configuration (no API key needed)
config = LlmConfig(
    provider="claude_code",
    model="claude-sonnet-4-5-20250929",
    # Optional settings:
    permission_mode="bypassPermissions",  # or "acceptEdits", "default", "plan"
    cwd="/path/to/your/project",
    max_turns=10,
    allowed_tools=["Read", "Write", "Bash"],
    mcp_config="./mcp_config.json"
)

llm = Llm.from_config(config)

# Sync completion
response = llm.complete("List all Python files in this project")
print(response)

# Async completion
async def claude_code_async():
    response = await llm.acomplete("Find all TODO comments in the codebase")
    print(response)

asyncio.run(claude_code_async())

# Tool call streaming with callbacks
def on_tool_event(event: dict):
    if event["stage"] == "started":
        print(f"-> Calling tool: {event['tool_name']}")
        print(f"   Arguments: {event.get('arguments', {})}")
    elif event["stage"] == "concluded":
        status = "ERROR" if event.get("is_error") else "OK"
        print(f"<- Tool {event['tool_name']} [{status}]")

llm.tool_callback = on_tool_event
response = llm.complete("Create a new file called hello.py with a hello world function")

# YAML configuration equivalent:
"""
llm:
  provider: "claude_code"
  model: "claude-sonnet-4-5-20250929"
  permission_mode: "bypassPermissions"
  cwd: "/path/to/your/project"
  max_turns: 10
  allowed_tools:
    - "Read"
    - "Write"
    - "Bash"
"""

```

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

### claude-agent-sdk Installation Check

Source: https://github.com/brunov21/aicore/blob/main/docs/claude_code_proxy_server_plan.md

This code checks if the 'claude-agent-sdk' is installed. If not, it provides installation instructions and exits.

```python
try:
    import claude_agent_sdk
except ImportError:
    print("ERROR: claude-agent-sdk is not installed.")
    print("Install it with: pip install claude-agent-sdk")
    print("Docs: https://platform.claude.com/docs/en/agent-sdk/python")
    sys.exit(1)
```

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

### Initialize and Use Mistral LLM

Source: https://github.com/brunov21/aicore/blob/main/README.md

Demonstrates how to initialize the Mistral LLM provider with a configuration object and generate text completions.

```python
from aicore.llm.config import LlmConfig
from aicore.llm.providers import MistralLlm

config = LlmConfig(
    api_key="your_api_key",
    model="your_model_name",
    temperature=0.7,
    max_tokens=100
)

mistral_llm = MistralLlm.from_config(config)
response = mistral_llm.complete(prompt="Hello, how are you?")
print(response)
```

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

### Initialize LLM Client and Make Request

Source: https://github.com/brunov21/aicore/blob/main/docs/llm/index.md

Load configuration, initialize the LLM client, and make a completion request. Ensure configuration is loaded before initializing the client.

```python
from aicore.llm import Llm
from aicore.config import load_config

# Load configuration
config = load_config("config.yml")

# Initialize LLM client
llm = Llm.from_config(config)

# Make completion request
response = llm.complete("Hello, how are you?")
```

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

### Minimal LLM Initialization and Completion

Source: https://github.com/brunov21/aicore/blob/main/llms.txt

Basic setup for an LLM client using OpenAI provider. Requires an API key and model specification. The `complete` method is synchronous.

```python
# Minimal example
from aicore.llm import Llm
from aicore.llm.config import LlmConfig

config = LlmConfig(provider="openai", api_key="key", model="gpt-4o")
llm = Llm.from_config(config)
response = llm.complete("Hello")
```

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

### Install Claude Code Proxy Server

Source: https://github.com/brunov21/aicore/blob/main/docs/providers/claude-code.md

Install the necessary packages for the Claude Code proxy server, including AiCore with the 'claude-server' extra. Ensure the Claude Code CLI is also installed and authenticated.

```bash
pip install core-for-ai[claude-server]
npm install -g @anthropic-ai/claude-code
claude login
```

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

### LLM Provider Configuration Example

Source: https://github.com/brunov21/aicore/blob/main/docs/llm/base_provider.md

Demonstrates how to configure an LLM provider using the LlmConfig class, specifying parameters like provider name, API key, model, and other settings.

```python
from aicore.llm.config import LlmConfig

config = LlmConfig(
    provider="openai",  # Provider name matching implementation
    api_key="your_api_key",
    model="gpt-4",
    temperature=0.7,
    max_tokens=1000,
    mcp_config="path/to/mcp_config.json",  # Optional MCP configuration
    timeout=30.0
)
```

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

### Verify AiCore Installation

Source: https://github.com/brunov21/aicore/blob/main/docs/quickstart/installation.md

Run this Python code to verify that AiCore has been installed correctly and to check its version.

```python
import aicore
print(aicore.__version__)
```

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

### Install Claude Code CLI

Source: https://github.com/brunov21/aicore/blob/main/docs/quickstart/claude-code.md

Installs the Claude Code CLI globally. Requires Node.js 18 or higher.

```bash
# Requires Node.js 18+
npm install -g @anthropic-ai/claude-code
```

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

### LLM Usage Tracking with Llm Instance

Source: https://context7.com/brunov21/aicore/llms.txt

Initializes an Llm instance with a configuration, performs a completion, and then prints the automatically tracked usage information. This demonstrates how the Llm instance inherently manages usage statistics.

```python
from aicore.llm import Llm
from aicore.llm.config import LlmConfig

llm = Llm.from_config(LlmConfig(
    provider="openai",
    api_key="key",
    model="gpt-4o"
))

response = llm.complete("Hello")
print(llm.usage)  # Automatically tracks all completions
```

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

### Example Curl Command for Health Check

Source: https://github.com/brunov21/aicore/blob/main/docs/claude_code_proxy_server_plan.md

Provides an example curl command to check the health of the proxy server.

```bash
curl http://127.0.0.1:{port}/health
```

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

### Main Function Structure

Source: https://github.com/brunov21/aicore/blob/main/docs/claude_code_proxy_server_plan.md

Orchestrates the startup process of the proxy server, including argument parsing, checks, tunnel setup, app wiring, banner printing, and running the uvicorn server.

```python
def main():
    # ... argument parsing, startup checks, tunnel setup ...
    uvicorn.run(app, host=args.host, port=args.port, log_level=args.log_level.lower())

if __name__ == "__main__":
    main()
```

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

### Launch Observability Dashboard

Source: https://github.com/brunov21/aicore/blob/main/docs/observability/dashboard.md

Instantiate and run the observability dashboard server. Ensure the specified host and port are accessible.

```python
from aicore.observability.dashboard import ObservabilityDashboard

# Create and launch dashboard
dashboard = ObservabilityDashboard()
dashboard.run_server(host="0.0.0.0", port=8050)  # Default port: 8050
```

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

### Install Claude Code CLI

Source: https://github.com/brunov21/aicore/blob/main/README.md

Commands to install the Claude Code CLI globally using npm and authenticate the CLI. Requires Node.js 18+.

```bash
# 1. Install the Claude Code CLI (requires Node.js 18+)
npm install -g @anthropic-ai/claude-code

# 2. Authenticate once
claude login
```

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

### Configure LLM with OpenAI

Source: https://github.com/brunov21/aicore/blob/main/docs/examples/simple_llm_call.md

Set up the LLM configuration, specifying the provider, API key, model, temperature, and maximum tokens. Replace 'your_api_key_here' with your actual OpenAI API key.

```python
config = LlmConfig(
    provider="openai",
    api_key="your_api_key_here",  # Replace with your actual API key
    model="gpt-4o",              # Model name
    temperature=0.7,             # Creativity level (0-1)
    max_tokens=1000              # Maximum response length
)
```

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

### Initialize and Use DeepSeek LLM

Source: https://github.com/brunov21/aicore/blob/main/docs/providers/deepseek.md

Initialize the Llm with the DeepSeek configuration and perform a basic text completion.

```python
from aicore.llm import Llm

# Initialize with config
llm = Llm(config=config)

# Basic completion
response = llm.complete("Explain quantum computing in simple terms")
```

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

### Direct MCP Client Usage

Source: https://context7.com/brunov21/aicore/llms.txt

Demonstrates direct usage of the MCPClient for tool discovery and invocation. Includes a callback for tool event notifications.

```python
from aicore.llm import Llm
from aicore.llm.config import LlmConfig
from aicore.llm.mcp.client import MCPClient
import asyncio

# MCP configuration file (mcp_config.json):
"""
{
  "mcpServers": {
    "brave-search": {
      "transport_type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {"BRAVE_API_KEY": "your_brave_api_key"}
    },
    "data-server": {
      "transport_type": "ws",
      "url": "ws://localhost:8080"
    },
    "sse-server": {
      "transport_type": "sse",
      "url": "http://localhost:3000/sse"
    }
  }
}
"""

# Using MCP with LLM via configuration
async def llm_with_mcp():
    config = LlmConfig(
        provider="openai",
        api_key="your_api_key",
        model="gpt-4o",
        mcp_config="./mcp_config.json",
        tool_choice="auto",
        max_tool_calls_per_response=3
    )
    llm = Llm.from_config(config)

    response = await llm.acomplete(
        "Search for latest news about AI advancements",
        system_prompt="Use available tools to gather information"
    )
    print(response)

asyncio.run(llm_with_mcp())

# Direct MCP client usage with tool callback
async def direct_mcp_usage():
    def on_tool_event(event):
        if event["stage"] == "started":
            print(f"Starting tool: {event['tool_name']}")
        elif event["stage"] == "concluded":
            print(f"Tool {event['tool_name']} finished in {event['duration']:.2f}s")

    async with MCPClient.from_config("./mcp_config.json", tool_callback=on_tool_event) as mcp:
        # Get all available tools
        all_tools = await mcp.servers.tools
        print(f"Available tools: {[t.name for t in all_tools]}")

        # Get tools organized by server
        tools_by_server = await mcp.servers.get_tools()
        for server, tools in tools_by_server.items():
            print(f"{server}: {[t.name for t in tools]}")

        # Call a tool (auto-routes to correct server)
        result = await mcp.servers.call_tool(
            "brave_web_search",
            {"query": "artificial intelligence"}
        )
        print(f"Search result: {result}")

asyncio.run(direct_mcp_usage())

```

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

### LLM Initialization with MCP and Async Completion

Source: https://github.com/brunov21/aicore/blob/main/llms.txt

Configure an LLM client with a Message Content Provider (MCP) configuration file and use the asynchronous `acomplete` method. Suitable for I/O-bound operations.

```python
# With MCP
config = LlmConfig(
    provider="openai",
    api_key="key",
    model="gpt-4o",
    mcp_config="./mcp_config.json"
)
llm = Llm.from_config(config)
response = await llm.acomplete("Search for AI news")
```

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

### Claude Code Provider Config File Example

Source: https://github.com/brunov21/aicore/blob/main/README.md

Example YAML configuration for the Claude Code provider in AiCore, specifying the provider, model, and optional settings like permission mode, working directory, and tool allowances.

```yaml
# config/config_example_claude_code.yml
llm:
  provider: "claude_code"
  model: "claude-sonnet-4-5-20250929"

  # Optional
  permission_mode: "bypassPermissions"   # default — all tools allowed
  cwd: "/path/to/your/project"           # working directory for the CLI
  max_turns: 10                           # limit agentic turns
  mcp_config: "./mcp_config.json"   # pass through an MCP config file
  cli_path: "/usr/local/bin/claude"      # override if CLI is not on PATH
  allowed_tools:
    - "Read"
    - "Write"
    - "Bash"
```

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

### Configure LLM for Observability Dashboard

Source: https://context7.com/brunov21/aicore/llms.txt

Set up an LLM with observability extras for tracking request volumes, latency, token usage, and costs. This example configures an OpenAI LLM and adds environment and app version details for enhanced monitoring.

```python
from aicore.observability import ObservabilityDashboard
from aicore.observability.collector import LlmOperationCollector
from aicore.llm import Llm
from aicore.llm.config import LlmConfig

# Configure LLM with observability extras
config = LlmConfig(
    provider="openai",
    api_key="your_api_key",
    model="gpt-4o"
)
llm = Llm.from_config(config)

# Add extras for tracking
llm.extras = {"environment": "production", "app_version": "1.2.3"}

# Make completions (automatically tracked)
response = llm.complete("Hello world")

```

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

### Start AICore Claude Proxy Server

Source: https://github.com/brunov21/aicore/blob/main/llms.txt

Start the `aicore-proxy-server` with various tunnel options. The `--port` option specifies the listening port, and `--tunnel` can be set to `none`, `ngrok`, `cloudflare`, or `ssh` for different tunneling methods.

```bash
# Local only (no tunnel)
aicore-proxy-server --port 8080 --tunnel none

# With ngrok tunnel (token stored in OS credential store on first use)
aicore-proxy-server --port 8080 --tunnel ngrok

# With Cloudflare tunnel
aicore-proxy-server --port 8080 --tunnel cloudflare

# With SSH reverse tunnel
aicore-proxy-server --port 8080 --tunnel ssh --ssh-host user@remote-host --ssh-remote-port 9090
```

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

### Basic Programmatic LLM Configuration

Source: https://github.com/brunov21/aicore/blob/main/llms.txt

Instantiate LlmConfig with essential parameters like provider, API key, model, temperature, and max tokens.

```python
from aicore.llm.config import LlmConfig

# Basic configuration
config = LlmConfig(
    provider="anthropic",
    api_key="your_anthropic_key",
    model="claude-3-5-sonnet-20241022",
    temperature=0.7,
    max_tokens=4096
)
```

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

### Programmatic LLM Configuration with Reasoner

Source: https://github.com/brunov21/aicore/blob/main/llms.txt

Set up LLM configuration with a separate LlmConfig instance for the reasoner, enabling advanced reasoning capabilities.

```python
# With reasoning augmentation
reasoner_config = LlmConfig(
    provider="groq",
    api_key="your_groq_key",
    model="deepseek-r1-distill-llama-70b"
)

config = LlmConfig(
    provider="openai",
    api_key="your_openai_key",
    model="gpt-4o",
    reasoner=reasoner_config
)
```

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

### WebSocket Chat Message

Source: https://github.com/brunov21/aicore/blob/main/examples/fastapi/README.md

Example of a text message to be sent over the WebSocket for chat interaction.

```text
"Hello, how can you help me today?"
```

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

### Implementing a New Provider

Source: https://github.com/brunov21/aicore/blob/main/docs/llm/base_provider.md

Guidelines and a skeleton for creating a new LLM provider implementation by inheriting from `LlmBaseProvider`.

```APIDOC
## Implementing a New Provider

To create a new LLM provider implementation:

1.  **Inherit**: Create a class that inherits from `LlmBaseProvider`.
2.  **Implement Methods**: Implement the abstract methods `complete` and `acomplete`.
3.  **API Communication**: Handle the specific API calls and authentication for the target LLM service.
4.  **Response Normalization**: Ensure that responses are normalized to the standard format expected by AiCore.
5.  **Tool Calling**: Implement support for tool calling if the provider needs to interact with MCP.

### Example Provider Skeleton:

```python
from aicore.llm.providers.base_provider import LlmBaseProvider
from aicore.llm.config import LlmConfig

class CustomProvider(LlmBaseProvider):
    def __init__(self, config: LlmConfig):
        super().__init__(config)
        # Initialize provider-specific client here
        
    def complete(self, prompt: str, **kwargs) -> Union[str, Dict]:
        # Implement synchronous completion logic
        pass
        
    async def acomplete(self, prompt: str, **kwargs) -> Union[str, Dict]:
        # Implement asynchronous completion logic
        pass
```
```