Ollama Client Skill

Overview

This skill provides a Python wrapper for interacting with Ollama's REST API to generate text completions using the Phi-4 model (14B parameters, 16K context window). It handles timeouts, retries, and structured logging for all LLM operations.

When to Use

Use this skill when you need to:

• •Generate text completions from Phi-4
• •Run prompts for clinical analysis tasks
• •Generate JSON-structured outputs from LLM
• •Handle LLM inference with timeout protection

Installation

IMPORTANT: This skill has its own isolated virtual environment (.venv) managed by uv. Do NOT use system Python.

Initialize the skill's environment:

# From the skill directory
cd .agent/skills/ollama-client
uv sync  # Creates .venv and installs dependencies from pyproject.toml

Dependencies are in pyproject.toml:

• •requests - HTTP client for Ollama API

Usage

CRITICAL: Always use uv run to execute code with this skill's .venv, NOT system Python.

Basic Text Generation

# From .agent/skills/ollama-client/ directory
# Run with: uv run python -c "..."
from ollama_client import OllamaClient

# Initialize client
client = OllamaClient(
    host="http://localhost:11434",  # Default from OLLAMA_HOST env var
    model="phi4:14b",                 # Default from OLLAMA_MODEL env var
    timeout=300                       # 5 minutes default
)

# Generate completion
result = client.generate(
    prompt="Summarize the following clinical note: ...",
    temperature=0.1,      # Low temperature for deterministic outputs
    max_tokens=1000,      # Optional token limit
    stop_sequences=["END"]  # Optional stop sequences
)

print(result["response"])
print(f"Execution time: {result['execution_time_ms']}ms")

With Environment Variables

import os

# Set in .env or docker-compose.yml
os.environ['OLLAMA_HOST'] = 'http://localhost:11434'
os.environ['OLLAMA_MODEL'] = 'phi4:14b'

# Client uses env vars automatically
client = OllamaClient()

Using from Another Module

When importing this skill from agents or other code:

import sys
from pathlib import Path

# Add skill to path (use relative path from your location)
skill_path = Path(__file__).parent.parent.parent / ".agent/skills/ollama-client"
sys.path.insert(0, str(skill_path))

from ollama_client import OllamaClient
client = OllamaClient()

Health Check

# Check if Ollama server is accessible
if client.is_available():
    print("Ollama server is healthy")
else:
    print("Ollama server unavailable")

Configuration

Environment Variables:

• •OLLAMA_HOST: Server URL (default: http://localhost:11434)
• •OLLAMA_MODEL: Model name (default: phi4:14b)

Parameters:

• •temperature: Sampling temperature (0.0-1.0, default: 0.1 for deterministic outputs)
• •max_tokens: Maximum tokens to generate (optional)
• •stop_sequences: List of strings to stop generation (optional)
• •timeout: Request timeout in seconds (default: 300)

Error Handling

The skill raises exceptions for:

• •Timeout: If request exceeds timeout duration
• •Connection Error: If Ollama server is unreachable
• •API Error: If Ollama returns an error response

All errors include execution time for debugging.

Best Practices

1. •Low Temperature: Use temperature=0.1 for clinical tasks requiring consistency
2. •Timeouts: Set appropriate timeouts based on prompt complexity (simple: 60s, complex: 300s)
3. •Health Checks: Verify server availability before critical operations
4. •Error Logging: Always log errors with execution time for troubleshooting

Integration with Agents

Agents use this skill for all LLM operations:

• •ToC Subagent: Section topic segmentation
• •Summary Subagent: Clinical entity extraction
• •Recommendation Subagent: Treatment plan generation
• •Evaluator Agent: Quality validation reasoning

Implementation

See ollama_client.py for the full Python implementation.