Metadata-Version: 2.4
Name: open-otk
Version: 1.0.0
Summary: Open Ollama Toolkit - Professional Python library for building AI applications with Ollama
Home-page: https://github.com/aiextension/open-otk
Author: Md. Abid Hasan Rafi
Author-email: ai.extension@outlook.com
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ollama>=0.1.0
Provides-Extra: scraper
Requires-Dist: requests>=2.31.0; extra == "scraper"
Requires-Dist: beautifulsoup4>=4.12.0; extra == "scraper"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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](https://github.com/AI-Extension)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

---

## 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

```bash
# 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:

```bash
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](docs/gui/GUI_APP_README.md)

---

## 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](https://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](https://ollama.ai)

### Step 2: Install a Model

```bash
# 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)**
```bash
# 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**
```bash
# Core dependencies only
pip install ollama

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

[**Complete Installation Guide →**](INSTALL.md)

### Step 4: Launch Open OTK

**If installed as package:**
```bash
otk
```
Run from anywhere - no need to navigate to installation directory!

**If running directly:**
```bash
cd open-otk
python otk.py
```

**Or test programmatically:**
```python
from otk import OllamaClient

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

**Try included examples:**
```bash
python quickstart.py              # Feature demonstration
python examples/simple_chat.py    # Interactive chat
```

[Detailed Setup Guide](docs/guides/GETTING_STARTED.md)

## Quick Start Examples

### Simple Generation

```python
from otk import OllamaClient

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

### Chat Session

```python
from otk import ChatSession

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

### Streaming Responses

```python
from otk import OllamaClient

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

### Model Management

```python
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):
```python
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**:
```python
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**:
```python
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:**

```python
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:**

```python
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:**

```python
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](CUSTOMIZATION_GUIDE.md) for full customization docs!

## Examples

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

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

Run any example:
```bash
python examples/simple_chat.py
```

## Generate Your Starter Template (Interactive)

**NEW! Create custom templates with a beautiful interactive wizard:**

```bash
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:**
```python
# Auto-generated code with:
# - Beautiful custom styling
# - Real-time chat interface
# - Threaded operations
# - Native desktop app
# - NO extra dependencies!
```

**Run with:**
```bash
python your_app.py
# Window opens immediately!
```

**Tkinter Advanced:**
```python
# 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
```bash
cd templates/chatbot
python simple_chatbot.py
```
A complete chatbot with conversation history and commands.

### 2. RAG System
```bash
cd templates/rag_system
python simple_rag.py
```
Retrieval Augmented Generation for question-answering with custom knowledge.

### 3. Text Analyzer
```bash
cd templates/text_analyzer
python text_analyzer.py
```
Analyze text for sentiment, keywords, entities, and more.

### 4. Code Assistant
```bash
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:

```python
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:

```python
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:

```python
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

```python
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:
```bash
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](examples/creative_integrations.py) for working code!

## � Testing & Verification

### Quick Test

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

### Full Verification

```bash
# Comprehensive verification (all features)
python verify_setup.py
```

### Test Specific Features

```python
# 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

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

### Troubleshooting

**Issue: Cannot connect to Ollama**
```bash
# Solution: Make sure Ollama is running
# Windows: Start Ollama app
# Linux/Mac: ollama serve
```

**Issue: Model not found**
```bash
# Solution: Pull the model
ollama pull llama2

# Or list available models
ollama list
```

**Issue: Import errors**
```bash
# Solution: Install dependencies
pip install ollama

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

**Full Testing Guide:** [TESTING_GUIDE.md](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](https://ollama.ai)
- Uses the official [ollama-python](https://github.com/ollama/ollama-python) library

## Support

- [Ollama Documentation](https://github.com/ollama/ollama/blob/main/docs/README.md)
- [Ollama Discord](https://discord.gg/ollama)
- [Report Issues](https://github.com/yourusername/ollama-toolkit/issues)

## Roadmap

- [x] GUI Template Generator with model browser
- [x] 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](docs/guides/GETTING_STARTED.md) - Complete beginner's guide
- [Customization Guide](docs/guides/CUSTOMIZATION_GUIDE.md) - Advanced customization
- [Testing Guide](docs/guides/TESTING_GUIDE.md) - How to test your setup

### GUI Application
- [GUI App Documentation](docs/gui/GUI_APP_README.md) - Visual interface guide
- [Modern Design Guide](docs/gui/MODERN_DESIGN_GUIDE.md) - UI/UX principles
- [GUI Enhancements](docs/gui/GUI_ENHANCEMENTS.md) - Feature improvements

### Reference
- [Quick Reference](docs/reference/QUICK_REFERENCE.md) - API cheat sheet
- [Library Philosophy](docs/reference/LIBRARY_PHILOSOPHY.md) - Design principles
- [What's New](docs/reference/WHATS_NEW.md) - 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](LICENSE) for full details.

---

## Author

**Md. Abid Hasan Rafi**  
AI Extension

- GitHub: [@AI-Extension](https://github.com/AI-Extension)
- Project: [Open OTK](https://github.com/aiextension/open-otk)

## Acknowledgments

- Built on [Ollama](https://ollama.ai) - Local LLM runtime
- Uses [ollama-python](https://github.com/ollama/ollama-python) - Official Python client
- Inspired by the open-source AI community

## Support & Resources

- [Ollama Documentation](https://github.com/ollama/ollama/blob/main/docs/README.md)
- [Ollama Discord Community](https://discord.gg/ollama)
- [Report Issues](https://github.com/aiextension/open-otk/issues)
- [Star on GitHub](https://github.com/aiextension/open-otk)

---

<div align="center">

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

Developed by **Md. Abid Hasan Rafi** | [AI Extension](https://github.com/AI-Extension)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

</div>
