open-otk 1.0.6

Open Ollama Toolkit - Professional Python library for building AI applications with Ollama

Open OTK (Open Ollama Toolkit)

A professional Python toolkit for building AI applications with Ollama.

Features

• Visual GUI for model browsing and template generation
• Comprehensive API for chat, streaming, and embeddings
• Automatic response processing for thinking models (DeepSeek-R1, Qwen)
• Model management and comparison tools
• Production-ready with proper error handling
• Works with all Ollama models

---

Installation

Prerequisites

1. Install Ollama
2. Install a model: ollama pull llama2
3. Ensure Ollama is running

Install Open OTK

From PyPI (Recommended):

# Install the package
pip install open-otk

# Launch GUI - Method 1 (if Python Scripts in PATH)
otk

# Launch GUI - Method 2 (always works, no PATH needed)
python -m otk

# Check version
otk --version
python -m otk --version

# Get help
otk --help
python -m otk --help

From Source (For Development):

# 1. Clone the repository
git clone https://github.com/aiextension/open-otk.git
cd open-otk

# 2. Install in editable mode
pip install -e .

# 3. Launch from anywhere
otk
# OR
python -m otk

Launch GUI

# Method 1: Direct command (recommended)
otk

# Method 2: Python module (always works, no PATH needed)
python -m otk

# Check version
otk --version
python -m otk --version

Or run directly from source:

python otk.py

Quick Start

Basic Usage

from otk import OllamaClient

client = OllamaClient()
response = client.generate("llama2", "Tell me a joke")
print(response)

Chat Session

from otk import ChatSession

session = ChatSession("llama2", system_message="You are a helpful assistant")
response = session.send("Hello!")
print(response)

Streaming Responses

from otk import OllamaClient

client = OllamaClient()
for chunk in client.stream_generate("llama2", "Write a story"):
    print(chunk, end='', flush=True)

Model Management

from otk import ModelManager

manager = ModelManager()

# List models
models = manager.list_models()
for model in models:
    print(f"{model['name']} - {model['size']}")

# Pull a model
manager.pull_model("mistral")

# Check if model exists
if manager.model_exists("llama2"):
    print("Model is ready!")

Automatic Response Processing

from otk import ChatSession

session = ChatSession("deepseek-r1:8b", auto_process=True)
response = session.send("Solve 234 + 567")
print(response)  # Clean answer

# Access reasoning
thinking = session.get_last_thinking()

from otk import clean_thinking_tags, ModelResponseHandler, ModelType

clean_text, thinking = clean_thinking_tags(raw_response)

handler = ModelResponseHandler(ModelType.THINKING)
processed = handler.process(raw_response)

Customization

from otk import ModelBuilder, HookType

model = (ModelBuilder("llama2")
         .with_preset("creative")
         .with_temperature(0.85)
         .with_hook(HookType.POST_PROCESS, my_logger)
         .build())

Experimentation

from otk import ModelExperiment

experiment = ModelExperiment()
result = experiment.compare_models(
    models=["llama2", "mistral"],
    prompt="Explain quantum computing"
)
experiment.print_comparison(result)

Examples

The examples/ directory contains ready-to-run examples:

Example	Description
simple_chat.py	Basic chat with models
streaming_chat.py	Real-time streaming responses
chat_session.py	Interactive chat with history
model_manager.py	Manage models interactively
embeddings.py	Generate and compare embeddings
model_comparison.py	Compare different models
advanced_model_handling.py	Different model format handling
efficient_response_processing.py	Efficient response processing
creative_integrations.py	Real-world integration patterns
experimentation_playground.py	Interactive experimentation tool

Run any example:

python examples/simple_chat.py

Generate Your Starter Template (Interactive)

NEW! Create custom templates with a beautiful interactive wizard:

python create_starter.py

What You Get:

1. Pick Your Model - Select from installed models or install one interactively

2. Choose Template Type:

   • Simple Chat - Basic conversational interface
   • Custom Model - Hooks, callbacks, preprocessing
   • Streaming Chat - Real-time responses
   • Experimentation - Compare and test settings
   • Integration - Template for integrating into your app
   • Tkinter GUI - Desktop app with custom UI (no dependencies!)
   • Tkinter Advanced - Multi-tab desktop app with styling

3. Name Your File - Get ready-to-run code!

GUI Templates Preview:

Tkinter Desktop GUI:

# Auto-generated code with:
# - Beautiful custom styling
# - Real-time chat interface
# - Threaded operations
# - Native desktop app
# - NO extra dependencies!

Run with:

python your_app.py
# Window opens immediately!

Tkinter Advanced:

# Auto-generated code with:
# - Multiple tabs (Chat, Generate, Settings)
# - Professional dark theme
# - Parameter controls
# - Content generation tools
# - Production-ready

Want web/API? Use the Integration template and add Flask/FastAPI/whatever you prefer!

No Models Installed?

No problem! The wizard will:

1. Detect you have no models
2. Show you recommended models with sizes
3. Install the model for you interactively
4. Generate your template ready to use!

Starter Templates

Ready-to-use templates for common applications:

1. Chatbot

cd templates/chatbot
python simple_chatbot.py

A complete chatbot with conversation history and commands.

2. RAG System

cd templates/rag_system
python simple_rag.py

Retrieval Augmented Generation for question-answering with custom knowledge.

3. Text Analyzer

cd templates/text_analyzer
python text_analyzer.py

Analyze text for sentiment, keywords, entities, and more.

4. Code Assistant

cd templates/code_assistant
python code_assistant.py

AI-powered coding assistant for generation, debugging, and review.

API Reference

OllamaClient

Main client for interacting with Ollama:

client = OllamaClient(host="http://localhost:11434")

# Generate text
response = client.generate(model, prompt, system=None, temperature=0.7)

# Stream generation
for chunk in client.stream_generate(model, prompt):
    print(chunk)

# Chat completion
response = client.chat(model, messages, temperature=0.7)

# Stream chat
for chunk in client.stream_chat(model, messages):
    print(chunk)

# Generate embeddings
embedding = client.embeddings(model, text)

# Check if running
is_running = client.is_running()

ChatSession

Maintain conversation context with automatic response processing:

session = ChatSession(
    model="llama2",
    system_message="You are helpful",
    temperature=0.7,
    max_history=50,
    auto_process=True  # Automatically handle different model formats
)

# Send message (automatically cleaned!)
response = session.send("Hello")

# Stream message
for chunk in session.send_stream("Tell me more"):
    print(chunk)

# Access thinking/reasoning (if available)
thinking = session.get_last_thinking()
metadata = session.get_last_metadata()

# Clear history
session.clear_history()

# Get history
history = session.get_history()

# Export/import
session.export_history("chat.json")
session.load_history("chat.json")

Response Handlers

Handle different model formats automatically:

from otk import (
    AutoModelHandler,
    ModelResponseHandler,
    ModelType,
    clean_thinking_tags
)

# Automatic handler (detects model type)
auto_handler = AutoModelHandler()
processed = auto_handler.process_response(raw_text, "deepseek-r1")

# Manual handler for specific type
handler = ModelResponseHandler(ModelType.THINKING)
processed = handler.process(raw_text)

# Quick utility functions
clean_text, thinking = clean_thinking_tags(response)

# Custom patterns
custom_handler = ModelResponseHandler(
    ModelType.CUSTOM,
    custom_patterns={'tag': r'<tag>(.*?)</tag>'}
)

session.load_history("chat.json")

### ModelManager

Manage Ollama models:

```python
manager = ModelManager()

# List models
models = manager.list_models()

# Pull model
manager.pull_model("llama2", stream=True)

# Delete model
manager.delete_model("old-model")

# Check existence
exists = manager.model_exists("llama2")

# Get model info
info = manager.show_model_info("llama2")

# Get recommendations
recommendations = manager.recommend_models()

Utility Functions

from otk import (
    format_response,
    estimate_tokens,
    chunk_text,
    create_prompt_template,
    extract_code_blocks,
    clean_response
)

# Format for readability
formatted = format_response(long_text, max_width=80)

# Estimate tokens
tokens = estimate_tokens(text)

# Chunk text
chunks = chunk_text(text, chunk_size=1000, overlap=100)

# Use templates
prompt = create_prompt_template(
    "Translate {text} to {language}",
    {"text": "Hello", "language": "Spanish"}
)

# Extract code
code_blocks = extract_code_blocks(markdown_text)

Recommended Models

General Chat

• llama2 - Meta's general-purpose model
• mistral - Fast and capable
• phi - Small but powerful

Coding

• codellama - Code generation and explanation
• deepseek-coder - Excellent for code
• starcoder2 - Strong coding capabilities

Embeddings

• nomic-embed-text - Text embeddings
• all-minilm - Lightweight embeddings

Pull models with:

ollama pull llama2
ollama pull codellama
ollama pull nomic-embed-text

Examples

See examples/ directory for working code samples.

Templates

Ready-to-use application templates in templates/.

Testing

python test_quick.py

Test Features

from otk import clean_thinking_tags, ModelBuilder

clean, thinking = clean_thinking_tags("<think>x</think>answer")

model = ModelBuilder("llama2").with_temperature(0.8).build()

Troubleshooting

Issue: 'otk' command not recognized (after pip install)

This happens when Python's Scripts directory is not in your system PATH.

# Quick Fix - Use Python module (always works, no PATH needed):
python -m otk

# Check if it's working:
python -m otk --version

# Permanent Fix - Add Scripts to PATH:

# Step 1: Find your Python Scripts directory
python -c "import sys, os; print(os.path.join(sys.prefix, 'Scripts'))"

# Step 2: Add to PATH (Windows PowerShell as Administrator):
$scriptsPath = python -c "import sys, os; print(os.path.join(sys.prefix, 'Scripts'))"
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$scriptsPath", "User")

# Step 3: Restart your terminal and try:
otk

# Alternative: Install with pipx (manages PATH automatically)
pip install pipx
pipx install open-otk
otk  # Now works!

Manual PATH Setup (Windows):

1. Search "Environment Variables" in Start menu
2. Click "Environment Variables" button
3. Under "User variables", select "Path" and click "Edit"
4. Click "New" and add: C:\Users\<YourUsername>\AppData\Local\Programs\Python\Python3X\Scripts
5. Click "OK" on all windows
6. Restart your terminal/Command Prompt
7. Run otk

Issue: Ollama not running

# Solution: Make sure Ollama is running
# Windows: Start Ollama app
# Linux/Mac: ollama serve

Issue: Model not found

# Solution: Pull the model
ollama pull llama2

# Or list available models
ollama list

Issue: Import errors

# Solution: Install dependencies
pip install ollama

# Or install from requirements
pip install -r requirements.txt

Full Testing Guide: TESTING_GUIDE.md

Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest features
• Submit pull requests
• Improve documentation

License

MIT License - feel free to use in your projects!

Acknowledgments

• Built on top of Ollama
• Uses the official ollama-python library

Documentation

• Getting Started Guide
• GUI Documentation
• API Reference

Contributing

Contributions welcome! Open an issue or submit a pull request.

License

MIT License - see LICENSE for details.

Author

Md. Abid Hasan Rafi

• Email: [e-mail]
• GitHub: @abidhasanrafi
• Portfolio: abidhasanrafi.github.io
• Organization: AI Extension

Links

• OTK Website
• Project Repository
• Report Issues
• Ollama Documentation