open-otk 1.0.0

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

Open OTK (Open Ollama Toolkit)

A professional Python toolkit for building AI-powered applications with Ollama models.

Developed by: Md. Abid Hasan Rafi | AI Extension

---

Overview

Open OTK is a complete development toolkit for building production-ready AI applications with Ollama models. Whether you're creating CLI tools, desktop applications, or complex integrations, Open OTK provides the professional foundation you need.

Key Features

• Rapid Development - Visual GUI creates working applications in seconds
• Full Control - Comprehensive hooks, callbacks, and customization options
• Professional Tools - Visual model browser, template generator, management suite
• Production Ready - Clean architecture, proper error handling, best practices
• Universal Compatibility - Works with all Ollama models automatically
• Minimal Dependencies - Lightweight with pure Python implementation

---

Getting Started

Quick Installation

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

# 2. Install Open OTK
pip install -e ".[scraper]"

# 3. Launch from anywhere
otk

Manual Launch

If you prefer not to install as a package:

python otk.py

What's Included:

• Model Browser - Discover and install models from ollama.com
• Model Manager - Visual interface for installed model management
• Template Generator - Create starter applications with intuitive interface
• Modern Design - Professional GitHub Dark theme
• Responsive Layout - Adapts to any screen size
• Instant Code Generation - Working Python applications in seconds

Full GUI Documentation

---

Why Choose Open OTK?

Open OTK is designed as a professional development toolkit, not just another chat wrapper.

Use Cases:

• Application Development - Integrate LLM capabilities into Python projects
• Custom Solutions - Full customization with hooks and callbacks
• Experimentation - Compare models, test configurations, benchmark performance
• Production Integration - Build robust tools and services
• Rapid Prototyping - Quick template generation for any use case

Core Features

• Auto-Detection - Automatically works with any installed Ollama model
• Smart Chat Sessions - Context management with intelligent response handling
• Response Processing - Handles thinking tags, code blocks, and various formats
• Customization System - Hooks, callbacks, presets, and builders for full control
• Experimentation Tools - Compare, benchmark, and A/B test different models
• GUI Generator - Create Tkinter desktop applications instantly
• Model Management - List, install, and manage models with ease
• Embeddings Support - Generate and work with text embeddings
• Streaming Responses - Real-time response streaming capabilities
• Integration Examples - Real-world use cases and patterns
• Zero Configuration - Works immediately after Ollama installation

Prerequisites

1. Ollama Installation - Download from ollama.ai
2. Model Selection - Install your preferred model:
   • ollama pull qwen2:0.5b (small, 352 MB)
   • ollama pull deepseek-r1:1.5b (coding-focused, 1.1 GB)
   • ollama pull llama2 (general purpose)
   • Or any other available model
3. Ollama Service - Ensure Ollama is running

Installation

Step 1: Install Ollama

Download and install from ollama.ai

Step 2: Install a Model

# Choose one or more:
ollama pull llama2           # General purpose
ollama pull mistral          # Fast and capable
ollama pull deepseek-r1:1.5b # Reasoning-focused
ollama pull qwen2:0.5b       # Lightweight

Step 3: Install Open OTK

Recommended: Install as a package (run from anywhere)

# Clone or download Open OTK
cd open-otk

# Install in development mode
pip install -e .

# Or install with all features
pip install -e ".[scraper]"

After installation, you can run otk from anywhere on your system!

Alternative: Manual dependencies

# Core dependencies only
pip install ollama

# Optional: Web scraper for GUI model browser
pip install requests beautifulsoup4

Complete Installation Guide →

Step 4: Launch Open OTK

If installed as package:

otk

Run from anywhere - no need to navigate to installation directory!

If running directly:

cd open-otk
python otk.py

Or test programmatically:

from otk import OllamaClient

client = OllamaClient()
print(client.generate("llama2", "Say hello!"))

Try included examples:

python quickstart.py              # Feature demonstration
python examples/simple_chat.py    # Interactive chat

Detailed Setup Guide

Quick Start Examples

Simple Generation

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 Handling

The library automatically handles different model response formats.

Works with Thinking Models (DeepSeek-R1, Qwen with reasoning):

from otk import ChatSession

# Automatically cleans <think> tags and extracts reasoning
session = ChatSession("deepseek-r1:8b", auto_process=True)
response = session.send("Solve 234 + 567")

print(response)  # Clean answer without thinking tags!

# Access the thinking process
thinking = session.get_last_thinking()
if thinking:
    print(f"Model used {len(thinking)} reasoning steps")

Quick Manual Cleaning:

from otk import clean_thinking_tags, auto_clean_response

# Clean any response with thinking tags
clean_text, thinking = clean_thinking_tags(raw_response)

# Auto-detect model type and clean
clean_text = auto_clean_response(raw_response, "deepseek-r1")

Custom Response Handlers:

from otk import ModelResponseHandler, ModelType

# Create handler for models with special formats
handler = ModelResponseHandler(ModelType.THINKING)
processed = handler.process(raw_response)

print(processed.content)  # Clean content
print(processed.thinking)  # Extracted reasoning
print(processed.metadata)  # Additional info

Full Customization & Integration

Build custom AI-powered tools:

from otk import ModelBuilder, HookType, ModelPresets

# Build a fully customized model
model = (ModelBuilder("llama2")
         .with_preset("creative")      # Use preset config
         .with_temperature(0.85)        # Fine-tune
         .with_hook(HookType.POST_PROCESS, my_logger)  # Add logging
         .with_post_processor(my_formatter)            # Custom formatting
         .build())

# Or create custom processors
def add_branding(text):
    return f"{text}\n\n— Powered by MyApp"

model.set_post_processor(add_branding)

Experimentation Tools:

from otk import ModelExperiment, ModelPlayground

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

# Try different temperatures
playground = ModelPlayground()
playground.try_temperatures("llama2", "Write a story")

# Benchmark performance
stats = experiment.benchmark("llama2", "What is Python?", iterations=10)

Integration Examples:

from otk import CustomizableModel

# Blog post generator
class BlogWriter:
    def __init__(self):
        self.model = CustomizableModel("llama2")
        self.model.set_post_processor(self._format_html)
    
    def _format_html(self, text):
        return f"<article>{text}</article>"
    
    def write(self, topic):
        return self.model.generate(f"Write about: {topic}")

# Smart data processor
class SmartCategorizer:
    def categorize(self, text, categories):
        prompt = f"Categorize '{text}' into: {', '.join(categories)}"
        return self.model.generate(prompt, temperature=0.2)

Learn More: Check CUSTOMIZATION_GUIDE.md for full customization docs!

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

Use Cases & Integration Ideas

What You Can Build:

• Data Processing Pipelines - Categorize, extract, transform data with AI
• Dev Tools - Code reviewers, documentation generators, debug assistants
• Content Systems - Auto-generate blogs, summaries, social media posts
• Creative Tools - Story generators, idea brainstormers, writing assistants
• Smart Bots - Custom chatbots with personalities and specific knowledge
• Knowledge Systems - RAG, Q&A systems with custom documents
• Search & Categorization - Smart categorizers, semantic search engines
• Learning Tools - Interactive tutors, quiz generators, explainers
• Research Tools - Experiment runners, model comparers, benchmarkers
• API Services - Build AI-powered APIs and microservices

See Real Examples: Check creative_integrations.py for working code!

� Testing & Verification

Quick Test

# Run quick test (checks imports, handlers, connection)
python test_quick.py

Full Verification

# Comprehensive verification (all features)
python verify_setup.py

Test Specific Features

# Test response handling
from otk import clean_thinking_tags
clean, thinking = clean_thinking_tags("<think>x</think>answer")

# Test customization
from otk import ModelBuilder
model = (ModelBuilder("llama2")
         .with_temperature(0.8)
         .build())

# Test experimentation
from otk import ModelExperiment
experiment = ModelExperiment()
experiment.run_single("llama2", "Test prompt")

Interactive Testing

# Best way to explore and test
python examples/experimentation_playground.py

Troubleshooting

Issue: Cannot connect to Ollama

# 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

Support

• Ollama Documentation
• Ollama Discord
• Report Issues

Roadmap

• GUI Template Generator with model browser
• Modern design system
• Async support for concurrent requests
• Multi-modal support (images, audio)
• Model benchmarking suite
• Plugin system for extensions
• Web-based UI alternative

---

Documentation

Getting Started

• Getting Started Guide - Complete beginner's guide
• Customization Guide - Advanced customization
• Testing Guide - How to test your setup

GUI Application

• GUI App Documentation - Visual interface guide
• Modern Design Guide - UI/UX principles
• GUI Enhancements - Feature improvements

Reference

• Quick Reference - API cheat sheet
• Library Philosophy - Design principles
• What's New - Changelog and updates

---

Contributing

Contributions are welcome! Open OTK is built for the community.

Ways to contribute:

• Report bugs and issues
• Suggest new features
• Improve documentation
• Submit pull requests
• Star the project

License

MIT License - Free to use in personal and commercial projects.

See LICENSE for full details.

---

Author

Md. Abid Hasan Rafi
AI Extension

• GitHub: @AI-Extension
• Project: Open OTK

Acknowledgments

• Built on Ollama - Local LLM runtime
• Uses ollama-python - Official Python client
• Inspired by the open-source AI community

Support & Resources

• Ollama Documentation
• Ollama Discord Community
• Report Issues
• Star on GitHub

---

Open OTK (Open Ollama Toolkit)
Professional AI Development Made Simple

Developed by Md. Abid Hasan Rafi | AI Extension