opalacoder 0.1.3__tar.gz → 0.1.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. opalacoder-0.1.4/.claude/rules/RULES.md +20 -0
  2. {opalacoder-0.1.3 → opalacoder-0.1.4}/.claude/settings.json +2 -1
  3. {opalacoder-0.1.3 → opalacoder-0.1.4}/CLAUDE.md +1 -2
  4. {opalacoder-0.1.3 → opalacoder-0.1.4}/GEMINI.md +1 -2
  5. opalacoder-0.1.4/PKG-INFO +269 -0
  6. opalacoder-0.1.4/README.md +243 -0
  7. {opalacoder-0.1.3 → opalacoder-0.1.4}/agents.yaml +14 -48
  8. opalacoder-0.1.4/config.yaml +13 -0
  9. opalacoder-0.1.4/docs/specs/01-arquitetura.md +133 -0
  10. opalacoder-0.1.4/docs/specs/02-memgpt-orquestrador.md +103 -0
  11. opalacoder-0.1.4/docs/specs/03-skill-implement-feature.md +146 -0
  12. opalacoder-0.1.4/docs/specs/04-memoria.md +134 -0
  13. opalacoder-0.1.4/docs/specs/05-vcs-sombra.md +94 -0
  14. opalacoder-0.1.4/docs/specs/06-skills-e-plugins.md +260 -0
  15. opalacoder-0.1.4/docs/specs/07-configuracao.md +161 -0
  16. opalacoder-0.1.4/docs/specs/08-ide.md +153 -0
  17. opalacoder-0.1.4/docs/specs/09-ide-projectcreationinterface.md +75 -0
  18. opalacoder-0.1.4/docs/specs/README.md +79 -0
  19. opalacoder-0.1.4/gui_src/index.html +17 -0
  20. opalacoder-0.1.4/gui_src/package-lock.json +2701 -0
  21. opalacoder-0.1.4/gui_src/package.json +30 -0
  22. opalacoder-0.1.4/gui_src/src/App.jsx +1953 -0
  23. opalacoder-0.1.4/gui_src/src/index.css +608 -0
  24. opalacoder-0.1.4/gui_src/src/main.jsx +10 -0
  25. opalacoder-0.1.4/gui_src/vite.config.js +24 -0
  26. opalacoder-0.1.4/opalacoder/agent_stdin.py +551 -0
  27. opalacoder-0.1.4/opalacoder/agents.py +79 -0
  28. opalacoder-0.1.4/opalacoder/cli.py +275 -0
  29. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/cli_commands.py +83 -54
  30. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/config.py +105 -53
  31. opalacoder-0.1.4/opalacoder/copy_gui.py +20 -0
  32. opalacoder-0.1.4/opalacoder/gui/assets/index-CZ4mgucw.css +32 -0
  33. opalacoder-0.1.4/opalacoder/gui/assets/index-DJeOys10.js +206 -0
  34. opalacoder-0.1.4/opalacoder/gui/index.html +18 -0
  35. opalacoder-0.1.4/opalacoder/ide_server.py +645 -0
  36. opalacoder-0.1.4/opalacoder/memgpt_runtime.py +345 -0
  37. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/plugins/html_css_js_tools.py +3 -7
  38. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/project.py +81 -8
  39. opalacoder-0.1.4/opalacoder/skills.py +230 -0
  40. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/terminal.py +56 -16
  41. opalacoder-0.1.4/opalacoder/terminal_manager.py +157 -0
  42. opalacoder-0.1.4/opalacoder/vector_index.py +335 -0
  43. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/workflow_orchestrator.py +168 -165
  44. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/workflow_tools.py +73 -5
  45. {opalacoder-0.1.3 → opalacoder-0.1.4}/pyproject.toml +3 -2
  46. opalacoder-0.1.4/requirements.txt +15 -0
  47. opalacoder-0.1.4/skills/chat-orchestrator/SKILL.md +63 -0
  48. opalacoder-0.1.4/skills/command-line/SKILL.md +33 -0
  49. opalacoder-0.1.4/skills/command-line/scripts/command_executor.py +105 -0
  50. opalacoder-0.1.4/skills/skills_store/html-css-js/SKILL.md +48 -0
  51. opalacoder-0.1.4/skills/skills_store/html-css-js/scripts/check_contracts.py +69 -0
  52. opalacoder-0.1.4/skills/skills_store/implement-feature/SKILL.md +46 -0
  53. opalacoder-0.1.4/skills/skills_store/implement-feature/scripts/run_workflow.py +149 -0
  54. opalacoder-0.1.4/tests/test_agent_config.py +62 -0
  55. opalacoder-0.1.4/tests/test_agent_stdin.py +133 -0
  56. opalacoder-0.1.4/tests/test_command_line_skill.py +76 -0
  57. opalacoder-0.1.4/tests/test_file_delete.py +61 -0
  58. opalacoder-0.1.4/tests/test_implement_feature_script.py +60 -0
  59. opalacoder-0.1.4/tests/test_memgpt_runtime.py +106 -0
  60. opalacoder-0.1.4/tests/test_model_commands.py +95 -0
  61. {opalacoder-0.1.3 → opalacoder-0.1.4}/tests/test_planner_output.py +4 -10
  62. opalacoder-0.1.4/tests/test_skills_directory_loader.py +225 -0
  63. opalacoder-0.1.4/tests/test_unhashable_dict_bug.py +168 -0
  64. {opalacoder-0.1.3 → opalacoder-0.1.4}/tests/test_workflow_pipeline.py +0 -136
  65. opalacoder-0.1.3/ARCH_SUMMARY.md +0 -201
  66. opalacoder-0.1.3/FLOW_MAP.md +0 -230
  67. opalacoder-0.1.3/PKG-INFO +0 -222
  68. opalacoder-0.1.3/README.md +0 -197
  69. opalacoder-0.1.3/docs/ALGS.md +0 -257
  70. opalacoder-0.1.3/docs/specs1.md +0 -16
  71. opalacoder-0.1.3/docs/specs2.md +0 -1
  72. opalacoder-0.1.3/docs/specs3.md +0 -0
  73. opalacoder-0.1.3/experiments/direct_gemini_test.py +0 -27
  74. opalacoder-0.1.3/experiments/run_micalc_test.py +0 -145
  75. opalacoder-0.1.3/experiments/test_complexity.py +0 -1
  76. opalacoder-0.1.3/experiments/test_gemini.py +0 -20
  77. opalacoder-0.1.3/experiments/test_gemini_sequences.py +0 -52
  78. opalacoder-0.1.3/experiments/test_gemma4.py +0 -94
  79. opalacoder-0.1.3/experiments/test_llm.py +0 -58
  80. opalacoder-0.1.3/opalacoder/agents.py +0 -267
  81. opalacoder-0.1.3/opalacoder/cli.py +0 -457
  82. opalacoder-0.1.3/opalacoder/memgpt.py +0 -463
  83. opalacoder-0.1.3/opalacoder/plugins/default_reviewer.py +0 -76
  84. opalacoder-0.1.3/opalacoder/skills.py +0 -311
  85. opalacoder-0.1.3/requirements.txt +0 -11
  86. opalacoder-0.1.3/skills/debug.md +0 -36
  87. opalacoder-0.1.3/skills/generaldeveloper.md +0 -52
  88. opalacoder-0.1.3/skills/html_css_js.md +0 -54
  89. opalacoder-0.1.3/skills/opalacoder.md +0 -37
  90. opalacoder-0.1.3/skills/python_subprocess.md +0 -11
  91. opalacoder-0.1.3/skills/react_vite.md +0 -6
  92. opalacoder-0.1.3/tests/test_agent_config.py +0 -98
  93. opalacoder-0.1.3/tests/test_double_inference.py +0 -21
  94. opalacoder-0.1.3/tests/test_intent_classifier.py +0 -178
  95. opalacoder-0.1.3/tests/test_skills_loading.py +0 -226
  96. {opalacoder-0.1.3 → opalacoder-0.1.4}/.github/workflows/publish.yml +0 -0
  97. {opalacoder-0.1.3 → opalacoder-0.1.4}/.gitignore +0 -0
  98. {opalacoder-0.1.3 → opalacoder-0.1.4}/AGENTS.md +0 -0
  99. {opalacoder-0.1.3 → opalacoder-0.1.4}/debug/scratch_tail.py +0 -0
  100. {opalacoder-0.1.3/docs → opalacoder-0.1.4/docs/guide}/analysis_results.md +0 -0
  101. {opalacoder-0.1.3/docs → opalacoder-0.1.4/docs/guide}/figs/logotipo.png +0 -0
  102. {opalacoder-0.1.3/docs → opalacoder-0.1.4/docs/guide}/paper_memplan.md +0 -0
  103. {opalacoder-0.1.3/docs → opalacoder-0.1.4/docs/guide}/skills-plugin-system.md +0 -0
  104. {opalacoder-0.1.3 → opalacoder-0.1.4}/main.py +0 -0
  105. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/__init__.py +0 -0
  106. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/api_keys.py +0 -0
  107. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/archival.py +0 -0
  108. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/code_index.py +0 -0
  109. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/embeddings.py +0 -0
  110. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/i18n.py +0 -0
  111. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/orchestrator.py +0 -0
  112. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/planner.py +0 -0
  113. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/plugins/__init__.py +0 -0
  114. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/session.py +0 -0
  115. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/structured.py +0 -0
  116. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/tools.py +0 -0
  117. {opalacoder-0.1.3 → opalacoder-0.1.4}/opalacoder/vcs.py +0 -0
  118. {opalacoder-0.1.3 → opalacoder-0.1.4}/pytest.ini +0 -0
  119. {opalacoder-0.1.3 → opalacoder-0.1.4}/tests/test_code_index_integration.py +0 -0
  120. {opalacoder-0.1.3 → opalacoder-0.1.4}/tests/test_complexity_evaluator.py +0 -0
  121. {opalacoder-0.1.3 → opalacoder-0.1.4}/tests/test_context_guard.py +0 -0
  122. {opalacoder-0.1.3 → opalacoder-0.1.4}/tests/test_i18n_coverage.py +0 -0
  123. {opalacoder-0.1.3 → opalacoder-0.1.4}/tests/test_planner_oracle_live.py +0 -0
  124. {opalacoder-0.1.3 → opalacoder-0.1.4}/tests/test_project_store.py +0 -0
  125. {opalacoder-0.1.3 → opalacoder-0.1.4}/tests/test_refinement_loop.py +0 -0
  126. {opalacoder-0.1.3 → opalacoder-0.1.4}/tests/test_search_bugs.py +0 -0
  127. {opalacoder-0.1.3 → opalacoder-0.1.4}/tests/test_verification_strategies.py +0 -0
@@ -0,0 +1,20 @@
1
+ # Regras para Analises dadas Questões do Usuário
2
+ 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.
3
+
4
+ 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.
5
+
6
+ # Regras de Diagnóstico de Testes
7
+ 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.
8
+
9
+ 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.
10
+
11
+ 2. **Repetibilidade**: Os testes devem produzir os mesmos resultados em execuções subsequentes, independentemente da ordem de execução ou do ambiente.
12
+
13
+ 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.
14
+
15
+
16
+ # Regras de Organização de Testes
17
+ Nunca gere arquivos de teste soltos na raiz do projeto. Use o diretório `tests/` para organizar os testes por funcionalidade ou módulo.
18
+
19
+ # Regras de Nomenclatura de Testes
20
+ 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()`.
@@ -11,7 +11,8 @@
11
11
  "Bash(python -m pytest tests/ -q --ignore=tests/test_planner_output.py --ignore=tests/test_agent_config.py -k \"not llm and asyncio\")",
12
12
  "Bash(python -m pytest tests/ -q --ignore=tests/test_planner_output.py --ignore=tests/test_agent_config.py -k \"not llm\")",
13
13
  "Bash(python -m pytest tests/test_workflow_pipeline.py tests/test_verification_strategies.py -q -k \"asyncio or \\(not llm\\)\")",
14
- "Bash(python -m pytest tests/ -x -q)"
14
+ "Bash(python -m pytest tests/ -x -q)",
15
+ "Bash(python -c \"from opalacoder.cli_commands import _registry, REPLState; print\\('OK'\\); print\\([k for k in _registry._cmds]\\)\")"
15
16
  ],
16
17
  "additionalDirectories": [
17
18
  "/home/gilzamir"
@@ -21,8 +21,7 @@ Key things to understand from that repo:
21
21
 
22
22
  ## Project Context
23
23
 
24
- Read `ARCH_SUMMARY.md` before making changes. It contains the current project status,
25
- known issues, and decisions already made. Do not re-litigate what is documented there.
24
+ 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.
26
25
 
27
26
  ## Build & Test Commands
28
27
  Run tests on tests dir after you implement a new feature.
@@ -21,8 +21,7 @@ Key things to understand from that repo:
21
21
 
22
22
  ## Project Context
23
23
 
24
- Read `ARCH_SUMMARY.md` before making changes. It contains the current project status,
25
- known issues, and decisions already made. Do not re-litigate what is documented there.
24
+ 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.
26
25
 
27
26
  ## Build & Test Commands
28
27
  Run tests on tests dir after you implement a new feature.
@@ -0,0 +1,269 @@
1
+ Metadata-Version: 2.4
2
+ Name: opalacoder
3
+ Version: 0.1.4
4
+ Summary: Autonomous coding agent with interactive planning and modular execution
5
+ Project-URL: Homepage, https://github.com/gilzamir/OpalaCoder
6
+ Project-URL: Bug Tracker, https://github.com/gilzamir/OpalaCoder/issues
7
+ Author-email: Gil Zamir <gilzamir@example.com>
8
+ License: MIT
9
+ Classifier: License :: OSI Approved :: MIT License
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Programming Language :: Python :: 3
12
+ Requires-Python: >=3.11
13
+ Requires-Dist: agenticblocks-io>=0.8.37
14
+ Requires-Dist: chromadb>=0.4.0
15
+ Requires-Dist: instructor>=1.15.1
16
+ Requires-Dist: litellm>=1.40.0
17
+ Requires-Dist: numpy>=1.21.0
18
+ Requires-Dist: python-dotenv>=1.0.0
19
+ Requires-Dist: pywebview>=4.0
20
+ Requires-Dist: pyyaml>=6.0
21
+ Requires-Dist: rich>=13.0.0
22
+ Requires-Dist: sentence-transformers>=3.0.0
23
+ Requires-Dist: tree-sitter-language-pack>=1.8.0
24
+ Requires-Dist: tree-sitter>=0.25.0
25
+ Description-Content-Type: text/markdown
26
+
27
+ # OpalaCoder
28
+
29
+ **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.
30
+
31
+ ---
32
+
33
+ ## Core Architecture & Features
34
+
35
+ ### 1. Project-Centric Context
36
+ 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.
37
+
38
+ ### 2. MemGPT Chat Orchestrator
39
+ 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`).
40
+
41
+ ### 3. Skills-Oriented Design (Anthropic Standard)
42
+ Capabilities are defined as modular **skills** (defined via `SKILL.md` declarations and optional Level 3 python/bash scripts).
43
+ - **Opt-in Activation**: Projects declare active skills in a local `skills.yaml` file.
44
+ - **Ephemeral Sub-Agents**: When a skill is invoked, the orchestrator spawns a focused sub-agent (`LLMAgentBlock`) dedicated to executing that skill's workflow.
45
+ - **Dialogue Interceptor**: The sub-agent communicates directly with the user, and an interceptor synchronizes the exchange back to the orchestrator's memory.
46
+
47
+ ### 4. Code Generation (`implement-feature` Skill)
48
+ Software development and bug-fixing tasks are handled by the default `implement-feature` skill, running a structured Plan → Execute → Verify loop:
49
+ - **Interactive Planning**: Generates high-level task plans and refines them based on user feedback.
50
+ - **Shadow Git Checkout**: Automatically checkpoints code to an isolated repository (`.opalacoder/.git`) before plan execution, allowing instant rollback via `/undo`.
51
+ - **Auto-Linting**: Validates changes using syntax checkers (`node --check`, `py_compile`) after each file edit, letting the worker self-correct syntax errors autonomously.
52
+
53
+ ### 5. Web-Based IDE GUI (Cross-Platform)
54
+ OpalaCoder features an integrated desktop GUI built using React, Vite, and `pywebview`:
55
+ - **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.
56
+ - **Integrated Terminal**: Includes a real-time xterm.js terminal with shell/PTY integration for running and inspecting commands natively.
57
+ - **Git Source Control Sidebar**: A dedicated panel that tracks file modifications (color-coded as Modified/Untracked/Deleted) and provides a commit interface.
58
+ - **Global Settings Panel**: Customize the editor font size, tab size, and word wrapping, with dynamic toggle support for Light and Dark themes.
59
+ - **About Tab**: Version tracking (currently `0.1.4 alfa`), licensing, and developer details in the settings panel.
60
+
61
+ ### 6. Persistent Projects and CLI Commands
62
+
63
+ | Command | Description |
64
+ |---|---|
65
+ | `/help` | Show available commands |
66
+ | `/clear` | Clear memory and history of the current project |
67
+ | `/rename <name>` | Rename the active project |
68
+ | `/list` | List all saved projects |
69
+ | `/load <name>` | Load an existing project |
70
+ | `/delete <name>` | Delete a project (optionally deletes its directory) |
71
+ | `/skills` | List available skills and active ones for the project |
72
+ | `/addskill <name>` / `/rmskill <name>` | Add or remove skills |
73
+ | `/undo` | Revert the last agent change via shadow VCS |
74
+ | `/commit <msg>` | Manually commit to the shadow git |
75
+ | `/exit` / `/quit` | Exit the application |
76
+
77
+ ### 7. Modular Architecture
78
+
79
+ ```text
80
+ opalacoder/
81
+ ├── cli.py Entrypoint, project loading, REPL loop
82
+ ├── memgpt_runtime.py MemGPT chat orchestrator and run_skill tool integration
83
+ ├── agents.py Agent creation helper functions
84
+ ├── config.py Global settings loader and CLI parser
85
+ ├── skills.py Skill loading, selection, and routing
86
+ ├── project.py SQLite project management and state
87
+ ├── vcs.py Shadow git strategies (auto, hybrid, agent-driven, none)
88
+ ├── ide_server.py Asynchronous HTTP and REST server hosting the IDE GUI
89
+ ├── agent_stdin.py JSON stdin/stdout protocol server for remote control
90
+ ├── code_index.py Multi-language symbol index (SQLite-backed, incremental)
91
+ ├── vector_index.py Vector index of chunks for semantic code lookup
92
+ └── tools.py Shared tool definitions (run_command, memory APIs)
93
+ ```
94
+
95
+ ---
96
+
97
+ ## Requirements
98
+
99
+ - Python 3.11+
100
+ - [agenticblocks](https://github.com/gilzamir/agenticblocks) (install from source)
101
+ - An Ollama instance with the default model available:
102
+ - **Default model**: `ministral-3:14b`
103
+ - **Alternative model** (complex tasks): also `ministral-3:14b` by default; change in `agents.yaml`
104
+ - Other tested models: `gemma4:latest`, `mistral-nemo:latest`
105
+ - Any model supported by [litellm](https://docs.litellm.ai) works
106
+ - **Recommended Ollama version**: `0.24.0+`
107
+
108
+ ---
109
+
110
+ ## Installation
111
+
112
+ ```bash
113
+ git clone https://github.com/gilzamir/OpalaCoder
114
+ cd OpalaCoder
115
+
116
+ python -m venv .env
117
+ source .env/bin/activate # Linux/macOS
118
+ # .env\Scripts\activate # Windows
119
+
120
+ # Install agenticblocks from source first
121
+ pip install -e /path/to/agenticblocks
122
+
123
+ # Install OpalaCoder dependencies
124
+ pip install -r requirements.txt
125
+ ```
126
+
127
+ ### Environment Variables (Optional)
128
+
129
+ ```env
130
+ # Override default model (any litellm-supported string)
131
+ OPALA_MODEL=ollama/ministral-3:14b
132
+ ```
133
+
134
+ ---
135
+
136
+ ## How to Run
137
+
138
+ OpalaCoder supports three main execution modes:
139
+
140
+ ### 1. Interactive CLI REPL (Default)
141
+ Starts the standard CLI terminal planner/execution loop:
142
+ ```bash
143
+ source .env/bin/activate
144
+ python main.py # default (plan mode)
145
+ python main.py --mode auto # run without interruptions
146
+ python main.py --mode edit # confirm sensitive operations
147
+ python main.py --model ollama/gemma4 # override model
148
+ python main.py --db /path/to/db # custom database path
149
+ python main.py --version
150
+ python main.py --help
151
+ ```
152
+
153
+ ### 2. Web-Based IDE GUI
154
+ Launches the integrated React desktop application. It opens as a local app window (via `pywebview`) or falls back to your web browser:
155
+ ```bash
156
+ source .env/bin/activate
157
+ python main.py --gui
158
+ ```
159
+
160
+ ### 3. Stdin/Stdout JSON Protocol Server
161
+ Launches the agent in background headless mode, communicating via single-line JSON messages:
162
+ ```bash
163
+ source .env/bin/activate
164
+ python main.py --stdin
165
+ ```
166
+
167
+ ---
168
+
169
+ ## Compiling Frontend GUI (Optional)
170
+
171
+ If you are developing or making changes to the React GUI, you can recompile the assets:
172
+ ```bash
173
+ cd gui_src
174
+ npm install
175
+ npm run build
176
+ ```
177
+ This builds the SPA bundle and saves it directly into the Python package distribution at `opalacoder/gui/`.
178
+
179
+ ## Project Flow
180
+
181
+ ```text
182
+ main() or `--gui` (server mode)
183
+
184
+ ├── startup_menu() ───────── Load/Create project, discover skills (via skills.yaml)
185
+
186
+ └── repl_loop() ──────────── Instantiate MemGPT chat-orchestrator
187
+
188
+ ├── User enters command (e.g. `/help`, `/undo`) ── Dispatched to CLI commands
189
+
190
+ └── User enters demand ────────────────────────── MemGPT.run(user_input)
191
+
192
+ ├── Direct chat (greetings, project status, general questions)
193
+
194
+ └── Request matches active skill ───────────── run_skill(name, context)
195
+
196
+ ├── Instantiate ephemeral sub-agent (LLMAgentBlock)
197
+ ├── Sub-agent loads SKILL.md and Level 3 scripts (e.g. implement-feature)
198
+ ├── Sub-agent executes with tools, talks to user (dialogue interceptor)
199
+ └── Return result to MemGPT orchestrator
200
+ ```
201
+
202
+ ---
203
+
204
+ ## Configuration (`agents.yaml`)
205
+
206
+ The main configuration file. Key fields and role overrides:
207
+
208
+ ```yaml
209
+ default: ollama/ministral-3:14b # default model for all agents
210
+ alternative: ollama/ministral-3:14b # model for complex tasks
211
+
212
+ llm_defaults:
213
+ temperature: 1.0
214
+ max_tokens: 8128
215
+ num_ctx: 8192
216
+
217
+ agents:
218
+ # The fixed chat-orchestrator of the skills-oriented architecture.
219
+ memgpt:
220
+ temperature: 1.0
221
+ num_ctx: 16384
222
+ max_heartbeats: 20
223
+
224
+ # drives the plan→execute→review loop inside the implement-feature skill
225
+ orchestrator:
226
+ temperature: 1.0
227
+ num_ctx: 16384
228
+ max_heartbeats: 20
229
+ strategy: workflow
230
+
231
+ # executes each task command with code editing tools
232
+ worker:
233
+ temperature: 1.0
234
+ max_tokens: 8128
235
+ num_ctx: 16384
236
+ reasoning_effort: "none" # Must stay "none" for tool-calling integration
237
+ ```
238
+
239
+ Full per-agent overrides for `temperature`, `max_tokens`, `num_ctx`, `reasoning_effort`, and `debug` are supported for every agent role.
240
+
241
+ ---
242
+
243
+ ## Benchmark
244
+
245
+ A JS bug-fix benchmark is included in `scripts/`:
246
+
247
+ ```bash
248
+ # Collect instances from GitHub (requires gh CLI authenticated)
249
+ python scripts/collect_jsbench.py --limit 50 --out datasets/jsbench
250
+
251
+ # Evaluate OpalaCoder on collected instances
252
+ python scripts/eval_jsbench.py --limit 10
253
+ ```
254
+
255
+ Results are written to `datasets/jsbench_results.json` with per-instance pass/fail and a summary fix rate.
256
+
257
+ ---
258
+
259
+ ## Build & Test
260
+
261
+ ```bash
262
+ python -m pytest tests/ -q
263
+ ```
264
+
265
+ ---
266
+
267
+ ## License
268
+
269
+ MIT
@@ -0,0 +1,243 @@
1
+ # OpalaCoder
2
+
3
+ **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.
4
+
5
+ ---
6
+
7
+ ## Core Architecture & Features
8
+
9
+ ### 1. Project-Centric Context
10
+ 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.
11
+
12
+ ### 2. MemGPT Chat Orchestrator
13
+ 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`).
14
+
15
+ ### 3. Skills-Oriented Design (Anthropic Standard)
16
+ Capabilities are defined as modular **skills** (defined via `SKILL.md` declarations and optional Level 3 python/bash scripts).
17
+ - **Opt-in Activation**: Projects declare active skills in a local `skills.yaml` file.
18
+ - **Ephemeral Sub-Agents**: When a skill is invoked, the orchestrator spawns a focused sub-agent (`LLMAgentBlock`) dedicated to executing that skill's workflow.
19
+ - **Dialogue Interceptor**: The sub-agent communicates directly with the user, and an interceptor synchronizes the exchange back to the orchestrator's memory.
20
+
21
+ ### 4. Code Generation (`implement-feature` Skill)
22
+ Software development and bug-fixing tasks are handled by the default `implement-feature` skill, running a structured Plan → Execute → Verify loop:
23
+ - **Interactive Planning**: Generates high-level task plans and refines them based on user feedback.
24
+ - **Shadow Git Checkout**: Automatically checkpoints code to an isolated repository (`.opalacoder/.git`) before plan execution, allowing instant rollback via `/undo`.
25
+ - **Auto-Linting**: Validates changes using syntax checkers (`node --check`, `py_compile`) after each file edit, letting the worker self-correct syntax errors autonomously.
26
+
27
+ ### 5. Web-Based IDE GUI (Cross-Platform)
28
+ OpalaCoder features an integrated desktop GUI built using React, Vite, and `pywebview`:
29
+ - **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.
30
+ - **Integrated Terminal**: Includes a real-time xterm.js terminal with shell/PTY integration for running and inspecting commands natively.
31
+ - **Git Source Control Sidebar**: A dedicated panel that tracks file modifications (color-coded as Modified/Untracked/Deleted) and provides a commit interface.
32
+ - **Global Settings Panel**: Customize the editor font size, tab size, and word wrapping, with dynamic toggle support for Light and Dark themes.
33
+ - **About Tab**: Version tracking (currently `0.1.4 alfa`), licensing, and developer details in the settings panel.
34
+
35
+ ### 6. Persistent Projects and CLI Commands
36
+
37
+ | Command | Description |
38
+ |---|---|
39
+ | `/help` | Show available commands |
40
+ | `/clear` | Clear memory and history of the current project |
41
+ | `/rename <name>` | Rename the active project |
42
+ | `/list` | List all saved projects |
43
+ | `/load <name>` | Load an existing project |
44
+ | `/delete <name>` | Delete a project (optionally deletes its directory) |
45
+ | `/skills` | List available skills and active ones for the project |
46
+ | `/addskill <name>` / `/rmskill <name>` | Add or remove skills |
47
+ | `/undo` | Revert the last agent change via shadow VCS |
48
+ | `/commit <msg>` | Manually commit to the shadow git |
49
+ | `/exit` / `/quit` | Exit the application |
50
+
51
+ ### 7. Modular Architecture
52
+
53
+ ```text
54
+ opalacoder/
55
+ ├── cli.py Entrypoint, project loading, REPL loop
56
+ ├── memgpt_runtime.py MemGPT chat orchestrator and run_skill tool integration
57
+ ├── agents.py Agent creation helper functions
58
+ ├── config.py Global settings loader and CLI parser
59
+ ├── skills.py Skill loading, selection, and routing
60
+ ├── project.py SQLite project management and state
61
+ ├── vcs.py Shadow git strategies (auto, hybrid, agent-driven, none)
62
+ ├── ide_server.py Asynchronous HTTP and REST server hosting the IDE GUI
63
+ ├── agent_stdin.py JSON stdin/stdout protocol server for remote control
64
+ ├── code_index.py Multi-language symbol index (SQLite-backed, incremental)
65
+ ├── vector_index.py Vector index of chunks for semantic code lookup
66
+ └── tools.py Shared tool definitions (run_command, memory APIs)
67
+ ```
68
+
69
+ ---
70
+
71
+ ## Requirements
72
+
73
+ - Python 3.11+
74
+ - [agenticblocks](https://github.com/gilzamir/agenticblocks) (install from source)
75
+ - An Ollama instance with the default model available:
76
+ - **Default model**: `ministral-3:14b`
77
+ - **Alternative model** (complex tasks): also `ministral-3:14b` by default; change in `agents.yaml`
78
+ - Other tested models: `gemma4:latest`, `mistral-nemo:latest`
79
+ - Any model supported by [litellm](https://docs.litellm.ai) works
80
+ - **Recommended Ollama version**: `0.24.0+`
81
+
82
+ ---
83
+
84
+ ## Installation
85
+
86
+ ```bash
87
+ git clone https://github.com/gilzamir/OpalaCoder
88
+ cd OpalaCoder
89
+
90
+ python -m venv .env
91
+ source .env/bin/activate # Linux/macOS
92
+ # .env\Scripts\activate # Windows
93
+
94
+ # Install agenticblocks from source first
95
+ pip install -e /path/to/agenticblocks
96
+
97
+ # Install OpalaCoder dependencies
98
+ pip install -r requirements.txt
99
+ ```
100
+
101
+ ### Environment Variables (Optional)
102
+
103
+ ```env
104
+ # Override default model (any litellm-supported string)
105
+ OPALA_MODEL=ollama/ministral-3:14b
106
+ ```
107
+
108
+ ---
109
+
110
+ ## How to Run
111
+
112
+ OpalaCoder supports three main execution modes:
113
+
114
+ ### 1. Interactive CLI REPL (Default)
115
+ Starts the standard CLI terminal planner/execution loop:
116
+ ```bash
117
+ source .env/bin/activate
118
+ python main.py # default (plan mode)
119
+ python main.py --mode auto # run without interruptions
120
+ python main.py --mode edit # confirm sensitive operations
121
+ python main.py --model ollama/gemma4 # override model
122
+ python main.py --db /path/to/db # custom database path
123
+ python main.py --version
124
+ python main.py --help
125
+ ```
126
+
127
+ ### 2. Web-Based IDE GUI
128
+ Launches the integrated React desktop application. It opens as a local app window (via `pywebview`) or falls back to your web browser:
129
+ ```bash
130
+ source .env/bin/activate
131
+ python main.py --gui
132
+ ```
133
+
134
+ ### 3. Stdin/Stdout JSON Protocol Server
135
+ Launches the agent in background headless mode, communicating via single-line JSON messages:
136
+ ```bash
137
+ source .env/bin/activate
138
+ python main.py --stdin
139
+ ```
140
+
141
+ ---
142
+
143
+ ## Compiling Frontend GUI (Optional)
144
+
145
+ If you are developing or making changes to the React GUI, you can recompile the assets:
146
+ ```bash
147
+ cd gui_src
148
+ npm install
149
+ npm run build
150
+ ```
151
+ This builds the SPA bundle and saves it directly into the Python package distribution at `opalacoder/gui/`.
152
+
153
+ ## Project Flow
154
+
155
+ ```text
156
+ main() or `--gui` (server mode)
157
+
158
+ ├── startup_menu() ───────── Load/Create project, discover skills (via skills.yaml)
159
+
160
+ └── repl_loop() ──────────── Instantiate MemGPT chat-orchestrator
161
+
162
+ ├── User enters command (e.g. `/help`, `/undo`) ── Dispatched to CLI commands
163
+
164
+ └── User enters demand ────────────────────────── MemGPT.run(user_input)
165
+
166
+ ├── Direct chat (greetings, project status, general questions)
167
+
168
+ └── Request matches active skill ───────────── run_skill(name, context)
169
+
170
+ ├── Instantiate ephemeral sub-agent (LLMAgentBlock)
171
+ ├── Sub-agent loads SKILL.md and Level 3 scripts (e.g. implement-feature)
172
+ ├── Sub-agent executes with tools, talks to user (dialogue interceptor)
173
+ └── Return result to MemGPT orchestrator
174
+ ```
175
+
176
+ ---
177
+
178
+ ## Configuration (`agents.yaml`)
179
+
180
+ The main configuration file. Key fields and role overrides:
181
+
182
+ ```yaml
183
+ default: ollama/ministral-3:14b # default model for all agents
184
+ alternative: ollama/ministral-3:14b # model for complex tasks
185
+
186
+ llm_defaults:
187
+ temperature: 1.0
188
+ max_tokens: 8128
189
+ num_ctx: 8192
190
+
191
+ agents:
192
+ # The fixed chat-orchestrator of the skills-oriented architecture.
193
+ memgpt:
194
+ temperature: 1.0
195
+ num_ctx: 16384
196
+ max_heartbeats: 20
197
+
198
+ # drives the plan→execute→review loop inside the implement-feature skill
199
+ orchestrator:
200
+ temperature: 1.0
201
+ num_ctx: 16384
202
+ max_heartbeats: 20
203
+ strategy: workflow
204
+
205
+ # executes each task command with code editing tools
206
+ worker:
207
+ temperature: 1.0
208
+ max_tokens: 8128
209
+ num_ctx: 16384
210
+ reasoning_effort: "none" # Must stay "none" for tool-calling integration
211
+ ```
212
+
213
+ Full per-agent overrides for `temperature`, `max_tokens`, `num_ctx`, `reasoning_effort`, and `debug` are supported for every agent role.
214
+
215
+ ---
216
+
217
+ ## Benchmark
218
+
219
+ A JS bug-fix benchmark is included in `scripts/`:
220
+
221
+ ```bash
222
+ # Collect instances from GitHub (requires gh CLI authenticated)
223
+ python scripts/collect_jsbench.py --limit 50 --out datasets/jsbench
224
+
225
+ # Evaluate OpalaCoder on collected instances
226
+ python scripts/eval_jsbench.py --limit 10
227
+ ```
228
+
229
+ Results are written to `datasets/jsbench_results.json` with per-instance pass/fail and a summary fix rate.
230
+
231
+ ---
232
+
233
+ ## Build & Test
234
+
235
+ ```bash
236
+ python -m pytest tests/ -q
237
+ ```
238
+
239
+ ---
240
+
241
+ ## License
242
+
243
+ MIT
@@ -1,13 +1,8 @@
1
- default: ollama/gemma4:latest
2
- alternative: ollama/gemma4:latest
3
-
4
- complexity_inference_mode: double
5
- git_strategy: auto
6
- response_mode: "last"
7
-
8
- heartbeats_scale_factor: 1
1
+ default: ollama/ministral-3:14b
2
+ alternative: ollama/ministral-3:14b
9
3
 
10
4
  # Global LLM defaults applied to all agents unless overridden below.
5
+ # Non-agent settings (git_strategy, vector_index, etc.) live in config.yaml
11
6
  llm_defaults:
12
7
  temperature: 1.0
13
8
  max_tokens: 8128
@@ -16,13 +11,10 @@ llm_defaults:
16
11
  # Per-agent overrides. Only fields listed here are overridden;
17
12
  # everything else falls back to llm_defaults.
18
13
  #
19
- # Roles:
20
- # intent_classifier classifies user intent (greetings/question/plan/chat)
21
- # complexity_evaluator decides default vs alternative model
22
- # chat_agent conversational assistant with memory
23
- # landscape_planner — high-level strategic planner
24
- # refinement_agent — refines plan based on user feedback
25
- # skill_selector — routes request to the appropriate skills
14
+ # Roles (skills-oriented architecture):
15
+ # memgpt fixed chat-orchestrator: converses + delegates via run_skill
16
+ # landscape_planner high-level strategic planner (inside implement-feature)
17
+ # refinement_agent refines plan based on user feedback (inside implement-feature)
26
18
  # orchestrator — drives the plan→execute→review loop (JSON oracle calls)
27
19
  # worker — LLMAgentBlock that executes each task command with tools
28
20
 
@@ -33,36 +25,16 @@ agents:
33
25
  # reasoning field, leaving message.content empty and causing silent misclassification
34
26
  # (ollama issue #15288). Leave unset for planning/execution agents.
35
27
 
36
- intent_classifier:
37
- temperature: 0
38
- max_tokens: 20
39
- num_ctx: 2048
40
- reasoning_effort: "none"
41
-
42
- complexity_evaluator:
43
- temperature: 0
44
- max_tokens: 64
45
- num_ctx: 2048
46
- reasoning_effort: "none"
47
-
48
- chat_agent:
28
+ # memgpt = the fixed chat-orchestrator of the skills-oriented architecture.
29
+ # It converses AND delegates to skills via run_skill, so a single turn may spend
30
+ # several heartbeats (read memory + run_skill + send_message, plus retries). A
31
+ # larger budget and context keep multi-turn skill sessions from being cut off.
32
+ memgpt:
49
33
  temperature: 1.0
50
- max_tokens: 2048
51
- num_ctx: 8192
52
- max_heartbeats: 10
34
+ num_ctx: 16384
35
+ max_heartbeats: 20
53
36
  debug: false
54
37
 
55
- # enricher = chat_agent running in Mode A (silent memory-retrieval pass).
56
- # reasoning_effort must be "none": thinking leaves tool_calls empty (ollama issue #15288).
57
- # chat_agent (synthesizer / Mode B) has no such restriction.
58
- enricher:
59
- temperature: 0.3
60
- max_tokens: 1024
61
- num_ctx: 8192
62
- max_heartbeats: 10
63
- debug: false
64
- reasoning_effort: "none"
65
-
66
38
  landscape_planner:
67
39
  temperature: 1.0
68
40
  num_ctx: 8192
@@ -73,12 +45,6 @@ agents:
73
45
  num_ctx: 8192
74
46
  reasoning_effort: "none"
75
47
 
76
- skill_selector:
77
- temperature: 0
78
- max_tokens: 64
79
- num_ctx: 4096
80
- reasoning_effort: "none"
81
-
82
48
  orchestrator:
83
49
  temperature: 1.0
84
50
  num_ctx: 16384
@@ -0,0 +1,13 @@
1
+ # OpalaCoder — non-agent configuration
2
+ # Agent model/LLM settings live in agents.yaml
3
+
4
+ git_strategy: auto
5
+ response_mode: "last"
6
+ heartbeats_scale_factor: 1
7
+
8
+ vector_index:
9
+ embedding_model: ollama/nomic-embed-text
10
+ embedding_fallback: sentence-transformers/all-MiniLM-L6-v2
11
+ chunk_size: 500 # max lines per chunk (one file per chunk)
12
+ chunk_overlap: 50 # overlap lines between adjacent chunks of the same file
13
+ top_k: 10 # number of chunks returned by retrieval