### Regenerate Documentation Examples

Source: https://github.com/arthur-ficial/apfel/blob/main/AGENTS.md

Runs the example prompt suite against the installed binary to update the documentation.

```bash
bash scripts/generate-examples.sh          # ~2 minutes, overwrites docs/EXAMPLES.md
```

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

### Install and Configure apfel-run

Source: https://github.com/arthur-ficial/apfel/blob/main/README.md

Commands to install the apfel-run wrapper and initialize a starter configuration file.

```bash
brew install Arthur-Ficial/tap/apfel-run
apfel-run config init                 # starter ~/.config/apfel/config.toml
alias apfel=apfel-run                 # optional, every apfel flag still works
```

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

### Install OpenCode via CLI

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/integrations/opencode.md

Use the curl installer to ensure the binary is correctly placed at ~/.opencode/bin/opencode, as npm install may skip post-install scripts.

```bash
curl installer
```

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

### Install via Mint or mise

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/install.md

Alternative package management methods for installing Apfel.

```bash
mint install Arthur-Ficial/apfel
```

```bash
mise use -g github:Arthur-Ficial/apfel
```

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

### Install opencode via curl

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/integrations/opencode.md

Fetches the opencode binary to the local machine. Ensure the installation directory is added to your system PATH.

```bash
curl -fsSL https://opencode.ai/install | bash
```

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

### Run server in demo mode

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/server-security.md

Starts the server with minimal security restrictions for quick testing.

```bash
apfel --serve --footgun
# WARNING banner printed - you know what you're doing
```

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

### Build and Test Commands

Source: https://github.com/arthur-ficial/apfel/blob/main/AGENTS.md

Standard commands for building the project, running tests, and managing installations.

```bash
make test                      # BUILD + ALL TESTS (unit + integration) - the one command you need
make install                   # build release + install to /usr/local/bin (NO version bump)
make build                     # build release only (NO version bump)
make version                   # print current version
swift build                    # debug build
swift run apfel-tests          # unit tests only (1041 tests)
make preflight                 # light release gate: unit + model-free integration + policy (~1.5 min warm)
make preflight FULL=1          # full qualification incl. the serial model phase (pre-#374 behavior)
```

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

### Install apfel via Homebrew

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/brew-install.md

Use this command to install the apfel binary from homebrew-core.

```bash
brew install apfel
```

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

### Start apfel server

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/integrations.md

Launch the apfel server process to begin accepting requests.

```bash
apfel --serve
```

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

### Build Apfel from Source

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/install.md

Clones the repository and installs the binary to /usr/local/bin/apfel.

```bash
git clone https://github.com/Arthur-Ficial/apfel.git
cd apfel
make install
```

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

### Install Apfel via Homebrew

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/install.md

Installs the standard package or the tap version which includes additional demo scripts.

```bash
brew install apfel
```

```bash
brew install Arthur-Ficial/tap/apfel
```

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

### Start Apfel Service

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/background-service.md

Initializes the Apfel background service using Homebrew.

```bash
brew services start apfel
```

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

### Example wtd output

Source: https://github.com/arthur-ficial/apfel/blob/main/demo/README.md

A sample output generated by the wtd command describing a Swift project.

```text
The directory /Users/you/dev/apfel contains a Swift package project that
appears to be a macOS application. It utilizes Swift 6.2 and the Swift
Package Manager (SPM). To build or run the project, use swift build.
```

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

### Example output

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/guides/python.md

Sample output generated by the summarization script.

```text
The Apple M1 chip, released in November 2020, was Apple's first ARM-based system-on-a-chip for Mac computers. It features an 8-core CPU with four performance and four efficiency cores, plus an integrated GPU with up to 8 cores. The chip combines CPU, GPU, memory, and neural engine on a single die, delivering significant performance-per-watt improvements over the Intel chips it replaced.
```

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

### Verify apfel installation

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/brew-install.md

Check the installed version and release information to confirm successful installation.

```bash
apfel --version
apfel --release
```

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

### Configure Service via Environment Variables

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/background-service.md

Sets configuration options like ports, tokens, and MCP paths before starting the service.

```bash
# Custom port
APFEL_PORT=8080 brew services start apfel

# Token authentication
APFEL_TOKEN="my-secret" brew services start apfel
APFEL_TOKEN=$(uuidgen) brew services start apfel

# Attach MCP tool servers (colon-separated paths)
APFEL_MCP="/path/to/server.py" brew services start apfel
APFEL_MCP="/path/a.py:/path/b.py" brew services start apfel

# MCP timeout for slow/remote servers (default: 5s, max: 300s)
APFEL_MCP_TIMEOUT=30 APFEL_MCP="/path/to/remote-server.py" brew services start apfel

# System prompt
APFEL_SYSTEM_PROMPT="Be concise" brew services start apfel

# Custom host (expose to network - see security note below)
APFEL_HOST=0.0.0.0 APFEL_TOKEN=$(uuidgen) brew services start apfel
```

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

### Launch Zed with dummy API key

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/integrations.md

Start Zed with a dummy API key, as the application requires one even though apfel ignores it.

```bash
APFEL_API_KEY=dummy zed
```

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

### Create Manual Launchd Plist

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/background-service.md

Advanced configuration for custom flags and complex setups by creating a manual plist file.

```bash
cat > ~/Library/LaunchAgents/com.arthurficial.apfel.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.arthurficial.apfel</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/opt/apfel/bin/apfel</string>
        <string>--serve</string>
        <string>--port</string>
        <string>11434</string>
        <string>--mcp</string>
        <string>/absolute/path/to/server.py</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/apfel.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/apfel.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>HOME</key>
        <string>/Users/YOUR_USERNAME</string>
        <key>APFEL_TOKEN</key>
        <string>YOUR_TOKEN</string>
    </dict>
</dict>
</plist>
EOF

# Load
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.arthurficial.apfel.plist

# Unload
launchctl bootout gui/$(id -u)/com.arthurficial.apfel

# Check status
launchctl print gui/$(id -u)/com.arthurficial.apfel
```

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

### Secure Network Exposure

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/background-service.md

Example command for exposing the service to the network with token authentication enabled.

```bash
APFEL_HOST=0.0.0.0 APFEL_TOKEN=$(uuidgen) brew services start apfel
```

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

### Install Apfel via Nix

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/install.md

Installs the package using the nixpkgs attribute name apfel-llm.

```bash
nix profile install nixpkgs#apfel-llm
```

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

### Install and Update Apfel

Source: https://github.com/arthur-ficial/apfel/blob/main/README.md

Commands to install or upgrade the Apfel package using Homebrew.

```bash
brew install apfel
```

```bash
brew upgrade apfel
```

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

### Example output for one-shot request

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/guides/swift-scripting.md

The expected text output from the one-shot Swift script.

```text
Swift is a modern, open-source programming language known for its safety features, ease of use, and performance, primarily used for developing iOS, macOS, watchOS, and tvOS applications.
```

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

### Tool Selection Response

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/tool-calling-guide.md

Example of a model response selecting the correct tool from multiple available options.

```json
{
    "choices": [
        {
            "finish_reason": "tool_calls",
            "index": 0,
            "message": {
                "role": "assistant",
                "tool_calls": [
                    {
                        "function": {
                            "arguments": "{\"to\": \"john@example.com\", \"subject\": \"Hello!\", \"body\": \"Hello, John!\"}",
                            "name": "send_email"
                        },
                        "id": "call_001",
                        "type": "function"
                    }
                ]
            }
        }
    ],
    "created": 1774531618,
    "id": "chatcmpl-72a34ab1-cf4",
    "model": "apple-foundationmodel",
    "object": "chat.completion",
    "usage": {
        "completion_tokens": 51,
        "prompt_tokens": 11,
        "total_tokens": 62
    }
}
```

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

### Install demo scripts globally

Source: https://github.com/arthur-ficial/apfel/blob/main/demo/README.md

Symlink demo scripts to a local bin directory to make them available system-wide with an apfel- prefix.

```bash
mkdir -p "$HOME/.local/bin"
for d in cmd explain gitsum mac-narrator naming oneliner port wtd; do
  ln -sf "$(pwd)/demo/$d" "$HOME/.local/bin/apfel-$d"
done
```

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

### Run guide verification tests

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/guides/index.md

Clones the test repository and executes the test suite against a running apfel server instance.

```bash
git clone https://github.com/Arthur-Ficial/apfel-guides-lab
cd apfel-guides-lab
apfel --serve &
python3 -m pytest -v
```

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

### Start apfel with CORS

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/local-setup-with-vs-code.md

Command to run the server with specific origin permissions for browser clients.

```bash
apfel --serve --cors --allowed-origins "<your local origin>"
```

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

### Start and verify apfel server

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/integrations/opencode.md

Commands to launch the apfel server and verify the OpenAI-compatible API endpoint is active.

```bash
apfel --serve
```

```bash
curl -s http://127.0.0.1:11434/v1/models
```

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

### Enable Shell Completions

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/cli-reference.md

Commands to generate and install shell completion scripts for bash, zsh, and fish.

```bash
apfel completions bash | sudo tee "$(brew --prefix)/etc/bash_completion.d/apfel" >/dev/null
```

```zsh
apfel completions zsh > "${fpath[1]}/_apfel"
```

```fish
apfel completions fish > ~/.config/fish/completions/apfel.fish
```

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

### Fetch completions from JavaScript

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/server-security.md

Example of making a POST request to the Apfel chat completions endpoint.

```javascript
const response = await fetch("http://localhost:11434/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "apple-foundationmodel",
    messages: [{ role: "user", content: "Hello!" }]
  })
});
const data = await response.json();
```

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

### Verify Toolchain

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/install.md

Checks the macOS version, Swift installation, and active Apple SDK version.

```bash
# Check macOS version (needs 26+)
sw_vers

# Check Swift is installed
swift --version

# Check the active Apple SDK version (must be 26.4+)
xcrun --show-sdk-version

# If Swift is missing, install Command Line Tools:
xcode-select --install
```

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

### Run apfel-calc server and test round trip

Source: https://github.com/arthur-ficial/apfel/blob/main/mcp/calculator/README.md

Starts the server in the background and executes a test script to verify tool calling functionality.

```bash
apfel --serve &
python3 mcp/calculator/test_round_trip.py
# Question: What is 247 times 83?
# Step 1: Model called multiply({"a": 247, "b": 83})
# Step 2: Calculator result: 20501
# Step 3: Final answer: The product of 247 and 83 is 20,501.
```

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

### Build and Test Commands

Source: https://github.com/arthur-ficial/apfel/blob/main/README.md

Standard Makefile and Swift commands for building, testing, and releasing the project.

```bash
make test                                # release build + all unit/integration tests
make preflight                           # full release qualification
make install                             # build release + install to /usr/local/bin
make build                               # build release only
make version                             # print current version
make release                             # patch release
make release TYPE=minor                  # minor release
make release TYPE=major                  # major release
swift build                              # quick debug build (no version bump)
swift run apfel-tests                    # unit tests
python3 -m pytest Tests/integration/ -v  # integration tests
apfel --benchmark -o json                # performance report
```

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

### Using the oneliner demo

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/demos.md

Generates complex pipe chains from plain English descriptions.

```bash
demo/oneliner "sum the third column of a CSV"
# $ awk -F',' '{sum += $3} END {print sum}' file.csv

demo/oneliner "count unique IPs in access.log"
# $ awk '{print $1}' access.log | sort | uniq -c | sort -rn
```

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

### Run server for standard CLI or SDK access

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/server-security.md

Standard server startup for local use with curl or the OpenAI Python SDK.

```bash
apfel --serve

# curl works as-is
curl -X POST http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"apple-foundationmodel","messages":[{"role":"user","content":"Hi"}]}'

# Python SDK works as-is
from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ignored")
```

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

### GET /health

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/openai-api-compatibility.md

Checks the health and availability of the model.

```APIDOC
## GET /health

### Description
Returns the status of the model, including availability, context window, and supported languages.

### Method
GET

### Endpoint
/health
```

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

### GET /v1/models

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/openai-api-compatibility.md

Retrieves the list of available models.

```APIDOC
## GET /v1/models

### Description
Returns the list of available models. Currently returns `apple-foundationmodel`.

### Method
GET

### Endpoint
/v1/models
```

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

### Allowed Requests

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/server-security.md

Examples of requests that bypass or satisfy the default security checks.

```bash
# curl - no Origin header, always works
curl http://localhost:11434/v1/models
# => 200 OK

# Python SDK - no Origin header, always works
python3 -c "
from openai import OpenAI
c = OpenAI(base_url='http://localhost:11434/v1', api_key='ignored')
print(c.models.list().data[0].id)
"
# => apple-foundationmodel
```

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

### Using the cmd demo

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/demos.md

Translates natural language queries into shell commands with optional execution or clipboard copying.

```bash
demo/cmd "find all .log files modified today"
# $ find . -name "*.log" -type f -mtime -1

demo/cmd -x "show disk usage sorted by size"   # -x = execute after confirm
demo/cmd -c "list open ports"                  # -c = copy to clipboard
```

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

### Enable permissive guardrails

Source: https://github.com/arthur-ficial/apfel/blob/main/README.md

Starts the server with permissive content transformations enabled for all requests.

```bash
apfel --serve --permissive             # every request uses permissive guardrails
```

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

### Verify PATH configuration

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/brew-install.md

Use these commands to ensure the Homebrew binary is correctly prioritized in your system PATH.

```bash
which apfel
brew --prefix
```

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

### Utility and Maintenance Commands

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/cli-reference.md

Access benchmarks, model info, updates, and help documentation.

```bash
apfel --benchmark -o json | jq '.benchmarks[] | {name, speedup_ratio}'
apfel --model-info
apfel --update
apfel --release
apfel --version
apfel --help
```

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

### Implement Tool Calling in PHP

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/guides/php.md

Shows how to define tools, process tool calls from the model, and return tool results to the chat completion loop.

```php
<?php
require __DIR__ . "/vendor/autoload.php";

$client = OpenAI::factory()->withBaseUri("http://localhost:11434/v1")->withApiKey("not-needed")->make();

$tools = [[
    "type" => "function",
    "function" => [
        "name" => "get_weather",
        "description" => "Get the current temperature in Celsius for a city.",
        "parameters" => [
            "type" => "object",
            "properties" => ["city" => ["type" => "string"]],
            "required" => ["city"],
        ],
    ],
]];

function get_weather(array $args): string {
    $fake = ["Vienna" => 14, "Cupertino" => 19, "Tokyo" => 11];
    $city = $args["city"] ?? "";
    return json_encode(["city" => $city, "temp_c" => $fake[$city] ?? 15]);
}

$messages = [["role" => "user", "content" => "What is the temperature in Vienna right now?"]];

$first = $client->chat()->create([
    "model" => "apple-foundationmodel", "messages" => $messages, "tools" => $tools, "max_tokens" => 256,
]);
$msg = $first->choices[0]->message;
$messages[] = $msg->toArray();

if (!empty($msg->toolCalls)) {
    foreach ($msg->toolCalls as $call) {
        $args = json_decode($call->function->arguments, true) ?? [];
        $messages[] = ["role" => "tool", "tool_call_id" => $call->id, "content" => get_weather($args)];
    }
    $final = $client->chat()->create([
        "model" => "apple-foundationmodel", "messages" => $messages, "max_tokens" => 120,
    ]);
    echo trim($final->choices[0]->message->content ?? "") . "\n";
}
```

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

### Analyze directories with wtd

Source: https://github.com/arthur-ficial/apfel/blob/main/demo/README.md

Provides an instant summary of a directory's purpose, language, and build instructions.

```bash
./wtd                    # current directory
./wtd ~/some/project     # any directory
./wtd -c .               # copy summary to clipboard
```

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

### Blocked Requests

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/server-security.md

Examples of requests that trigger a 403 Forbidden response due to unauthorized Origin headers.

```bash
# Browser JavaScript from a foreign site
curl -H "Origin: http://evil.com" http://localhost:11434/v1/models
# => 403 Forbidden
# => {"error":{"message":"Origin 'http://evil.com' is not allowed.","type":"forbidden"}}

# Subdomain attacks (http://localhost.evil.com != http://localhost)
curl -H "Origin: http://localhost.evil.com" http://localhost:11434/v1/models
# => 403 Forbidden
```

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

### Tool Call Response JSON

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/tool-calling-guide.md

Example of a tool call response structure when a tool is invoked without a description.

```json
{
    "choices": [
        {
            "finish_reason": "tool_calls",
            "index": 0,
            "message": {
                "role": "assistant",
                "tool_calls": [
                    {
                        "function": {
                            "arguments": "{\"term\": \"cats\", \"language\": \"en\", \"numResults\": 10}",
                            "name": "search"
                        },
                        "id": "call_1",
                        "type": "function"
                    }
                ]
            }
        }
    ]
}
```

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

### Manage tokens via CLI

Source: https://github.com/arthur-ficial/apfel/blob/main/README.md

Demonstrates setting token limits using CLI arguments or environment variables.

```bash
apfel "Reply SKIP."                    # uses remaining window
apfel --max-tokens 64 "Reply SKIP."    # explicit cap
APFEL_MAX_TOKENS=2048 apfel "..."      # via env var
```

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

### Configure max_tokens via cURL

Source: https://github.com/arthur-ficial/apfel/blob/main/README.md

Examples of sending chat completion requests with and without an explicit max_tokens limit.

```bash
# Omitted: uses remaining window, finish_reason: "stop" or "length"
curl -sS http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"apple-foundationmodel",
       "messages":[{"role":"user","content":"Reply SKIP, MOVE, or RENAME."}]}'
```

```bash
# Explicit cap (recommended for tight latency budgets)
curl -sS http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"apple-foundationmodel","max_tokens":128,
       "messages":[{"role":"user","content":"Summarise: ..."}]}'
```

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

### Troubleshoot Build Errors

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/install.md

Commands to update Command Line Tools and ensure the correct SDK is active.

```bash
# update/install Command Line Tools
xcode-select --install

# ensure the CLT developer dir is selected
sudo xcode-select -s /Library/Developer/CommandLineTools

# confirm the active SDK is new enough
xcrun --show-sdk-version

# retry
make install
```

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

### Default Guardrail Block Response

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/PERMISSIVE.md

Example of the error message returned when a request is blocked by default safety guardrails.

```text
error: [guardrail] The request was blocked by Apple's safety guardrails. Try rephrasing.
```

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

### Server Mode

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/cli-reference.md

Run apfel as a server with --serve and configure networking options.

```bash
apfel --serve
apfel --serve --port 3000 --host 0.0.0.0
```

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

### Executing the cmd shell function

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/demos.md

Examples of using the custom cmd shell function for various system tasks.

```bash
cmd find all swift files larger than 1MB
cmd -c show disk usage sorted by size
cmd -x what process is using port 3000
cmd list all git branches merged into main
cmd count lines of code by language
```

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

### Run Preflight Checks

Source: https://github.com/arthur-ficial/apfel/blob/main/AGENTS.md

Executes the local release gate to verify git state, unit tests, and version sanity. Do not proceed with a release if this command fails.

```bash
make preflight
```

```bash
make preflight FULL=1
```

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

### Manage Apfel Background Service

Source: https://github.com/arthur-ficial/apfel/blob/main/README.md

Commands to start or stop the Apfel background service using Homebrew services.

```bash
apfel --serve                              # foreground
brew services start apfel                  # background (like Ollama)
brew services stop apfel
APFEL_TOKEN=$(uuidgen) APFEL_MCP=/path/to/tools.py brew services start apfel
```

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

### Run preflight checks

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/release.md

Executes the local qualification script to verify the environment and code state before a release.

```bash
make preflight
```

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

### Required Tool Choice Response

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/tool-calling-guide.md

Example of a model response when tool_choice is set to required, demonstrating forced tool invocation.

```json
{
    "choices": [
        {
            "finish_reason": "tool_calls",
            "index": 0,
            "message": {
                "role": "assistant",
                "tool_calls": [
                    {
                        "function": {
                            "arguments": "{\"city\": \"Vienna\", \"country\": \"Austria\"}",
                            "name": "get_info"
                        },
                        "id": "call_1",
                        "type": "function"
                    }
                ]
            }
        }
    ]
}
```

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

### Parallel Tool Call Failure Response

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/tool-calling-guide.md

Example of a model response when failing to execute multiple parallel tool calls.

```json
{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "message": {
                "content": "I'm sorry, but I can't assist with that request.",
                "role": "assistant"
            }
        }
    ]
}
```

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

### Set System Prompts

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/cli-reference.md

Configure system behavior using the -s or --system flag, or read a system prompt from a file with --system-file.

```bash
apfel -s "You are a pirate" "What is recursion?"
apfel -s "Reply in JSON only" "List 3 colors"
apfel --system-file persona.txt "Introduce yourself"
```

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

### System Prompt Reinforced Tool Call

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/tool-calling-guide.md

Example of a successful tool call response achieved through system prompt reinforcement.

```json
{
    "choices": [
        {
            "finish_reason": "tool_calls",
            "index": 0,
            "message": {
                "role": "assistant",
                "tool_calls": [
                    {
                        "function": {
                            "arguments": "{\"city\": \"Berlin\"}",
                            "name": "get_weather"
                        },
                        "id": "call_unique",
                        "type": "function"
                    }
                ]
            }
        }
    ],
    "created": 1774531677,
    "id": "chatcmpl-c237372f-77e",
    "model": "apple-foundationmodel",
    "object": "chat.completion",
    "usage": {
        "completion_tokens": 57,
        "prompt_tokens": 8,
        "total_tokens": 65
    }
}
```

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

### Malformed Tool Call Response

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/tool-calling-guide.md

Example of a response where the model hallucinated a tool name and schema, resulting in malformed JSON.

```json
{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "message": {
                "content": "```json\n{\"tool_calls\": [{\"id\": \"call_1\", \"type\": \"function\", \"function\": {\"name\": \"addition\", \"arguments\": \"{\\\"numbers\\\": [2, 2]}\"}}]}
```",
                "role": "assistant"
            }
        }
    ]
}
```

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

### Build apfel-llm locally with nix-build

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/nixpkgs.md

Clones the Nixpkgs repository and builds the apfel-llm package to verify the build process.

```bash
git clone --depth 1 https://github.com/NixOS/nixpkgs.git /tmp/nixpkgs-test
cd /tmp/nixpkgs-test
nix-build -A apfel-llm --no-out-link

ls /nix/store/*-apfel-llm-*/bin/apfel
```

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

### Execute LLM tool calling workflow in Zsh

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/guides/zsh.md

This script demonstrates a complete tool calling cycle: sending a prompt with tool definitions, parsing the tool call, simulating a tool execution, and sending the result back to the model.

```zsh
#!/bin/zsh
emulate -L zsh
setopt err_exit pipe_fail no_unset

local tools='[{
  "type":"function",
  "function":{
    "name":"get_weather",
    "description":"Get the current temperature in Celsius for a city.",
    "parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}
  }
}]'

local first
first=$(jq -n --argjson tools "$tools" '{
  model:"apple-foundationmodel",
  messages:[{role:"user", content:"What is the temperature in Vienna right now?"}],
  tools:$tools,
  max_tokens:256
}' | curl -sS http://localhost:11434/v1/chat/completions \
       -H "Content-Type: application/json" -d @-)

local msg=$(jq -c '.choices[0].message' <<<"$first")
local call=$(jq -c '.tool_calls[0]' <<<"$msg")
local city=$(jq -r '.function.arguments | fromjson | .city' <<<"$call")
local -A fake=(Vienna 14 Cupertino 19 Tokyo 11)
local temp=${fake[$city]:-15}

local tool_result=$(jq -cn --arg c "$city" --argjson t "$temp" '{city:$c, temp_c:$t}')
local tool_msg=$(jq -cn --arg id "$(jq -r '.id' <<<"$call")" --arg content "$tool_result" \
  '{role:"tool", tool_call_id:$id, content:$content}')

local final_payload=$(jq -n --argjson msg "$msg" --argjson tool "$tool_msg" '{
  model:"apple-foundationmodel",
  messages:[{role:"user", content:"What is the temperature in Vienna right now?"}, $msg, $tool],
  max_tokens:120
}')

curl -sS http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" -d "$final_payload" \
  | jq -r '.choices[0].message.content'
```

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

### Verify apfel server health

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/guides/index.md

Starts the apfel server and checks the health endpoint to ensure the service is ready for requests.

```bash
apfel --serve &
curl -s http://localhost:11434/health
# {"status":"ok"}
```

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

### Implement Tool Calling in Python

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/guides/python.md

Shows the full cycle of defining a tool, sending a prompt, processing tool calls, and retrieving the final response. Uses the standard OpenAI client structure.

```python
import json
from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="not-needed")

TOOLS = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current temperature in Celsius for a city.",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string", "description": "City name"}},
            "required": ["city"],
        },
    },
}]


def get_weather(city: str, **_: object) -> str:
    fake = {"Vienna": 14, "Cupertino": 19, "Tokyo": 11}
    return json.dumps({"city": city, "temp_c": fake.get(city, 15)})


messages = [{"role": "user", "content": "What is the temperature in Vienna right now?"}]

first = client.chat.completions.create(
    model="apple-foundationmodel", messages=messages, tools=TOOLS, max_tokens=256,
)

msg = first.choices[0].message
messages.append(msg.model_dump(exclude_none=True))

if msg.tool_calls:
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = get_weather(**args)
        messages.append({"role": "tool", "tool_call_id": call.id, "content": result})

    final = client.chat.completions.create(
        model="apple-foundationmodel", messages=messages, max_tokens=120,
    )
    print((final.choices[0].message.content or "").strip())
```

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

### Minimal MCP Server Implementation

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/mcp-calculator.md

A basic Python script demonstrating the required JSON-RPC handling for an MCP server over stdio.

```python
#!/usr/bin/env python3
import json, sys

def read():
    line = sys.stdin.readline()
    return json.loads(line.strip()) if line else None

def send(msg):
    sys.stdout.write(json.dumps(msg) + "\n")
    sys.stdout.flush()

def respond(id, result):
    send({"jsonrpc": "2.0", "id": id, "result": result})

while True:
    msg = read()
    if not msg:
        break
    method = msg.get("method", "")
    id = msg.get("id")

    if method == "initialize":
        respond(id, {
            "protocolVersion": "2025-06-18",
            "capabilities": {"tools": {}},
            "serverInfo": {"name": "my-tool", "version": "1.0.0"}
        })
    elif method == "notifications/initialized":
        pass
    elif method == "tools/list":
        respond(id, {"tools": [{
            "name": "my_tool",
            "description": "What it does",
            "inputSchema": {
                "type": "object",
                "properties": {"input": {"type": "string"}},
                "required": ["input"]
            }
        }]})
    elif method == "tools/call":
        args = msg["params"]["arguments"]
        result = "your result here"
        respond(id, {
            "content": [{"type": "text", "text": result}],
            "isError": False
        })
    elif method == "ping":
        respond(id, {})
```

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

### Apply system prompts

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/EXAMPLES.md

Use the -s flag to define persona or response constraints for the model.

```bash
$ apfel -s "You are a pirate. Respond only in pirate speak." "What is recursion?"
```

```bash
$ apfel -s "Respond in exactly 5 words." "Explain quantum computing."
```

```bash
$ apfel -s "You are a Socratic teacher. Only respond with questions." "What is gravity?"
```

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

### Explicit Tool Use Request Response

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/tool-calling-guide.md

Example of a model response containing a hallucinated tool name and malformed JSON structure.

```json
{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "message": {
                "content": "```json\n{\"tool_calls\": [{\"id\": \"cat_info\", \"type\": \"function\", \"function\": {\"name\": \"wikipedia.info\", \"arguments\": {\"q\": \"cats\"}}}]}\n```",
                "role": "assistant"
            }
        }
    ]
}
```

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

### Interact with Apfel via OpenAI API

Source: https://github.com/arthur-ficial/apfel/blob/main/README.md

Examples of querying the local Apfel server using curl or the OpenAI Python client.

```bash
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"apple-foundationmodel","messages":[{"role":"user","content":"Hello"}]}'
```

```python
from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="unused")
resp = client.chat.completions.create(
    model="apple-foundationmodel",
    messages=[{"role": "user", "content": "What is 1+1?"}],
)
print(resp.choices[0].message.content)
```

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

### Using the mac-narrator demo

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/demos.md

Provides a narration of system activity, with an optional watch mode.

```bash
demo/mac-narrator
demo/mac-narrator --watch
```

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

### MCP Tool Integration

Source: https://github.com/arthur-ficial/apfel/blob/main/docs/cli-reference.md

Configure MCP servers using --mcp, --mcp-token, and --mcp-timeout flags.

```bash
apfel --mcp ./mcp/calculator/server.py "What is 15 times 27?"
apfel --mcp ./calc.py --mcp ./weather.py "Use both tools"
apfel --mcp https://mcp.example.com/v1 "Remote MCP server"
APFEL_MCP_TOKEN=mytoken apfel --mcp https://mcp.example.com/v1 "With auth"
apfel --mcp-timeout 30 --mcp ./slow-remote-server.py "hello"
```