opalacoder 0.1.0__tar.gz

opalacoder-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  release:
+    types:
+      - published
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    
+    # These permissions are required for Trusted Publishing
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: pip install --upgrade pip build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # To use Trusted Publishing, you need to configure your PyPI project 
+        # to trust this GitHub repository and workflow.

opalacoder-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+*.env
+.env
+*.env*
+.venv
+*.venv
+node_modules
+plan.md
+

opalacoder-0.1.0/AGENT.md

@@ -0,0 +1,31 @@
+# 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 `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.
+
+## 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.0/ALGS.md

@@ -0,0 +1,47 @@
+# OpalaCoder Algorithms
+
+This document describes the core algorithmic logic and decision flows adopted in OpalaCoder's architecture.
+
+## 1. Double Inference Complexity Algorithm and Dynamic Budgeting
+
+OpalaCoder implements an innovative model known as **Two-Stage Predictive Budgeting** to ensure maximum financial and resolutive efficiency for LLM agents. The goal of this algorithm is to avoid wasting tokens from expensive models on initial planning if the task is trivial, but without compromising the execution if the detailed plan reveals architectural complexities.
+
+The execution is controlled by the `complexity_inference_mode` configuration located in `agents.yaml`, operating in either `simple` or `double` modes.
+
+### Logic Flow (`double` mode)
+
+The algorithm follows these procedural steps:
+
+1. **First Stage: Pre-Plan Heuristic Inference (Strategy 1)**
+   - The user submits a prompt with their original request.
+   - The `make_complexity_evaluator` receives this raw request and returns one of two complexity labels: `"default"` or `"alternative"`.
+   - Based on this label, OpalaCoder chooses the base model that will generate the "Landscape" (Phase 1) and conduct the interactive Refinement (Phase 2).
+   - *Purpose:* Ensure that the initial cognitive capacity of the planner is equivalent to the presumed complexity by the user, saving excessive processing on short and simple requests.
+
+2. **Plan Refinement Loop**
+   - The plan goes through interactive cycles of human approval. The final outcome of this step is the `approved_plan` text.
+
+3. **Second Stage: Post-Plan JSON Evaluation (Strategy 3)**
+   - Instead of jumping straight to execution (as competing agents would do), OpalaCoder intercepts the pipeline before the orchestrator initializes.
+   - The `make_post_plan_evaluator` reads the final `approved_plan` line by line.
+   - The expected output from this agent is a strict JSON format:
+     ```json
+     {
+       "model": "default | alternative",
+       "estimated_steps": <integer>
+     }
+     ```
+   - *Execution Promotion Analysis (`model`)*: The algorithm compares the orchestrator's current model with the JSON prediction. If the JSON concludes that the architecture outlined in the plan is more complex than it seemed in the prompt (requiring `"alternative"`) and the orchestrator was set to `"default"`, the algorithm **upgrades (promotes)** the orchestrator to the alternative model *in-flight*, guaranteeing deep reasoning power for the most critical stage.
+   - *Budget Calculation (`max_heartbeats == "auto"`)*: If the orchestration config dictates static heartbeats, nothing changes. However, if it is set to `"auto"`, the ceiling calculation takes effect:
+     ```python
+     max_hb_config = min(estimated_steps * 3 + 5, 200)
+     ```
+     The estimated number of steps (e.g., read_file, write_file, run_command) semantically extracted by the LLM is multiplied by a safety margin (3) plus a fixed delta (5), always capped by the maximum logical limit (200), preventing infinite hallucination loops.
+
+4. **Execution**
+   - The `AutonomousOrchestratorStrategy` inherits the readjusted `model` and the organically calculated `max_heartbeats`, and triggers the MemGPT instances.
+
+### Fallback Mode (`simple` mode)
+If the configuration is set to `simple` or if the JSON Extraction of the *Post-Plan Evaluator* fails due to formatting hallucination:
+- In-flight model promotion is ignored.
+- If heartbeats are set to `"auto"`, a static contingency ceiling of `max_hb_config = 50` is applied.

opalacoder-0.1.0/ARCH_SUMMARY.md

@@ -0,0 +1,76 @@
+# OpalaCoder — Architecture Summary
+
+## Focus
+
+OpalaCoder is designed to work with **small language models** (e.g. Mistral-Nemo, Llama 3 8B via Ollama) as its primary target. Large models (Gemini, GPT-4, Claude) are supported as a fallback for complex tasks, but the core design prioritizes correctness and usability under constrained context windows and limited reasoning capacity.
+
+## Core Idea: Project-Centric Context Management
+
+The central abstraction is the **project**, not the session. Every interaction happens within a named project that has a fixed filesystem path. This design decision exists for one reason: **context management**.
+
+Small models degrade quickly when context is large, mixed, or unbounded. By anchoring all activity to a project, OpalaCoder can:
+
+- Inject a stable, minimal project header (`[PROJECT: name | PATH: /path]`) into every prompt instead of growing conversation state
+- Load only the skills relevant to that project type (selected at creation, not dynamically per-request)
+- Scope all file reads, writes, and commands to the project directory, eliminating ambiguity about where things should go
+- Persist history, plan state, and skill configuration per project in SQLite, keeping each LLM call focused
+
+## Architecture
+
+```
+CLI (cli.py)
+ ├── startup_menu()          — load or create project
+ ├── _create_project()       — name + path + description → LLM selects skills
+ └── repl_loop()             — main REPL; loads project-scoped skills once
+      ├── Intent classifier  — routes input to: plan | chat | question | greetings
+      ├── run_pipeline()     — triggers orchestration for planning tasks
+      │    ├── AutonomousOrchestratorStrategy   (capable models)
+      │    │    ├── generate_panorama()         phase 1: high-level plan
+      │    │    ├── refine_plan()               phase 2: user refinement loop
+      │    │    └── MemGPT agent loop           autonomous execution with tools
+      │    └── DeterministicOrchestratorStrategy (small models)
+      │         ├── generate_panorama()         phase 1
+      │         ├── refine_plan()               phase 2
+      │         ├── decompose_plan()            phase 3: subplan decomposition
+      │         ├── execute_subplans()          phase 4: WorkflowGraph execution
+      │         └── aggregate_results()         phase 5: final summary
+      └── chat_agent         — MemGPT agent for Q&A and conversation
+
+Project (project.py)
+ ├── ProjectData             — name, path, skills, description, history, plan state
+ └── ProjectStore            — SQLite CRUD for projects and message history
+
+Skills (skills.py)
+ ├── load_project_skills()   — loads only skills listed in the project
+ ├── select_skills_for_project() — LLM picks skills from description at creation
+ ├── find_skill_file()       — resolves <name>.md across skill search dirs
+ └── get_relevant_skills_llm()  — semantic router (uses project skills only)
+
+Tools (tools.py)              — file read/write, run_command, search_code, ask_human
+ └── PROJECT_PATH global     — all tools resolve paths relative to the project dir
+
+Skill search order:
+  1. {project_path}/skills/   (project-local, highest priority)
+  2. {repo_root}/skills/      (OpalaCoder built-in skills)
+  3. ~/.opalacoder/skills/        (user global skills)
+```
+
+## Key Decisions
+
+| Decision | Reason |
+|---|---|
+| Project replaces session as primary abstraction | Stable context anchor; avoids unbounded session drift |
+| Skills fixed at project creation | Prevents irrelevant skill injection; reduces prompt size for small models |
+| `/addskill` command | Lets users extend skills without restarting or recreating the project |
+| `opalacoder` skill always loaded | Core behavioral instructions must always be present |
+| Two orchestrator strategies | Small models cannot reliably drive autonomous tool loops; deterministic DAG is more reliable for them |
+| All tools use `PROJECT_PATH` as `cwd` | Eliminates path ambiguity; agent does not need to reason about absolute paths |
+| SQLite persistence | Lightweight, zero-dependency, suitable for local-first tooling |
+
+## Skill Scopes
+
+Skills carry a `scope` frontmatter field that controls where they are injected:
+
+- `all` — injected into both the intent classifier and the orchestrator
+- `orchestrator` — injected only into the planner/executor (behavioral instructions)
+- `classifier` — injected only into the intent classifier

opalacoder-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+LOAD the file AGENT.md.

opalacoder-0.1.0/GEMINI.md

@@ -0,0 +1,31 @@
+# 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 `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.
+
+## 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.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: opalacoder
+Version: 0.1.0
+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
+Requires-Dist: instructor>=1.15.1
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Description-Content-Type: text/markdown
+
+# OpalaCoder
+
+**OpalaCoder** is an autonomous coding agent with interactive planning, modular execution, and persistent project memory. It is designed to work well with small and less autonomous models while maintaining the feel of a fully autonomous agent. It is built using the **AgenticBlocks.IO** framework.
+
+---
+
+## Features
+
+### Project-Centric Context Management
+OpalaCoder centers around **projects** rather than transient chat sessions. Every interaction happens within a named project with a fixed filesystem path. This anchors the LLM context, loads only project-relevant skills, scopes all file and terminal operations, and persists history effectively for both small local models and large hosted APIs.
+
+### Advanced Semantic Router (Chain of Thought)
+Uses an LLM for semantic routing with internal reasoning (Chain of Thought). It translates user demands to English internally, correctly deduces the intent, and seamlessly routes execution even for multilingual commands, injecting only the necessary context from specific **Skills** (`skills/*.md`).
+
+### Dynamic Model Selection (Double Inference Architecture)
+OpalaCoder dynamically evaluates task complexity. For trivial tasks, it uses a fast default model (e.g., `ollama/mistral-nemo`). If the task requires architectural refactoring or advanced complex logic, it automatically falls back to a more powerful alternative model configured via API keys.
+
+### Interactive Planning
+The agent receives a natural language demand, generates a high-level landscape plan, and enters a refinement loop with the user until the plan is approved. The approved plan is then automatically decomposed into executable sub-steps (subplans).
+
+### Execution with Retry & Strategy Routing
+OpalaCoder delegates orchestration to specialized strategies. Small models use a deterministic execution pipeline (DAG), while capable models can use a fully autonomous agent loop. If a sub-step fails, the agent retries (up to a configurable limit) by injecting the previous error into the context for self-correction.
+
+### Execution Modes
+
+| Mode   | Behavior |
+|--------|---------------|
+| `plan` | Generates a plan and asks for user approval before executing (default) |
+| `auto` | Executes everything without interruptions — ideal for automated pipelines |
+| `edit` | Requests user confirmation only for sensitive operations (file creation/deletion, network calls, etc.) |
+
+### Persistent Projects and CLI Commands
+Each execution belongs to a named project with continuous memory. During the chat with OpalaCoder, you can interact with the state manager using native commands:
+- `/help` or `/h`: Shows available commands.
+- `/clear`: Clears the memory and history of the current project.
+- `/rename <new_name>`: Renames the active project.
+- `/list`: Lists all projects saved in SQLite.
+- `/load <name>` and `/delete <name>`: Loads or deletes old projects. (Deleting also asks to delete the project directory).
+- `/skills`: Lists available skills and highlights the active ones for the project.
+- `/addskill <name>` and `/rmskill <name>`: Adds or removes specific skills for the current project.
+- `/undo`: Reverts the last change made by the agent via internal shadow VCS.
+- `/commit <msg>`: Forces a commit to the local shadow git control.
+- `/exit` or `/quit`: Exits the application.
+
+### Shadow Git (VCS)
+Every project comes with an isolated "Shadow Git" (`.opalacoder/.git`) that automatically checkpoints the codebase before and after execution. This allows for safe iteration without muddying the user's main git repository, and enables the `/undo` command.
+
+### Elegant Terminal
+Formatted output with [Rich](https://github.com/Texel-io/rich): banners, progress spinners, plan panels, per-subplan status tables, and highlighted error reports.
+
+### Modular Architecture
+The code is divided into independent, easy-to-debug modules:
+
+```text
+opalacoder/
+├── config.py       Global settings (model, retries, mode, db, VCS)
+├── terminal.py     Rich output (banners, spinners, panels, tables)
+├── project.py      SQLite project management and state
+├── vcs.py          Internal shadow Git strategies (auto, hybrid, agent-driven)
+├── agents.py       LLM agent factories
+├── planner.py      Pipeline: panorama → refinement → decomposition
+├── orchestrator.py Strategy-based execution (deterministic vs autonomous)
+└── cli.py          Argparse + project bootstrap + REPL
+```
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [agenticblocks](https://github.com/gilzamir/agenticblocks) installed in the virtual environment
+- [Rich](https://github.com/Texel-io/rich): `pip install rich`
+- An accessible LLM server (e.g., [Ollama](https://ollama.com) with `mistral-nemo`, or any model supported by [litellm](https://docs.litellm.ai))
+
+---
+
+## Installation
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd OpalaCoder
+
+# Create and activate the virtual environment
+python -m venv .env
+source .env/bin/activate          # Linux/macOS
+# .env\Scripts\activate           # Windows
+
+# Install the dependencies
+pip install -r requirements.txt
+```
+
+### Environment Variables (Optional)
+
+Create a `.env` file in the project root to override defaults:
+
+```env
+# Default LLM model (any litellm supported string)
+OPALA_MODEL=ollama/mistral-nemo
+```
+
+---
+
+## How to Run
+
+```bash
+# Activate the virtual environment
+source .env/bin/activate
+
+# Default execution (plan mode)
+python main.py
+
+# Choose execution mode
+python main.py --mode auto
+python main.py --mode plan
+python main.py --mode edit
+
+# Use another model
+python main.py --model ollama/llama3
+
+# Custom database path
+python main.py --db /path/to/projects.db
+
+# Show version
+python main.py --version
+
+# Help
+python main.py --help
+```
+
+---
+
+## Project Flow
+
+```text
+1. Banner + Mode Selection
+       ↓
+2. Project Configuration
+   ├── New Project   → Name, Path, Description -> LLM selects skills
+   └── Existing      → Load context and skills
+       ↓
+3. User enters demand
+       ↓
+4. Agent generates landscape (high-level plan)
+       ↓
+5. Refinement loop (plan/edit modes)
+   ├── User approves → proceeds
+   └── User suggests changes → agent refines and loops back to step 5
+       ↓
+6. Decomposition into subplans (SP-1, SP-2, …)
+       ↓
+7. Sequential execution by dependency
+   └── For each subplan:
+       ├── Pre-run VCS checkpoint
+       ├── Executes generated code (AgenticBlocks WorkflowGraph)
+       ├── Success → Next subplan
+       └── Failure → Retry up to max_retries, then report error
+       ├── Post-run VCS checkpoint
+       ↓
+8. Aggregation: Final synthesized result of the operation
+       ↓
+9. Result displayed + project saved
+```
+
+---
+
+## Advanced Configuration
+
+### Build & Test Commands
+Run tests in the `tests` directory after implementing a new feature:
+
+```bash
+python -m pytest
+```
+
+### Change the Default Model
+
+Edit `opalacoder/config.py`:
+
+```python
+DEFAULT_MODEL = "ollama/mistral-nemo"  # change here
+```
+
+Or use the environment variable `OPALA_MODEL`.
+
+### Sensitive Operations
+
+In `opalacoder/config.py`:
+
+```python
+SENSITIVE_OPS = {
+    "write_file", "delete_file", "run_shell",
+    "send_network_request", "create_user", "delete_user",
+    # add keywords here for operations that require confirmation in edit mode
+}
+```
+
+---
+
+## Security
+
+- The `edit` mode requires explicit confirmation for operations affecting the filesystem, network, or user accounts.
+- Generated code is executed locally. For greater isolation, the `CodePlanExecutorBlock` from the AgenticBlocks library supports execution in a Docker container — edit `make_executor_block` in `opalacoder/agents.py` changing `execution_mode="local"` to `execution_mode="docker"`.
+- Never run the agent in `auto` mode with access to production systems without reviewing the generated subplans.
+
+---
+
+## License
+
+MIT

opalacoder-0.1.0/README.md

@@ -0,0 +1,210 @@
+# OpalaCoder
+
+**OpalaCoder** is an autonomous coding agent with interactive planning, modular execution, and persistent project memory. It is designed to work well with small and less autonomous models while maintaining the feel of a fully autonomous agent. It is built using the **AgenticBlocks.IO** framework.
+
+---
+
+## Features
+
+### Project-Centric Context Management
+OpalaCoder centers around **projects** rather than transient chat sessions. Every interaction happens within a named project with a fixed filesystem path. This anchors the LLM context, loads only project-relevant skills, scopes all file and terminal operations, and persists history effectively for both small local models and large hosted APIs.
+
+### Advanced Semantic Router (Chain of Thought)
+Uses an LLM for semantic routing with internal reasoning (Chain of Thought). It translates user demands to English internally, correctly deduces the intent, and seamlessly routes execution even for multilingual commands, injecting only the necessary context from specific **Skills** (`skills/*.md`).
+
+### Dynamic Model Selection (Double Inference Architecture)
+OpalaCoder dynamically evaluates task complexity. For trivial tasks, it uses a fast default model (e.g., `ollama/mistral-nemo`). If the task requires architectural refactoring or advanced complex logic, it automatically falls back to a more powerful alternative model configured via API keys.
+
+### Interactive Planning
+The agent receives a natural language demand, generates a high-level landscape plan, and enters a refinement loop with the user until the plan is approved. The approved plan is then automatically decomposed into executable sub-steps (subplans).
+
+### Execution with Retry & Strategy Routing
+OpalaCoder delegates orchestration to specialized strategies. Small models use a deterministic execution pipeline (DAG), while capable models can use a fully autonomous agent loop. If a sub-step fails, the agent retries (up to a configurable limit) by injecting the previous error into the context for self-correction.
+
+### Execution Modes
+
+| Mode   | Behavior |
+|--------|---------------|
+| `plan` | Generates a plan and asks for user approval before executing (default) |
+| `auto` | Executes everything without interruptions — ideal for automated pipelines |
+| `edit` | Requests user confirmation only for sensitive operations (file creation/deletion, network calls, etc.) |
+
+### Persistent Projects and CLI Commands
+Each execution belongs to a named project with continuous memory. During the chat with OpalaCoder, you can interact with the state manager using native commands:
+- `/help` or `/h`: Shows available commands.
+- `/clear`: Clears the memory and history of the current project.
+- `/rename <new_name>`: Renames the active project.
+- `/list`: Lists all projects saved in SQLite.
+- `/load <name>` and `/delete <name>`: Loads or deletes old projects. (Deleting also asks to delete the project directory).
+- `/skills`: Lists available skills and highlights the active ones for the project.
+- `/addskill <name>` and `/rmskill <name>`: Adds or removes specific skills for the current project.
+- `/undo`: Reverts the last change made by the agent via internal shadow VCS.
+- `/commit <msg>`: Forces a commit to the local shadow git control.
+- `/exit` or `/quit`: Exits the application.
+
+### Shadow Git (VCS)
+Every project comes with an isolated "Shadow Git" (`.opalacoder/.git`) that automatically checkpoints the codebase before and after execution. This allows for safe iteration without muddying the user's main git repository, and enables the `/undo` command.
+
+### Elegant Terminal
+Formatted output with [Rich](https://github.com/Texel-io/rich): banners, progress spinners, plan panels, per-subplan status tables, and highlighted error reports.
+
+### Modular Architecture
+The code is divided into independent, easy-to-debug modules:
+
+```text
+opalacoder/
+├── config.py       Global settings (model, retries, mode, db, VCS)
+├── terminal.py     Rich output (banners, spinners, panels, tables)
+├── project.py      SQLite project management and state
+├── vcs.py          Internal shadow Git strategies (auto, hybrid, agent-driven)
+├── agents.py       LLM agent factories
+├── planner.py      Pipeline: panorama → refinement → decomposition
+├── orchestrator.py Strategy-based execution (deterministic vs autonomous)
+└── cli.py          Argparse + project bootstrap + REPL
+```
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [agenticblocks](https://github.com/gilzamir/agenticblocks) installed in the virtual environment
+- [Rich](https://github.com/Texel-io/rich): `pip install rich`
+- An accessible LLM server (e.g., [Ollama](https://ollama.com) with `mistral-nemo`, or any model supported by [litellm](https://docs.litellm.ai))
+
+---
+
+## Installation
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd OpalaCoder
+
+# Create and activate the virtual environment
+python -m venv .env
+source .env/bin/activate          # Linux/macOS
+# .env\Scripts\activate           # Windows
+
+# Install the dependencies
+pip install -r requirements.txt
+```
+
+### Environment Variables (Optional)
+
+Create a `.env` file in the project root to override defaults:
+
+```env
+# Default LLM model (any litellm supported string)
+OPALA_MODEL=ollama/mistral-nemo
+```
+
+---
+
+## How to Run
+
+```bash
+# Activate the virtual environment
+source .env/bin/activate
+
+# Default execution (plan mode)
+python main.py
+
+# Choose execution mode
+python main.py --mode auto
+python main.py --mode plan
+python main.py --mode edit
+
+# Use another model
+python main.py --model ollama/llama3
+
+# Custom database path
+python main.py --db /path/to/projects.db
+
+# Show version
+python main.py --version
+
+# Help
+python main.py --help
+```
+
+---
+
+## Project Flow
+
+```text
+1. Banner + Mode Selection
+       ↓
+2. Project Configuration
+   ├── New Project   → Name, Path, Description -> LLM selects skills
+   └── Existing      → Load context and skills
+       ↓
+3. User enters demand
+       ↓
+4. Agent generates landscape (high-level plan)
+       ↓
+5. Refinement loop (plan/edit modes)
+   ├── User approves → proceeds
+   └── User suggests changes → agent refines and loops back to step 5
+       ↓
+6. Decomposition into subplans (SP-1, SP-2, …)
+       ↓
+7. Sequential execution by dependency
+   └── For each subplan:
+       ├── Pre-run VCS checkpoint
+       ├── Executes generated code (AgenticBlocks WorkflowGraph)
+       ├── Success → Next subplan
+       └── Failure → Retry up to max_retries, then report error
+       ├── Post-run VCS checkpoint
+       ↓
+8. Aggregation: Final synthesized result of the operation
+       ↓
+9. Result displayed + project saved
+```
+
+---
+
+## Advanced Configuration
+
+### Build & Test Commands
+Run tests in the `tests` directory after implementing a new feature:
+
+```bash
+python -m pytest
+```
+
+### Change the Default Model
+
+Edit `opalacoder/config.py`:
+
+```python
+DEFAULT_MODEL = "ollama/mistral-nemo"  # change here
+```
+
+Or use the environment variable `OPALA_MODEL`.
+
+### Sensitive Operations
+
+In `opalacoder/config.py`:
+
+```python
+SENSITIVE_OPS = {
+    "write_file", "delete_file", "run_shell",
+    "send_network_request", "create_user", "delete_user",
+    # add keywords here for operations that require confirmation in edit mode
+}
+```
+
+---
+
+## Security
+
+- The `edit` mode requires explicit confirmation for operations affecting the filesystem, network, or user accounts.
+- Generated code is executed locally. For greater isolation, the `CodePlanExecutorBlock` from the AgenticBlocks library supports execution in a Docker container — edit `make_executor_block` in `opalacoder/agents.py` changing `execution_mode="local"` to `execution_mode="docker"`.
+- Never run the agent in `auto` mode with access to production systems without reviewing the generated subplans.
+
+---
+
+## License
+
+MIT