Add README_GPT_OSS.md

docs/README_GPT_OSS.md

@@ -0,0 +1,426 @@
+# 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."*