thonny-codemate 0.1.0__tar.gz

thonny_codemate-0.1.0/CLAUDE.md

@@ -0,0 +1,169 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Thonny IDE plugin that integrates local LLM capabilities using llama-cpp-python (not Ollama server) to provide GitHub Copilot-like features. The plugin will:
+- Load GGUF models directly using llama-cpp-python when Thonny starts
+- Provide code generation and explanation based on user instructions
+- Support context-aware coding with multiple file understanding
+- Include a portable USB deployment option
+
+## AI向けドキュメント
+
+`docs_for_ai/*.md` はAI向けのドキュメントです。AIがこのプロジェクトを理解しやすくするために、プロジェクトの目的・ゴールの情報が含まれています。
+
+また、AIは作業を開始する前に`docs_for_ai/todo.md` を参照し、タスクを確認してください。
+新たなタスクが発生した場合は、このファイルに追加してください。
+タスクが完了したら、 `docs_for_ai/todo.md` の該当箇所を完了のステータスにしてください。i had
+
+`README.md` を更新した場合は `README.ja.md` も日本語で更新してください。
+
+## Project Goals
+
+1. **Core Functionality**
+   - Direct GGUF model loading via llama-cpp-python (no Ollama server)
+   - Automatic model loading on Thonny startup
+   - Agentic coding with multi-file context understanding
+   - Code generation based on user instructions
+
+2. **User Features**
+   - Text selection in editor → context-aware Q&A with LLM
+   - "Code Explanation" context menu for selected text
+   - User skill level selection for appropriate responses
+   - Optional support for ChatGPT/Ollama/OpenRouter servers
+
+3. **Distribution**
+   - PyPI package: `pip install thonny-codemate`
+   - USB portable version with Thonny + plugin + models bundled
+
+## Project Structure
+
+```
+thonny-codemate/
+├── docs_for_ai/
+│   └── project_goal.md    # Detailed project requirements
+├── pyproject.toml         # Package configuration
+├── README.md
+├── thonnycontrib/
+│   └── thonny_codemate/
+│       ├── __init__.py    # load_plugin() implementation
+│       ├── llm_client.py  # llama-cpp-python wrapper
+│       ├── ui_widgets.py  # Thonny UI components
+│       └── config.py      # Configuration management
+├── models/                # GGUF model storage
+├── tests/                 # Unit tests
+└── CLAUDE.md             # This file
+```
+
+## Development Setup
+
+### Virtual Environment Setup
+```bash
+python -m venv .venv
+# Windows:
+.venv\Scripts\activate
+# macOS/Linux:
+source .venv/bin/activate
+pip install -U pip
+```
+
+### Install Dependencies
+```bash
+# Install llama-cpp-python (CPU version)
+pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
+
+# For CUDA support:
+pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124
+
+# Install Thonny for development
+git clone https://github.com/thonny/thonny.git
+pip install -e ./thonny
+
+# Install plugin in editable mode
+pip install -e .
+```
+
+### Download GGUF Models
+```bash
+pip install -U "huggingface_hub[cli]"
+huggingface-cli download TheBloke/Llama-3-8B-GGUF llama3-8b.Q4_K_M.gguf --local-dir ./models
+```
+
+## Common Commands
+
+```bash
+# Run Thonny with plugin
+python -m thonny
+
+# Debug mode with debugpy
+python -m debugpy --listen 5678 --wait-for-client -m thonny
+
+# Run tests
+pytest -v
+
+# Build package
+python -m build
+
+# Quick restart workflow
+# Ctrl+Q → Enter → ↑ → Enter
+```
+
+## Architecture
+
+### Core Components
+
+1. **LLM Client Module** (`llm_client.py`)
+   - Wraps llama-cpp-python for GGUF model loading
+   - Manages model lifecycle and memory
+   - Handles chat formatting and context management
+
+2. **UI Integration** (`ui_widgets.py`)
+   - Context menu for "Code Explanation"
+   - Assistant panel for interactive Q&A
+   - Progress indicators for model loading
+
+3. **Configuration** (`config.py`)
+   - Model path and selection
+   - User skill level settings
+   - Optional API endpoints for external services
+
+### Key Implementation Details
+
+```python
+# Plugin entry point in __init__.py
+def load_plugin():
+    from thonny import get_workbench
+    from .llm_client import LLMClient
+    from .ui_widgets import AssistantView
+    
+    # Initialize LLM on startup
+    client = LLMClient()
+    client.load_model_async()
+    
+    # Add UI components
+    get_workbench().add_view(AssistantView, "Assistant", "se")
+```
+
+## Development Notes
+
+### Debugging Tips
+- Use `logging` module - output goes to System Shell
+- Check `thonny.log` in Thonny data folder for detailed logs
+- VS Code/PyCharm remote debugging via debugpy is most efficient
+
+### Performance Considerations
+- Load models asynchronously to avoid blocking UI
+- Use threading for LLM inference
+- Cache model in memory between sessions if possible
+
+### Testing Strategy
+- Mock `thonny.get_workbench()` for unit tests
+- Test model loading separately from UI
+- Include integration tests with small GGUF models
+
+### Portability Requirements
+- Bundle all dependencies for USB deployment
+- Use relative paths for model files
+- Include platform-specific llama-cpp-python wheels

thonny_codemate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 tokoroten
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

thonny_codemate-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md
+include README.ja.md
+include LICENSE
+include pyproject.toml
+include CLAUDE.md
+recursive-include thonnycontrib *.py
+recursive-include docs_for_ai *.md
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .DS_Store
+recursive-exclude models *
+recursive-exclude .venv *
+recursive-exclude tests *

thonny_codemate-0.1.0/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: thonny-codemate
+Version: 0.1.0
+Summary: A Thonny IDE plugin that provides AI-powered coding assistance using local and cloud LLMs
+Author-email: tokoroten <shinta.nakayama@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/tokoroten/thonny-codemate
+Project-URL: Repository, https://github.com/tokoroten/thonny-codemate
+Project-URL: Issues, https://github.com/tokoroten/thonny-codemate/issues
+Keywords: thonny,plugin,llm,ai,code-assistant,education
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: thonny>=4.0.0
+Requires-Dist: huggingface-hub[hf_xet]>=0.16.0
+Requires-Dist: tkinterweb[javascript]>=3.24
+Requires-Dist: pythonmonkey>=0.2.0
+Requires-Dist: markdown>=3.5
+Requires-Dist: pygments>=2.17
+Requires-Dist: llama-cpp-python>=0.3.9
+Provides-Extra: cuda
+Provides-Extra: metal
+Provides-Extra: external-only
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: debugpy>=1.6; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: llama-cpp-python>=0.3.9; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0; extra == "test"
+Requires-Dist: pytest-mock>=3.10.0; extra == "test"
+Dynamic: license-file
+
+# Thonny Local LLM Plugin
+
+A Thonny IDE plugin that integrates local LLM capabilities using llama-cpp-python to provide GitHub Copilot-like features without requiring external API services.
+
+![image](https://github.com/user-attachments/assets/af94b175-bcc1-4e44-bbed-37402ee2850f)
+
+## Features
+
+- 🤖 **Local LLM Integration**: Uses llama-cpp-python to load GGUF models directly (no Ollama server required)
+- 🚀 **On-Demand Model Loading**: Models are loaded on first use (not at startup) to avoid slow startup times
+- 📝 **Code Generation**: Generate code based on natural language instructions
+- 💡 **Code Explanation**: Select code and get AI-powered explanations via context menu
+- 🎯 **Context-Aware**: Understands multiple files and project context
+- 💬 **Conversation Memory**: Maintains conversation history for contextual responses
+- 🎚️ **Skill Level Adaptation**: Adjusts responses based on user's programming skill level
+- 🔌 **External API Support**: Optional support for ChatGPT, Ollama server, and OpenRouter as alternatives
+- 📥 **Model Download Manager**: Built-in download manager for recommended models
+- 🎨 **Customizable System Prompts**: Tailor AI behavior with custom system prompts
+- 📋 **Interactive Code Blocks**: Copy and insert code blocks directly from chat
+- 🎨 **Markdown Rendering**: Optional rich text formatting with tkinterweb
+- 💾 **USB Portable**: Can be bundled with Thonny and models for portable use
+- 🛡️ **Error Resilience**: Advanced error handling with automatic retry and user-friendly messages
+- ⚡ **Performance Optimized**: Message virtualization and caching for handling large conversations
+- 🔧 **Smart Provider Detection**: Automatically detects Ollama vs LM Studio based on API responses
+- 🌐 **Multi-language Support**: Japanese, Chinese (Simplified/Traditional), and English UI
+
+## Installation
+
+### From PyPI
+```bash
+# Standard installation (includes llama-cpp-python for CPU)
+pip install thonny-codemate
+```
+
+**For GPU support**, see [INSTALL_GPU.md](INSTALL_GPU.md) for detailed instructions:
+- NVIDIA GPUs (CUDA)
+- Apple Silicon (Metal)
+- Automatic GPU detection
+
+### Development Installation
+
+#### Quick Setup with uv (Recommended)
+```bash
+# Clone the repository
+git clone https://github.com/tokoroten/thonny-codemate.git
+cd thonny-codemate
+
+# Install uv if not already installed
+# Windows (PowerShell):
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+# Linux/macOS:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install all dependencies (including llama-cpp-python)
+uv sync --all-extras
+
+# Or install with development dependencies only
+uv sync --extra dev
+
+# (Optional) Install Markdown rendering support
+# Basic Markdown rendering:
+uv sync --extra markdown
+# Full JavaScript support for interactive features:
+uv sync --extra markdown-full
+
+# Activate virtual environment
+.venv\Scripts\activate  # Windows
+source .venv/bin/activate  # macOS/Linux
+```
+
+#### Alternative Setup Script
+```bash
+# Use the setup script for guided installation
+python setup_dev.py
+```
+
+### Installing with GPU Support
+
+By default, llama-cpp-python is installed with CPU support. For GPU acceleration:
+
+**CUDA support**:
+```bash
+# Reinstall llama-cpp-python with CUDA support
+uv pip uninstall llama-cpp-python
+uv pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124
+```
+
+**Metal support (macOS)**:
+```bash
+# Rebuild with Metal support
+uv pip uninstall llama-cpp-python
+CMAKE_ARGS="-DLLAMA_METAL=on" uv pip install llama-cpp-python --no-cache-dir
+```
+
+## Model Setup
+
+### Download GGUF Models
+
+Recommended models:
+- **Qwen2.5-Coder-14B** - Latest high-performance model specialized for programming (8.8GB)
+- **Llama-3.2-1B/3B** - Lightweight and fast models (0.8GB/2.0GB)
+- **Llama-3-ELYZA-JP-8B** - Japanese-specialized model (4.9GB)
+
+```bash
+# Install Hugging Face CLI
+pip install -U "huggingface_hub[cli]"
+
+# Qwen2.5 Coder (programming-focused, recommended)
+huggingface-cli download bartowski/Qwen2.5-Coder-14B-Instruct-GGUF Qwen2.5-Coder-14B-Instruct-Q4_K_M.gguf --local-dir ./models
+
+# Llama 3.2 1B (lightweight)
+huggingface-cli download bartowski/Llama-3.2-1B-Instruct-GGUF Llama-3.2-1B-Instruct-Q4_K_M.gguf --local-dir ./models
+```
+
+## Usage
+
+1. **Start Thonny** - The plugin will load automatically
+2. **Model Setup**:
+   - Open Settings → LLM Assistant Settings
+   - Choose between local models or external APIs
+   - For local models: Select a GGUF file or download recommended models
+   - For external APIs: Enter your API key and model name
+3. **Code Explanation**:
+   - Select code in the editor
+   - Right-click and choose "Explain Selection"
+   - The AI will explain the code based on your skill level
+4. **Code Generation**:
+   - Write a comment describing what you want
+   - Right-click and choose "Generate from Comment"
+   - Or use the AI Assistant panel for interactive chat
+5. **Error Fixing**:
+   - When you encounter an error, click "Explain Error" in the assistant panel
+   - The AI will analyze the error and suggest fixes
+
+### External API Configuration
+
+#### ChatGPT
+1. Get an API key from [OpenAI](https://platform.openai.com/)
+2. In settings, select "chatgpt" as provider
+3. Enter your API key
+4. Choose model (e.g., gpt-3.5-turbo, gpt-4)
+
+#### Ollama
+1. Install and run [Ollama](https://ollama.ai/)
+2. In settings, select "ollama" as provider
+3. Set base URL (default: http://localhost:11434)
+4. Choose installed model (e.g., llama3, mistral)
+
+#### OpenRouter
+1. Get an API key from [OpenRouter](https://openrouter.ai/)
+2. In settings, select "openrouter" as provider
+3. Enter your API key
+4. Choose model (free models available)
+
+## Development
+
+### Project Structure
+```
+thonny-codemate/
+├── thonnycontrib/
+│   └── thonny_codemate/
+│       ├── __init__.py       # Plugin entry point
+│       ├── llm_client.py     # LLM integration
+│       ├── ui_widgets.py     # UI components
+│       └── config.py         # Configuration
+├── models/                   # GGUF model storage
+├── tests/                    # Unit tests
+├── docs_for_ai/             # AI documentation
+└── README.md
+```
+
+### Running in Development Mode
+```bash
+# Normal mode
+python run_dev.py
+
+# Debug mode (for VS Code/PyCharm attachment)
+python run_dev.py --debug
+
+# Quick run with uv
+uv run thonny
+```
+
+### Running Tests
+```bash
+uv run pytest -v
+```
+
+## Configuration
+
+The plugin stores its configuration in Thonny's settings system. You can configure:
+
+- **Provider Selection**: Local models or external APIs (ChatGPT, Ollama, OpenRouter)
+- **Model Settings**: Model path, context size, generation parameters
+- **User Preferences**: Skill level (beginner/intermediate/advanced)
+- **System Prompts**: Choose between coding-focused, explanation-focused, or custom prompts
+- **Generation Parameters**: Temperature, max tokens, etc.
+
+## Requirements
+
+- Python 3.8+
+- Thonny 4.0+
+- llama-cpp-python (automatically installed)
+- 4GB+ RAM (depending on model size)
+- 5-10GB disk space for models
+- uv (for development)
+- tkinterweb with JavaScript support (for Markdown rendering and interactive features)
+  - Automatically installed with the plugin
+  - Includes PythonMonkey for JavaScript-Python communication
+  - Enables Copy/Insert buttons with direct Python integration
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Acknowledgments
+
+- Inspired by GitHub Copilot's functionality
+- Built on top of [llama-cpp-python](https://github.com/abetlen/llama-cpp-python)
+- Designed for [Thonny IDE](https://thonny.org/)
+- **99% of the code in this project was generated by [Claude Code](https://claude.ai/code)** - This project demonstrates the capabilities of AI-assisted development
+
+## Status
+
+🚧 **Under Development** - This plugin is currently in early development stage.
+
+## Roadmap
+
+- [x] Initial project setup
+- [x] Development environment with uv
+- [x] Basic plugin structure
+- [x] LLM integration with llama-cpp-python
+- [x] Chat panel UI (right side)
+- [x] Context menu for code explanation
+- [x] Code generation from comments
+- [x] Error fixing assistance
+- [x] Configuration UI
+- [x] Multi-file context support
+- [x] Model download manager
+- [x] External API support (ChatGPT, Ollama, OpenRouter)
+- [x] Customizable system prompts
+- [ ] Inline code completion
+- [ ] USB portable packaging
+- [ ] PyPI release
+
+## Links
+
+- [Thonny IDE](https://thonny.org/)
+- [llama-cpp-python](https://github.com/abetlen/llama-cpp-python)
+- [Project Documentation](docs_for_ai/)