opalacoder 0.1.1__tar.gz → 0.1.4__tar.gz

opalacoder-0.1.4/.claude/rules/RULES.md

@@ -0,0 +1,20 @@
+# Regras para Analises dadas Questões do Usuário
+1. **Relevância**: As análises devem ser diretamente relevantes à questão do usuário, abordando os pontos específicos levantados e evitando informações desnecessárias.
+
+2. Nunca levante hipóteses ou suposições sem base sólida. Se a questão do usuário for ambígua, peça esclarecimentos antes de fornecer uma análise. Realize testes para validar/excluir/confirmar hipóteses, e baseie suas análises nos resultados desses testes. Não invente testes fáceis de passar ou que não testem o que você diz que testam.
+
+# Regras de Diagnóstico de Testes
+1. **Cobertura de Código**: Assegure-se de que os testes cubram pelo menos 80% do código, incluindo casos de borda e cenários de falha.
+
+2. **Isolamento**: Cada teste deve ser independente e não depender de outros testes ou do estado global. Use mocks e stubs para isolar as unidades de código.
+
+2. **Repetibilidade**: Os testes devem produzir os mesmos resultados em execuções subsequentes, independentemente da ordem de execução ou do ambiente.
+
+3. **Clareza**: Os testes devem ser claros e fáceis de entender. Use nomes descritivos para os testes e organize-os de maneira lógica.
+
+
+# Regras de Organização de Testes
+Nunca gere arquivos de teste soltos na raiz do projeto. Use o diretório `tests/` para organizar os testes por funcionalidade ou módulo.
+
+# Regras de Nomenclatura de Testes
+Siga a convenção de nomenclatura `test_<nome_da_funcionalidade>.py` para arquivos de teste. Dentro dos arquivos, nomeie as funções de teste com o prefixo `test_` seguido de uma descrição clara do que está sendo testado, por exemplo, `test_calculo_soma()`.

opalacoder-0.1.4/.claude/settings.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep -A 30 \"checkAndEnforceHardFail\\\\|improve.*loop\\\\|composite.*tool\" /tmp/smallcode/bin/smallcode.js | head -60)",
+      "Read(//tmp/smallcode/bin/**)",
+      "Bash(python -c ' *)",
+      "Read(//home/gilzamir/**)",
+      "Bash(sed -n '/DEBUG PLAN JSON/,/\\\\/DEBUG PLAN JSON/p' /home/gilzamir/log.log)",
+      "Read(//home/gilzamir/micalc/**)",
+      "Bash(git stash *)",
+      "Bash(python -m pytest tests/ -q --ignore=tests/test_planner_output.py --ignore=tests/test_agent_config.py -k \"not llm and asyncio\")",
+      "Bash(python -m pytest tests/ -q --ignore=tests/test_planner_output.py --ignore=tests/test_agent_config.py -k \"not llm\")",
+      "Bash(python -m pytest tests/test_workflow_pipeline.py tests/test_verification_strategies.py -q -k \"asyncio or \\(not llm\\)\")",
+      "Bash(python -m pytest tests/ -x -q)",
+      "Bash(python -c \"from opalacoder.cli_commands import _registry, REPLState; print\\('OK'\\); print\\([k for k in _registry._cmds]\\)\")"
+    ],
+    "additionalDirectories": [
+      "/home/gilzamir"
+    ]
+  }
+}

opalacoder-0.1.4/.gitignore

@@ -0,0 +1,128 @@
+# --- Project-specific ---
+*.env
+.env
+*.env*
+.venv
+*.venv
+node_modules/
+plan.md
+
+# --- Project runtime data ---
+.opalacoder/
+
+# --- Python bytecode & caches ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyo
+
+# --- C extensions ---
+*.so
+
+# --- Distribution / packaging ---
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# --- PyInstaller ---
+*.manifest
+*.spec
+
+# --- Installer logs ---
+pip-log.txt
+pip-delete-this-directory.txt
+
+# --- Testing & coverage ---
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# --- Translations ---
+*.mo
+*.pot
+
+# --- Databases ---
+*.sqlite
+*.sqlite3
+*.sqlite3-journal
+*.sqlite-shm
+*.sqlite-wal
+
+# --- Logging ---
+*.log
+
+# --- Virtual environments ---
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# --- Jupyter ---
+.ipynb_checkpoints
+
+# --- IPython ---
+profile_default/
+ipython_config.py
+
+# --- PEP 582 ---
+__pypackages__/
+
+# --- Type checkers ---
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# --- Build tools ---
+.pybuilder/
+target/
+cython_debug/
+docs/_build/
+/site
+
+# --- Misc Python tools ---
+.scrapy
+instance/
+.webassets-cache
+celerybeat-schedule
+celerybeat.pid
+*.sage.py
+.spyderproject
+.spyproject
+.ropeproject
+local_settings.py
+
+# --- IDEs / Editors ---
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+*.db

opalacoder-0.1.1/AGENT.md → opalacoder-0.1.4/AGENTS.md

@@ -1,3 +1,7 @@
+# General Rules
+
+1. Don't make baseless assumptions; before drawing any conclusions, conduct tests and analysis to gather as much information as possible.
+
 # Project Guide
 
 ## Language

opalacoder-0.1.4/CLAUDE.md

@@ -0,0 +1,34 @@
+# General Rules
+
+1. Don't make baseless assumptions; before drawing any conclusions, conduct tests and analysis to gather as much information as possible.
+
+# Project Guide
+
+## Language
+
+All code, comments, and documentation must be written in **English**.
+
+## Architecture
+
+This project uses the **AgenticBlocks.IO** framework.
+Before starting any task, read the library source and documentation at:
+https://github.com/gilzamir/agenticblocks
+
+Key things to understand from that repo:
+- How blocks are structured and composed
+- How agents communicate and dispatch events
+- Naming conventions used throughout the framework
+
+## Project Context
+
+Read `docs/specs` before making changes. It contains the current project status, known issues, and decisions already made. Do not re-litigate what is documented there.
+
+## Build & Test Commands
+Run tests on tests dir after you implement a new feature.
+
+
+> Fill in your actual commands below — this is the highest-value section.
+
+```bash
+python -m pytest
+```

{opalacoder-0.1.1 → opalacoder-0.1.4}/GEMINI.md

@@ -1,3 +1,7 @@
+# General Rules
+
+1. Don't make baseless assumptions; before drawing any conclusions, conduct tests and analysis to gather as much information as possible.
+
 # Project Guide
 
 ## Language
@@ -17,8 +21,7 @@ Key things to understand from that repo:
 
 ## Project Context
 
-Read `ARCH_SUMMARY.md` before making changes. It contains the current project status,
-known issues, and decisions already made. Do not re-litigate what is documented there.
+Read `docs/specs` before making changes. It contains the current project status, known issues, and decisions already made. Do not re-litigate what is documented there.
 
 ## Build & Test Commands
 Run tests on tests dir after you implement a new feature.

opalacoder-0.1.4/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: opalacoder
+Version: 0.1.4
+Summary: Autonomous coding agent with interactive planning and modular execution
+Project-URL: Homepage, https://github.com/gilzamir/OpalaCoder
+Project-URL: Bug Tracker, https://github.com/gilzamir/OpalaCoder/issues
+Author-email: Gil Zamir <gilzamir@example.com>
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: agenticblocks-io>=0.8.37
+Requires-Dist: chromadb>=0.4.0
+Requires-Dist: instructor>=1.15.1
+Requires-Dist: litellm>=1.40.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pywebview>=4.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sentence-transformers>=3.0.0
+Requires-Dist: tree-sitter-language-pack>=1.8.0
+Requires-Dist: tree-sitter>=0.25.0
+Description-Content-Type: text/markdown
+
+# OpalaCoder
+
+**OpalaCoder** is an autonomous coding agent built on the **[AgenticBlocks.IO](https://github.com/gilzamir/agenticblocks)** framework. It features a project-centric context model and a modular, skills-oriented architecture optimized to run efficiently with local LLMs.
+
+---
+
+## Core Architecture & Features
+
+### 1. Project-Centric Context
+All operations happen within a named project mapped to a fixed directory. This grounds the agent's workspace, scopes file/terminal access, maintains SQLite-based project memory, and keeps LLM context windows small and focused.
+
+### 2. MemGPT Chat Orchestrator
+The main entry point is a persistent **MemGPT Chat Orchestrator** (`MemGPTAgentBlock`). Rather than running a static intent classifier, the orchestrator converses with the user, manages long-term memory, and dynamically routes complex tasks by invoking active skills via tool-calling (`run_skill`).
+
+### 3. Skills-Oriented Design (Anthropic Standard)
+Capabilities are defined as modular **skills** (defined via `SKILL.md` declarations and optional Level 3 python/bash scripts).
+- **Opt-in Activation**: Projects declare active skills in a local `skills.yaml` file.
+- **Ephemeral Sub-Agents**: When a skill is invoked, the orchestrator spawns a focused sub-agent (`LLMAgentBlock`) dedicated to executing that skill's workflow.
+- **Dialogue Interceptor**: The sub-agent communicates directly with the user, and an interceptor synchronizes the exchange back to the orchestrator's memory.
+
+### 4. Code Generation (`implement-feature` Skill)
+Software development and bug-fixing tasks are handled by the default `implement-feature` skill, running a structured Plan → Execute → Verify loop:
+- **Interactive Planning**: Generates high-level task plans and refines them based on user feedback.
+- **Shadow Git Checkout**: Automatically checkpoints code to an isolated repository (`.opalacoder/.git`) before plan execution, allowing instant rollback via `/undo`.
+- **Auto-Linting**: Validates changes using syntax checkers (`node --check`, `py_compile`) after each file edit, letting the worker self-correct syntax errors autonomously.
+
+### 5. Web-Based IDE GUI (Cross-Platform)
+OpalaCoder features an integrated desktop GUI built using React, Vite, and `pywebview`:
+- **Cross-Platform Support**: Works seamlessly on Linux and Windows. If `pywebview` is not available, it automatically falls back to hosting a local web server and launching the interface in your default browser.
+- **Integrated Terminal**: Includes a real-time xterm.js terminal with shell/PTY integration for running and inspecting commands natively.
+- **Git Source Control Sidebar**: A dedicated panel that tracks file modifications (color-coded as Modified/Untracked/Deleted) and provides a commit interface.
+- **Global Settings Panel**: Customize the editor font size, tab size, and word wrapping, with dynamic toggle support for Light and Dark themes.
+- **About Tab**: Version tracking (currently `0.1.4 alfa`), licensing, and developer details in the settings panel.
+
+### 6. Persistent Projects and CLI Commands
+
+| Command | Description |
+|---|---|
+| `/help` | Show available commands |
+| `/clear` | Clear memory and history of the current project |
+| `/rename <name>` | Rename the active project |
+| `/list` | List all saved projects |
+| `/load <name>` | Load an existing project |
+| `/delete <name>` | Delete a project (optionally deletes its directory) |
+| `/skills` | List available skills and active ones for the project |
+| `/addskill <name>` / `/rmskill <name>` | Add or remove skills |
+| `/undo` | Revert the last agent change via shadow VCS |
+| `/commit <msg>` | Manually commit to the shadow git |
+| `/exit` / `/quit` | Exit the application |
+
+### 7. Modular Architecture
+
+```text
+opalacoder/
+├── cli.py                  Entrypoint, project loading, REPL loop
+├── memgpt_runtime.py       MemGPT chat orchestrator and run_skill tool integration
+├── agents.py               Agent creation helper functions
+├── config.py               Global settings loader and CLI parser
+├── skills.py               Skill loading, selection, and routing
+├── project.py              SQLite project management and state
+├── vcs.py                  Shadow git strategies (auto, hybrid, agent-driven, none)
+├── ide_server.py           Asynchronous HTTP and REST server hosting the IDE GUI
+├── agent_stdin.py          JSON stdin/stdout protocol server for remote control
+├── code_index.py           Multi-language symbol index (SQLite-backed, incremental)
+├── vector_index.py         Vector index of chunks for semantic code lookup
+└── tools.py                Shared tool definitions (run_command, memory APIs)
+```
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [agenticblocks](https://github.com/gilzamir/agenticblocks) (install from source)
+- An Ollama instance with the default model available:
+  - **Default model**: `ministral-3:14b`
+  - **Alternative model** (complex tasks): also `ministral-3:14b` by default; change in `agents.yaml`
+  - Other tested models: `gemma4:latest`, `mistral-nemo:latest`
+  - Any model supported by [litellm](https://docs.litellm.ai) works
+- **Recommended Ollama version**: `0.24.0+`
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/gilzamir/OpalaCoder
+cd OpalaCoder
+
+python -m venv .env
+source .env/bin/activate          # Linux/macOS
+# .env\Scripts\activate           # Windows
+
+# Install agenticblocks from source first
+pip install -e /path/to/agenticblocks
+
+# Install OpalaCoder dependencies
+pip install -r requirements.txt
+```
+
+### Environment Variables (Optional)
+
+```env
+# Override default model (any litellm-supported string)
+OPALA_MODEL=ollama/ministral-3:14b
+```
+
+---
+
+## How to Run
+
+OpalaCoder supports three main execution modes:
+
+### 1. Interactive CLI REPL (Default)
+Starts the standard CLI terminal planner/execution loop:
+```bash
+source .env/bin/activate
+python main.py                        # default (plan mode)
+python main.py --mode auto            # run without interruptions
+python main.py --mode edit            # confirm sensitive operations
+python main.py --model ollama/gemma4  # override model
+python main.py --db /path/to/db       # custom database path
+python main.py --version
+python main.py --help
+```
+
+### 2. Web-Based IDE GUI
+Launches the integrated React desktop application. It opens as a local app window (via `pywebview`) or falls back to your web browser:
+```bash
+source .env/bin/activate
+python main.py --gui
+```
+
+### 3. Stdin/Stdout JSON Protocol Server
+Launches the agent in background headless mode, communicating via single-line JSON messages:
+```bash
+source .env/bin/activate
+python main.py --stdin
+```
+
+---
+
+## Compiling Frontend GUI (Optional)
+
+If you are developing or making changes to the React GUI, you can recompile the assets:
+```bash
+cd gui_src
+npm install
+npm run build
+```
+This builds the SPA bundle and saves it directly into the Python package distribution at `opalacoder/gui/`.
+
+## Project Flow
+
+```text
+main() or `--gui` (server mode)
+  │
+  ├── startup_menu() ───────── Load/Create project, discover skills (via skills.yaml)
+  │
+  └── repl_loop() ──────────── Instantiate MemGPT chat-orchestrator
+        │
+        ├── User enters command (e.g. `/help`, `/undo`) ── Dispatched to CLI commands
+        │
+        └── User enters demand ────────────────────────── MemGPT.run(user_input)
+              │
+              ├── Direct chat (greetings, project status, general questions)
+              │
+              └── Request matches active skill ───────────── run_skill(name, context)
+                    │
+                    ├── Instantiate ephemeral sub-agent (LLMAgentBlock)
+                    ├── Sub-agent loads SKILL.md and Level 3 scripts (e.g. implement-feature)
+                    ├── Sub-agent executes with tools, talks to user (dialogue interceptor)
+                    └── Return result to MemGPT orchestrator
+```
+
+---
+
+## Configuration (`agents.yaml`)
+
+The main configuration file. Key fields and role overrides:
+
+```yaml
+default: ollama/ministral-3:14b      # default model for all agents
+alternative: ollama/ministral-3:14b  # model for complex tasks
+
+llm_defaults:
+  temperature: 1.0
+  max_tokens: 8128
+  num_ctx: 8192
+
+agents:
+  # The fixed chat-orchestrator of the skills-oriented architecture.
+  memgpt:
+    temperature: 1.0
+    num_ctx: 16384
+    max_heartbeats: 20
+
+  # drives the plan→execute→review loop inside the implement-feature skill
+  orchestrator:
+    temperature: 1.0
+    num_ctx: 16384
+    max_heartbeats: 20
+    strategy: workflow
+
+  # executes each task command with code editing tools
+  worker:
+    temperature: 1.0
+    max_tokens: 8128
+    num_ctx: 16384
+    reasoning_effort: "none"  # Must stay "none" for tool-calling integration
+```
+
+Full per-agent overrides for `temperature`, `max_tokens`, `num_ctx`, `reasoning_effort`, and `debug` are supported for every agent role.
+
+---
+
+## Benchmark
+
+A JS bug-fix benchmark is included in `scripts/`:
+
+```bash
+# Collect instances from GitHub (requires gh CLI authenticated)
+python scripts/collect_jsbench.py --limit 50 --out datasets/jsbench
+
+# Evaluate OpalaCoder on collected instances
+python scripts/eval_jsbench.py --limit 10
+```
+
+Results are written to `datasets/jsbench_results.json` with per-instance pass/fail and a summary fix rate.
+
+---
+
+## Build & Test
+
+```bash
+python -m pytest tests/ -q
+```
+
+---
+
+## License
+
+MIT