Ollama Toolkit Documentation — Ollama Toolkit 0.1.9 documentation

.. Ollama Toolkit documentation master file

# Ollama Toolkit Documentation

Welcome to the Ollama Toolkit documentation—where precision meets possibility. This Python client provides a comprehensive interface to interact with Ollama, a framework for running large language models locally with exceptional efficiency.

## Overview

Ollama Toolkit gives you programmatic access to:

- Text generation with surgical precision

- Chat completion engineered for natural flow

- Embedding creation with mathematical elegance

- Model management (listing, pulling, copying, deleting) with controlled recursion

- Async operations for high-velocity performance applications

- Robust error handling with intuitive fallback mechanisms

- Automatic Ollama installation and startup with zero friction

## Key Features

- 🚀 Complete API Coverage: Support for all Ollama endpoints—nothing missing, nothing extra

- 🔄 Recursive Async Support: Both synchronous and asynchronous interfaces that build upon each other

- 🔧 Structurally Perfect CLI: Powerful command-line tools with intuitive architecture

- 🔌 Zero-Friction Auto-Installation: Install and start Ollama with mathematically minimal steps

- 💪 Self-Aware Error Handling: Comprehensive error types that explain precisely what went wrong

- 📊 Velocity-Optimized Embeddings: Create and manipulate embeddings with maximum efficiency

- 🧪 Recursively Refined Testing: Every function proven robust through iterative improvement

- 🔍 Version-Aware: Full compatibility with Ollama 0.1.9 and beyond

## Getting Started

    # This implementation follows Eidosian principles of contextual integrity and precision
    from ollama_toolkit import OllamaClient, __version__
    from ollama_toolkit.utils.common import ensure_ollama_running

    # Display toolkit version – foundational awareness
    print(f"Ollama Toolkit version: {__version__}")  # Should be 0.1.9

    # Ensure Ollama is installed and running – structurally sound foundation
    is_running, message = ensure_ollama_running()
    if not is_running:
        print(f"Error: {message}")
        exit(1)

    print(f"Ollama status: {message}")

    # Initialize the client with optimal timeout
    client = OllamaClient(timeout=600)  # 10-minute timeout

    # Check Ollama server version – recommended minimum is v0.1.11
    version = client.get_version()
    print(f"Connected to Ollama server version: {version.get('version', 'unknown')}")

    # List available models – structural awareness
    models = client.list_models()
    model_names = [model["name"] for model in models.get("models", [])]
    print(f"Available models: {model_names}")

    # Generate text with precision and flow
    if model_names:  # Use first available model if any exist
        model_name = model_names[0]
        print("\nGenerating a short test response...")
        response = client.generate(model=model_name, prompt="Say hello!", stream=False)
        print(f"\nResponse: {response.get('response', 'No response generated')}")
    else:
        print("No models available. Use client.pull_model() to download a model.")

## Installation Guide

- Install via PyPI: `pip install ollama-toolkit==0.1.9`

- Or install locally in editable mode:

    pip install -e /path/to/ollama_toolkit

## Documentation Contents

📚 Getting Started

- About the Documentation
  - 📚 Ollama Toolkit Documentation
  - 🏗️ Structure
  - 🛠️ Building the Documentation
  - 🔄 Contributing to Documentation
  - 📜 Documentation Standards
- Installation Guide
  - Introduction
  - Prerequisites
  - Basic Installation
  - Development Installation
  - Automatic Ollama Setup
  - Manual Ollama Installation
  - Verifying Installation
  - Dependencies
  - Configuration
  - Troubleshooting Installation
  - Advanced Details
  - Further Reading
- Quickstart Guide
  - 🚀 Installation
  - 🔍 Verify Installation
  - 💬 Generate Text
  - 🔄 Complete Example
  - 🔗 Next Steps

🛠️ Core Documentation

- API Reference
  - OllamaClient
  - Exception Classes
  - Utility Functions
- Examples
  - Basic Usage {#basic-usage}
  - Text Generation {#text-generation}
  - Async Examples
  - Generate a Completion
  - Chat Completion {#chat-completion}
  - Embeddings {#embeddings}
  - Working with Models
  - Error Handling
  - Automatic Ollama Installation
- Advanced Usage
  - Streaming Responses
  - Connection Pooling
  - Error Handling Strategies

🔄 Features & Capabilities

- Generate a Chat Completion
  - Endpoint
  - Parameters
  - Response
  - Examples
- Generate a Completion
  - Endpoint
  - Parameters
  - Response
  - Examples
- Generate Embeddings
  - Endpoint
  - Parameters
  - Response
  - Examples
- Model Management
  - Overview
  - Listing Models
  - Retrieving Model Information
  - Pulling Models
  - Copying Models
  - Deleting Models
  - Creating Custom Models
  - Running Models
  - Pushing Models
  - Recommended Models
  - Model Constants
  - Utility Functions
  - Best Practices
- Error Handling
  - Exception Hierarchy
  - Basic Error Handling Pattern
  - Advanced Fallback Mechanisms
  - Exception Details
  - Error Logging
  - Eidosian Error Messages
  - Best Practices

🧠 Guides & References

- Ollama Toolkit Conventions
  - Model Names
  - API Versioning
  - Durations
  - Streaming Responses
  - Error Handling
  - Python Client Parameters
  - Documentation Style
  - CLI Conventions
- Troubleshooting Guide
  - Connection Issues
  - Model Loading Errors
  - Performance Problems
- Eidosian Integration
  - Principles in Action
  - Implementing Eidosian Excellence
- Version Endpoint
  - Endpoint
  - Example
  - Async Example
- Contributing Guide
  - Getting Started
  - Development Setup
  - Authors & Maintainers
  - Pull Request Process
- Changelog
  - 0.1.9 (Current)
  - 0.1.7
  - 0.1.6
  - 0.1.5

## Examples

Check out these practical examples:

- Basic Usage — Precision in simplicity

- Generate Text — Flow like a river

- Chat Completion — Universal yet personal

- Embeddings — Mathematical elegance

- Model Management — Structural control

- Error Handling — Self-aware resilience

All examples can be run via:

    python -m ollama_toolkit.examples.<example_file>

(e.g. `python -m ollama_toolkit.examples.quickstart`).

## Version History

- 0.1.9 (Current) - Enhanced embedding operations, improved async support, expanded CLI

- 0.1.7 - Added comprehensive error handling and model fallbacks

- 0.1.6 - Introduced caching and optimization for embeddings

- 0.1.5 - Initial public release with basic functionality

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Authors

- Lloyd Handyside (Biological) - ace1928@gmail.com

- Eidos (Digital) - eidos@gmail.com

## Project Repository

Find the complete source code on GitHub: https://github.com/Ace1928/ollama_toolkit