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

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

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

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

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

### Function Calling

Define custom functions the model can call:

```json
{
  "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:

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

```python
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](https://ollama.ai/docs)
- [Function Calling Guide](https://github.com/ollama/ollama/blob/main/docs/api.md#tools)
- [Python Environment Details](https://jupyter.org/)
- [Apache License 2.0](http://www.apache.org/licenses/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."*