Ollama Utils

A Python library providing convenient utilities for integrating Ollama with Streamlit and Python applications. This package offers a simple, pythonic interface to Ollama's API with built-in Streamlit components for rapid prototyping of LLM applications.

Features

•  Full HTTP API Integration - No CLI dependencies
• =� Streaming Support - Real-time response streaming
• <� Parameter Control - Fine-tune model behavior (temperature, top_p, etc.)
• =� Streamlit Components - Ready-to-use UI components
• = Model Management - List, pull, delete, and inspect models
• =� Chat Interface - Multi-turn conversations
• <� Simple API - Easy to use, well-documented functions

Installation

Using uv (recommended)

uv add ollama-utils

Using pip

pip install ollama-utils

Prerequisites

1. Install Ollama: Download from ollama.com

2. Start Ollama server:

   ollama serve
   

3. Pull a model:

   ollama pull llama3.2:latest
   

Quick Start

Basic Text Generation

from ollama_utils import generate_with_model

# Simple generation
response = generate_with_model("llama3.2:latest", "Write a haiku about Python")
print(response)

# With custom parameters
response = generate_with_model(
    "llama3.2:latest", 
    "Explain quantum computing",
    temperature=0.7,
    num_predict=500
)

Chat Conversations

from ollama_utils import chat_with_model

messages = [
    {"role": "user", "content": "Hello! What's the weather like?"},
    {"role": "assistant", "content": "I don't have access to real-time weather data, but I can help you with weather-related questions!"},
    {"role": "user", "content": "What should I wear in 70�F weather?"}
]

response = chat_with_model("llama3.2:latest", messages)
print(response)

Streaming Responses

from ollama_utils import generate_with_model

# Stream generation
for chunk in generate_with_model("llama3.2:latest", "Tell me a story", stream=True):
    print(chunk, end="", flush=True)

# Stream chat
for chunk in chat_with_model("llama3.2:latest", messages, stream=True):
    print(chunk, end="", flush=True)

Model Management

from ollama_utils import list_models, pull_model, delete_model, show_model

# List available models
models = list_models()
for model in models:
    print(f"Model: {model['name']}, Size: {model['size']}")

# Pull a new model
result = pull_model("mistral:latest")
if result["success"]:
    print("Model pulled successfully!")

# Get model info
info = show_model("llama3.2:latest")
print(info)

Streamlit Integration

Quick Chat Interface

import streamlit as st
from ollama_utils.streamlit_helpers import chat_ui

st.title("My LLM Chat App")

# This creates a complete chat interface!
chat_ui()

Custom Streamlit App

import streamlit as st
from ollama_utils.streamlit_helpers import model_selector
from ollama_utils import generate_with_model

st.title("LLM Text Generator")

# Model selection dropdown
model = model_selector()

# Text input
prompt = st.text_area("Enter your prompt:")

if st.button("Generate"):
    if model and prompt:
        # Generate with streaming
        response_placeholder = st.empty()
        full_response = ""
        
        for chunk in generate_with_model(model, prompt, stream=True):
            full_response += chunk
            response_placeholder.markdown(full_response + "�")
        
        response_placeholder.markdown(full_response)

API Reference

Core Functions

generate_with_model(model_name, prompt, stream=False, **kwargs)

Generate text using the /api/generate endpoint.

Parameters:

• model_name (str): Name of the model (e.g., "llama3.2:latest")
• prompt (str): Input prompt
• stream (bool): Enable streaming responses
• **kwargs: Additional parameters (temperature, top_p, num_predict, etc.)

Returns:

• If stream=False: Complete response as string
• If stream=True: Generator yielding response chunks

chat_with_model(model_name, messages, stream=False, **kwargs)

Multi-turn chat using the /api/chat endpoint.

Parameters:

• model_name (str): Name of the model
• messages (List[dict]): List of messages with "role" and "content" keys
• stream (bool): Enable streaming responses
• **kwargs: Additional parameters

Returns:

• If stream=False: Complete response as string
• If stream=True: Generator yielding response chunks

list_models()

List all locally installed models.

Returns:

• List of model dictionaries with metadata

pull_model(model_name)

Download a model from Ollama registry.

Parameters:

• model_name (str): Name of the model to pull

Returns:

• Dictionary with "success" and "output"/"error" keys

delete_model(model_name)

Remove a model from local cache.

Parameters:

• model_name (str): Name of the model to delete

Returns:

• Dictionary with "success" and "output"/"error" keys

show_model(model_name)

Display detailed information about a model.

Parameters:

• model_name (str): Name of the model

Returns:

• Formatted string with model information

is_model_installed(model_name)

Check if a model is installed locally.

Parameters:

• model_name (str): Name of the model

Returns:

• Boolean indicating if the model is installed

Streamlit Helpers

model_selector(label="Select a local model", sidebar=True)

Create a dropdown selector for available models.

Parameters:

• label (str): Label for the selector
• sidebar (bool): Whether to place in sidebar

Returns:

• Selected model name or None

chat_ui(model_name=None, streaming=True)

Complete chat interface with history and controls.

Parameters:

• model_name (str, optional): Model to use (if None, shows selector)
• streaming (bool): Enable streaming responses

Advanced Usage

Custom Parameters

# Fine-tune model behavior
response = generate_with_model(
    "llama3.2:latest",
    "Explain machine learning",
    temperature=0.8,      # Creativity (0.0-2.0)
    top_p=0.9,           # Nucleus sampling (0.0-1.0)
    top_k=40,            # Top-k sampling (1-100)
    repeat_penalty=1.1,   # Repetition penalty (0.0-2.0)
    num_predict=1000,     # Max tokens to generate
)

Error Handling

from ollama_utils import chat_with_model

try:
    response = chat_with_model("nonexistent-model", messages)
    if response.startswith("Chat error"):
        print(f"Error occurred: {response}")
    else:
        print(f"Response: {response}")
except Exception as e:
    print(f"Unexpected error: {e}")

Demo Application

Run the included demo to test all features:

git clone https://github.com/malpasocodes/ollama-utils.git
cd ollama-utils
uv sync
uv run streamlit run demo_app.py

The demo includes:

• Model management interface
• Text generation testing
• Chat interface
• API parameter testing
• Full chat UI demonstration

Requirements

• Python 3.8+
• Ollama installed and running
• requests library
• streamlit library (for Streamlit helpers)

Contributing

1. Fork the repository
2. Clone and set up development environment:

   git clone https://github.com/your-username/ollama-utils.git
   cd ollama-utils
   uv sync
   

3. Create a feature branch (git checkout -b feature/amazing-feature)
4. Run tests: uv run pytest
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

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

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: API Reference

Changelog

0.1.0

• Initial release
• Full HTTP API integration
• Streaming support
• Streamlit helpers
• Model management functions
• Chat and generation capabilities