docs/README_GPT_OSS.md

GPT-OSS - Open Source ChatGPT Alternative

A powerful open-source alternative to ChatGPT with advanced reasoning capabilities, integrated browser tools, and Python code execution — all running locally on Ollama.

🚀 Quick Start

# Pull and run the model
ollama pull Raiff1982/gpt-oss
ollama run Raiff1982/gpt-oss

🎯 What Makes This Model Special?

GPT-OSS provides a feature-complete ChatGPT experience with:

• 🧠 Multi-Level Reasoning - Built-in analysis channels for deep thinking
• 🌐 Browser Integration - Search, open, and find information on the web
• 🐍 Python Execution - Run Python code in a stateful Jupyter environment
• 🔧 Tool Calling - Extensible function calling framework
• 📊 Data Persistence - Save and load files to /mnt/data
• 💭 Chain of Thought - Transparent reasoning with configurable depth

🛠️ Core Features

Reasoning Channels

The model operates across multiple channels for structured thinking:

analysis     → Internal reasoning and tool usage (Python, browser)
commentary   → Function calls and external tool integration
final        → User-facing responses and conclusions

This architecture enables:

• Transparent reasoning - See how the model thinks
• Tool integration - Seamlessly use Python/browser without breaking flow
• Clean output - Separate internal work from final answers

Browser Tools

Built-in web browsing capabilities:

# Search the web
browser.search(query="latest AI research", topn=10)

# Open specific results
browser.open(id=3, loc=0, num_lines=50)

# Find text on page
browser.find(pattern="neural networks")

Use cases:

• Research current events and news
• Find technical documentation
• Verify facts and statistics
• Compare information across sources

Python Code Execution

Stateful Jupyter notebook environment:

# Execute code directly
import pandas as pd
import matplotlib.pyplot as plt

# Load and analyze data
df = pd.read_csv('/mnt/data/data.csv')
df.describe()

# Create visualizations
plt.plot(df['x'], df['y'])
plt.savefig('/mnt/data/plot.png')

Capabilities:

• Full Python standard library
• Data analysis (pandas, numpy)
• Visualization (matplotlib, seaborn)
• Machine learning (scikit-learn)
• File persistence in /mnt/data
• 120 second execution timeout

Reasoning Levels

Control analysis depth with reasoning parameters:

low     → Quick, intuitive responses
medium  → Balanced thinking (default)
high    → Deep, thorough analysis

🎨 Example Use Cases

Research Assistant

> What are the latest developments in quantum computing?

[Model searches web, analyzes multiple sources, synthesizes findings]
[Cites sources with: 【6†L9-L11】 format]
[Provides comprehensive summary with references]

Data Analysis

> Analyze this CSV and find correlations

[Loads data with pandas]
[Performs statistical analysis]
[Creates visualization]
[Explains insights and patterns]

Code Generation & Debugging

> Help me debug this Python function

[Analyzes code structure]
[Tests in Python environment]
[Identifies issues]
[Provides corrected version with explanation]

Multi-Step Problem Solving

> Plan a trip to Tokyo for 5 days under $2000

[Searches flight prices]
[Finds accommodation options]
[Researches local costs]
[Creates detailed itinerary with budget breakdown]

⚙️ Technical Specifications

• Size: ~13 GB
• Context Window: 8192+ tokens
• Temperature: 1.0 (balanced creativity)
• Knowledge Cutoff: June 2024
• License: Apache 2.0

System Architecture

User Query
    ↓
System Prompt (ChatGPT identity, tool definitions)
    ↓
Analysis Channel (reasoning, Python, browser tools)
    ↓
Commentary Channel (function calls)
    ↓
Final Channel (user-facing response)

🔧 Advanced Usage

Custom System Instructions

Extend the model with additional context:

ollama run Raiff1982/gpt-oss "You are now a specialized Python tutor..."

Function Calling

Define custom functions the model can call:

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {"type": "string"},
      "units": {"type": "string", "enum": ["celsius", "fahrenheit"]}
    }
  }
}

API Integration

Use with Ollama's API for programmatic access:

import ollama

response = ollama.chat(
    model='Raiff1982/gpt-oss',
    messages=[
        {
            'role': 'user',
            'content': 'Write a Python script to analyze CSV data'
        }
    ],
    tools=[
        {
            'type': 'function',
            'function': {
                'name': 'python',
                'description': 'Execute Python code'
            }
        }
    ]
)

print(response['message']['content'])

Streaming Responses

Get real-time output for long responses:

stream = ollama.chat(
    model='Raiff1982/gpt-oss',
    messages=[{'role': 'user', 'content': 'Explain quantum mechanics'}],
    stream=True
)

for chunk in stream:
    print(chunk['message']['content'], end='', flush=True)

🧪 Example Interactions

Web Research with Citations

User: What caused the 2024 stock market volatility?

Assistant (analysis): *searches financial news*
Assistant (analysis): *opens top 3 results*
Assistant (analysis): *extracts key information*

Assistant (final): Based on recent financial reports【4†L12-L15】【7†L8】:
1. Federal interest rate changes in Q1 2024
2. Tech sector corrections【4†L23】
3. Geopolitical tensions affecting energy markets【9†L5-L9】

The primary driver was...

Python Data Analysis

User: Load sales_data.csv and show me the top 5 products

Assistant (analysis):
```python
import pandas as pd
df = pd.read_csv('/mnt/data/sales_data.csv')
top_5 = df.groupby('product')['revenue'].sum().sort_values(ascending=False).head(5)
print(top_5)

Assistant (final): Here are your top 5 products by revenue:

1. Product A: $45,230
2. Product B: $38,920 ...

### Complex Reasoning

User: Should I invest in renewable energy stocks?

Assistant (analysis): thinking deeply

• Market trends analysis
• Policy impact assessment
• Risk evaluation
• Timeline considerations

Assistant (final): I'll break this down across several dimensions:

Market Analysis [searches recent data]

• Solar industry growth rate: 15% YoY【3†L45】
• Wind energy investments up 23%【5†L12-L14】

Policy Environment [Considers regulatory landscape, incentives, risks]

Personal Recommendation Based on your [risk tolerance/timeline/goals]...

## 📊 Capabilities Matrix

| Feature | Supported | Notes |
|---------|-----------|-------|
| Web Search | ✅ | Real-time information retrieval |
| Web Browsing | ✅ | Open and parse URLs |
| Python Execution | ✅ | Stateful Jupyter environment |
| Code Generation | ✅ | Multiple languages |
| Data Analysis | ✅ | Pandas, NumPy, visualization |
| File Persistence | ✅ | `/mnt/data` directory |
| Function Calling | ✅ | Extensible tool framework |
| Multi-Step Reasoning | ✅ | Chain of thought |
| Streaming | ✅ | Real-time output |
| Citations | ✅ | Source tracking with line numbers |

## 🔒 Privacy & Safety

**Local Execution Benefits:**
- All processing happens on your machine
- No data sent to external APIs (except browser tools)
- Full control over tool usage
- Inspect code before execution

**Browser Tool Considerations:**
- Browser tools do make external web requests
- Review URLs and search queries before execution
- Content fetched is processed locally

**Python Execution Safety:**
- Sandboxed environment with 120s timeout
- File access limited to `/mnt/data`
- No network access from Python by default
- Review generated code before running

## 🚦 Best Practices

### Effective Prompting

❌ Vague: "Tell me about AI" ✅ Specific: "Search for recent breakthroughs in transformer architecture from 2024, then summarize the top 3 findings"

❌ Too broad: "Analyze my data" ✅ Actionable: "Load sales.csv, calculate monthly revenue trends, and create a line plot showing growth over time"

### Tool Usage
- **Search first** - Use browser before asking knowledge questions
- **Verify with code** - Use Python to validate calculations
- **Cite sources** - Pay attention to citation numbers
- **Check dates** - Knowledge cutoff is June 2024

### Reasoning Control
```bash
# Quick responses
ollama run Raiff1982/gpt-oss --reasoning low "Quick question..."

# Deep analysis
ollama run Raiff1982/gpt-oss --reasoning high "Complex problem..."

🆚 GPT-OSS vs. Other Models

Feature	GPT-OSS	Standard LLMs	ChatGPT Plus
Cost	Free (local)	Free/Varies	$20/month
Privacy	Full privacy	Varies	Data processed externally
Tools	Browser + Python	None	Browser + Python + DALL-E
Reasoning	Transparent	Hidden	Partial transparency
Customization	Full control	Limited	Limited
Offline	After download	Varies	No

🔄 Updates & Versioning

This model is actively maintained:

• Base architecture follows ChatGPT design patterns
• Tools and capabilities updated regularly
• Community contributions welcome

📚 Related Resources

• Ollama Documentation
• Function Calling Guide
• Python Environment Details
• Apache License 2.0

🤝 Contributing

Help improve GPT-OSS:

1. Report issues with tool usage
2. Share effective prompting strategies
3. Contribute function definitions
4. Document use cases and examples

💡 Tips & Tricks

Multi-Step Workflows

> First, search for "Python data visualization libraries 2024"
> Then, use Python to create example plots with the top 3 libraries
> Finally, compare their strengths and weaknesses

Data Pipeline

> Load my CSV from /mnt/data/raw.csv
> Clean the data (handle missing values, outliers)
> Create summary statistics
> Save cleaned data to /mnt/data/processed.csv
> Generate a report with key findings

Research & Writing

> Research the history of neural networks (search 5 sources)
> Outline a 1000-word article based on findings
> Draft section 1 with proper citations
> Review and refine for clarity

🏆 Acknowledgments

• OpenAI - ChatGPT architecture inspiration
• Ollama Team - Local model runtime
• Open Source Community - Tool integrations and feedback

---

Model Page: https://ollama.com/Raiff1982/gpt-oss
Created: December 27, 2025
Size: 13 GB
License: Apache 2.0

"Open source intelligence with the power of ChatGPT, privacy of local execution, and freedom of customization."