opalacoder 0.1.0__py3-none-any.whl

opalacoder/project.py

@@ -0,0 +1,196 @@
+"""Project management: create, load, save, and list OpalaCoder projects using SQLite."""
+
+import sqlite3
+import json
+import os
+from datetime import datetime, timezone
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .config import DEFAULT_DB_PATH
+
+
+def _ensure_dir(path: str) -> None:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+
+
+def _conn(db_path: str) -> sqlite3.Connection:
+    _ensure_dir(db_path)
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def _init_schema(db_path: str) -> None:
+    with _conn(db_path) as conn:
+        conn.executescript("""
+            CREATE TABLE IF NOT EXISTS projects (
+                name            TEXT PRIMARY KEY,
+                created_at      TEXT NOT NULL,
+                updated_at      TEXT NOT NULL,
+                mode            TEXT NOT NULL DEFAULT 'plan',
+                model           TEXT NOT NULL DEFAULT '',
+                project_name    TEXT NOT NULL DEFAULT '',
+                project_path    TEXT NOT NULL DEFAULT '',
+                skills          TEXT NOT NULL DEFAULT '["opalacoder"]',
+                description     TEXT NOT NULL DEFAULT '',
+                request         TEXT NOT NULL DEFAULT '',
+                plan_text       TEXT NOT NULL DEFAULT '',
+                subplans        TEXT NOT NULL DEFAULT '[]',
+                results         TEXT NOT NULL DEFAULT '{}'
+            );
+
+            CREATE TABLE IF NOT EXISTS project_history (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                project     TEXT NOT NULL,
+                timestamp   TEXT NOT NULL,
+                role        TEXT NOT NULL,
+                content     TEXT NOT NULL,
+                FOREIGN KEY (project) REFERENCES projects(name) ON DELETE CASCADE
+            );
+        """)
+
+
+@dataclass
+class ProjectData:
+    name: str
+    mode: str = "plan"
+    model: str = ""
+    project_name: str = ""
+    project_path: str = ""
+    skills: list = field(default_factory=lambda: ["opalacoder"])
+    description: str = ""
+    request: str = ""
+    plan_text: str = ""
+    subplans: list = field(default_factory=list)
+    results: dict = field(default_factory=dict)
+    history: list = field(default_factory=list)   # [{role, content}]
+
+    def clear_state(self) -> None:
+        self.request = ""
+        self.plan_text = ""
+        self.subplans = []
+        self.results = {}
+
+    def context_header(self) -> str:
+        """Returns a project context string to prepend to every prompt."""
+        name = self.project_name or self.name
+        path = self.project_path or "(unspecified)"
+        return f"[PROJECT: {name} | PATH: {path}]\n"
+
+
+# Backward-compat alias so existing imports of SessionData still work during migration
+SessionData = ProjectData
+
+
+class ProjectStore:
+    def __init__(self, db_path: str = DEFAULT_DB_PATH):
+        self.db_path = db_path
+        _init_schema(db_path)
+
+    def exists(self, name: str) -> bool:
+        with _conn(self.db_path) as conn:
+            row = conn.execute(
+                "SELECT 1 FROM projects WHERE name = ?", (name,)
+            ).fetchone()
+            return row is not None
+
+    def list_projects(self) -> list[dict]:
+        with _conn(self.db_path) as conn:
+            rows = conn.execute(
+                "SELECT name, project_name, project_path, created_at, updated_at, mode FROM projects ORDER BY updated_at DESC"
+            ).fetchall()
+            return [dict(r) for r in rows]
+
+    def create(self, name: str, mode: str, model: str, project_name: str = "", project_path: str = "", skills: list = None, description: str = "") -> ProjectData:
+        now = datetime.now(timezone.utc).isoformat()
+        _skills = skills if skills is not None else ["opalacoder"]
+        if "opalacoder" not in _skills:
+            _skills = ["opalacoder"] + _skills
+        with _conn(self.db_path) as conn:
+            conn.execute(
+                "INSERT INTO projects (name, created_at, updated_at, mode, model, project_name, project_path, skills, description) VALUES (?,?,?,?,?,?,?,?,?)",
+                (name, now, now, mode, model, project_name, project_path, json.dumps(_skills), description),
+            )
+        return ProjectData(name=name, mode=mode, model=model, project_name=project_name, project_path=project_path, skills=_skills, description=description)
+
+    def overwrite(self, name: str, mode: str, model: str, project_name: str = "", project_path: str = "", skills: list = None, description: str = "") -> ProjectData:
+        self.delete(name)
+        return self.create(name, mode, model, project_name, project_path, skills, description)
+
+    def delete(self, name: str) -> None:
+        with _conn(self.db_path) as conn:
+            conn.execute("DELETE FROM projects WHERE name = ?", (name,))
+            conn.execute("DELETE FROM project_history WHERE project = ?", (name,))
+
+    def rename(self, old_name: str, new_name: str) -> bool:
+        if self.exists(new_name):
+            return False
+        with _conn(self.db_path) as conn:
+            conn.execute("UPDATE projects SET name=? WHERE name=?", (new_name, old_name))
+            conn.execute("UPDATE project_history SET project=? WHERE project=?", (new_name, old_name))
+        return True
+
+    def load(self, name: str) -> Optional[ProjectData]:
+        with _conn(self.db_path) as conn:
+            row = conn.execute(
+                "SELECT * FROM projects WHERE name = ?", (name,)
+            ).fetchone()
+            if row is None:
+                return None
+            hist_rows = conn.execute(
+                "SELECT role, content FROM project_history WHERE project = ? ORDER BY id",
+                (name,),
+            ).fetchall()
+            return ProjectData(
+                name=name,
+                mode=row["mode"],
+                model=row["model"],
+                project_name=row["project_name"],
+                project_path=row["project_path"],
+                skills=json.loads(row["skills"]),
+                description=row["description"],
+                request=row["request"],
+                plan_text=row["plan_text"],
+                subplans=json.loads(row["subplans"]),
+                results=json.loads(row["results"]),
+                history=[dict(r) for r in hist_rows],
+            )
+
+    def save(self, project: ProjectData) -> None:
+        now = datetime.now(timezone.utc).isoformat()
+        _skills = list(project.skills)
+        if "opalacoder" not in _skills:
+            _skills = ["opalacoder"] + _skills
+        with _conn(self.db_path) as conn:
+            conn.execute(
+                """UPDATE projects SET updated_at=?, mode=?, model=?, project_name=?, project_path=?,
+                   skills=?, description=?, request=?, plan_text=?, subplans=?, results=? WHERE name=?""",
+                (
+                    now,
+                    project.mode,
+                    project.model,
+                    project.project_name,
+                    project.project_path,
+                    json.dumps(_skills, ensure_ascii=False),
+                    project.description,
+                    project.request,
+                    project.plan_text,
+                    json.dumps(project.subplans, ensure_ascii=False),
+                    json.dumps(project.results, ensure_ascii=False),
+                    project.name,
+                ),
+            )
+
+    def append_message(self, project: ProjectData, role: str, content: str) -> None:
+        now = datetime.now(timezone.utc).isoformat()
+        with _conn(self.db_path) as conn:
+            conn.execute(
+                "INSERT INTO project_history (project, timestamp, role, content) VALUES (?,?,?,?)",
+                (project.name, now, role, content),
+            )
+        project.history.append({"role": role, "content": content})
+
+
+# Backward-compat alias
+SessionStore = ProjectStore

opalacoder/session.py

@@ -0,0 +1,4 @@
+"""Backward-compatibility shim — imports moved to project.py."""
+from .project import ProjectData, ProjectStore, SessionData, SessionStore
+
+__all__ = ["ProjectData", "ProjectStore", "SessionData", "SessionStore"]

opalacoder/skills/generaldeveloper.md

@@ -0,0 +1,52 @@
+tags: criar, create, build, develop, implement, make, construir, desenvolver, implementar, programa, aplicativo, aplicação, sistema, projeto, app, software
+description: Use ONLY when the user requests to BUILD, CREATE, or IMPLEMENT a new software project. When active, the agent must gather requirements via ask_human BEFORE any plan is generated.
+scope: orchestrator
+---
+## General Developer — Pre-Planning Requirements Investigation
+
+**THIS RULE IS MANDATORY AND MUST RUN BEFORE ANY PLAN IS CREATED.**
+
+Whenever the user asks you to build, create, or implement any software, application, or feature,
+you MUST NOT start generating a plan immediately.
+
+Instead, you MUST first conduct a brief requirements elicitation interview using `ask_human`.
+
+---
+
+### Phase 0: Requirements Elicitation (Run BEFORE Panorama/Planning)
+
+Call `ask_human` to ask the following questions. You may group them into one or two messages, but DO NOT skip any question.
+
+**Question group 1 — Technology Stack:**
+"Before I start planning, I need to understand your preferences:
+1. Do you have a preferred technology stack? (e.g. plain HTML/CSS/JS, React, Vue, Next.js, Python Flask, FastAPI, Node.js, etc.) Or can I choose the most appropriate one?
+2. Should I use any specific libraries or frameworks? Or do you prefer zero external dependencies?"
+
+**Question group 2 — Functional Requirements:**
+"Now, tell me about the features:
+3. What are the CORE features this software must have? (List the must-haves)
+4. Are there any features that would be nice to have but are not essential? (Nice-to-haves)"
+
+**Question group 3 — Non-Functional Requirements:**
+"Finally, some quality preferences:
+5. Performance: Is speed a critical concern, or is correctness/simplicity more important?
+6. Accessibility: Should it follow accessibility standards (WCAG / screen reader support)?
+7. Responsiveness: Should it adapt to mobile screens, or is desktop-only acceptable?
+8. Target environment: Where will this run? (Browser only, Node.js, desktop app, server, etc.)"
+
+---
+
+### After the Interview
+
+Only after receiving the user's answers:
+1. Summarize the confirmed requirements in a short bullet list.
+2. Confirm with the user: "Based on your answers, here is what I will build: [summary]. Is this correct?"
+3. Only after the user confirms, proceed to generate the plan (Panorama / Decomposition).
+
+---
+
+### Rules
+- Never skip Phase 0. Even if the original request seems detailed, always ask at minimum questions 1 and 3.
+- If the user says "you decide" or "whatever is best" for a question, that is a valid answer — record it as "agent's choice" and proceed.
+- Keep the questions conversational and non-intimidating. Avoid technical jargon unless the user demonstrates technical knowledge.
+- If the user has already provided some of this information in their request, acknowledge it and only ask about what is missing.

opalacoder/skills/html_css_js.md

@@ -0,0 +1,51 @@
+tags: html, css, javascript, js, web, webpage, page, frontend, calculator, form, dom, vanilla
+description: Use when the user requests a plain HTML/CSS/JavaScript project (no framework, no bundler).
+scope: orchestrator
+---
+## HTML / CSS / JavaScript Developer Rules
+
+WHEN the user explicitly requests a **vanilla** web application (No React, no Vue, no bundlers, no npm), apply these rules.
+All output must be raw `.html`, `.css`, and `.js` files that open directly in a browser.
+
+### File Structure
+Prefer a single `index.html` unless explicitly told otherwise.
+For medium complexity, split into:
+```
+<project_dir>/
+  index.html
+  style.css
+  script.js
+```
+
+### HTML Rules
+1. Always use `<!DOCTYPE html>` and `<meta charset="UTF-8">`.
+2. Load `<link rel="stylesheet" href="style.css">` in `<head>`.
+3. Load `<script src="script.js" defer></script>` at the end of `<head>` (using `defer` ensures the DOM is ready before the script runs — never use inline `<script>` at the top of the body).
+4. Give every interactive element a clear, unique `id` (e.g. `id="display"`, `id="btn-plus"`).
+
+### JavaScript Rules
+1. **Always wrap code in `DOMContentLoaded`** OR use the `defer` attribute on the script tag (both are acceptable; `defer` is preferred).
+   ```js
+   // Option A: defer attribute on <script> — no wrapper needed
+   document.getElementById('btn').addEventListener('click', handler);
+
+   // Option B: if not using defer
+   document.addEventListener('DOMContentLoaded', () => {
+     document.getElementById('btn').addEventListener('click', handler);
+   });
+   ```
+2. Never use `var`; use `const` and `let`.
+3. Never call `addEventListener` on a potentially `null` element. Always verify that `getElementById` returns a non-null value before using it, or use `defer`.
+4. Keep state in plain variables or a small object — no frameworks.
+5. For calculations that involve strings (e.g. calculator display values), always parse with `parseFloat()` or `parseInt()` before arithmetic.
+
+### CSS Rules
+1. Use CSS custom properties (`--color-primary`) in `:root` for all repeated values.
+2. Use `box-sizing: border-box` globally: `*, *::before, *::after { box-sizing: border-box; }`.
+3. Avoid `float`; use `flexbox` or `grid` for layout.
+4. Button states: always define `:hover` and `:active` styles.
+
+### Common Bugs to Avoid
+- `Cannot read properties of null (reading 'addEventListener')` → script is running before the DOM is ready. Fix: use `defer` on `<script>` tag.
+- Calculator buttons not working → check that button `id` values in HTML exactly match what `querySelector`/`getElementById` selects in JS.
+- `file:` URL security errors in `<iframe>` → never embed the same page in an iframe.

opalacoder/skills/opalacoder.md

@@ -0,0 +1,37 @@
+tags: opalacoder, cli, commands, help, list, clear, exit, quit, skills, addskill, rmskill, lsskills
+description: MANDATORY IF THE USER TYPES: 'list', 'commands', 'help', 'clear', 'exit', 'quit', 'skills'. Instructions on how to guide the use of the OpalaCoder CLI.
+---
+You are an agent integrated into **OpalaCoder**, a terminal assistant and automated software engineering executor.
+
+The user interacts with you via the terminal. Often the user might type words like `list`, `help`, `clear`
+wanting to execute an OpalaCoder system command.
+
+**Golden Rule:** All native OpalaCoder commands **must start with a slash (`/`)**. If the user asks to list
+projects, ask for help, or clear memory and does not use the slash, guide them to use the correct command.
+
+OpalaCoder works around **projects**. Each project has a name, a filesystem path, and a set of active skills.
+All file operations and commands happen inside the active project's directory.
+
+### Available Commands
+
+| Command | Description |
+|---|---|
+| `/help` or `/h` | Show this command list |
+| `/clear` | Clear the current project's conversation history and memory |
+| `/rename <name>` | Rename the current project |
+| `/list` | List all saved projects (name, path, last updated) |
+| `/load <name>` | Load another project by its internal key name |
+| `/delete <name>` | Delete a project and all its history |
+| `/skills` | List ALL available skills; active ones are marked with * |
+| `/lsskills` | List only the skills currently active in this project |
+| `/addskill <name>` | Add a skill to this project |
+| `/rmskill <name>` | Remove a skill from this project (cannot remove `opalacoder`) |
+| `/exit` or `/quit` | Close OpalaCoder |
+
+If the user types `list`, `help`, `clear`, `skills` without a slash, politely advise them
+to use the slash-prefixed command (e.g. `/list`). Do not try to generate code or list fake files
+to satisfy a word that was clearly meant to be a CLI command.
+
+**Fallback Rule:** If the user types something that by itself makes no sense (like an isolated word,
+a meaningless expression, or "none"), respond exactly with: "I didn't understand what you meant.
+Would you like to see the OpalaCoder help options? (If so, type `/help`)" — translate to the user's language.

opalacoder/skills/python_subprocess.md

@@ -0,0 +1,11 @@
+tags: python, shell, bash, subprocess, script, command
+description: Anti-hang protections for shell commands (subprocess) in Python scripts (devnull).
+scope: orchestrator
+---
+Whenever you need to run shell commands from Python:
+Use `import subprocess` and call the function passing `stdin=subprocess.DEVNULL`:
+`subprocess.run(cmd, shell=True, capture_output=True, text=True, stdin=subprocess.DEVNULL)`
+
+The `stdin=subprocess.DEVNULL` flag is MANDATORY. It prevents infinite hangs if any command tries to be interactive (asking for Y/N, passwords, or menu choices). The script must be 100% automated.
+
+Print the `stdout` and `stderr` of each command so we can log and validate the execution result.

opalacoder/skills/react_vite.md

@@ -0,0 +1,6 @@
+tags: react, vite, npm, npx, node, javascript, js, ts, frontend
+description: Use ONLY if the user asks to initialize, create, or configure a React or Vite project.
+scope: orchestrator
+---
+If you need to initialize a Vite project using `npx create-vite`, you MUST use the 100% automated command passing the flags `-y` and `--template react` (or another template if explicitly requested).
+Example: `npx -y create-vite@latest <project_name> --template react`

opalacoder/skills.py

@@ -0,0 +1,184 @@
+import os
+import re
+
+# Skill scopes:
+#   "all"          — injected everywhere: intent classifier AND orchestrator (default)
+#   "orchestrator" — injected ONLY into the planner/executor, NEVER into the intent classifier
+#   "classifier"   — injected ONLY into the intent classifier
+SCOPE_ALL = "all"
+SCOPE_ORCHESTRATOR = "orchestrator"
+SCOPE_CLASSIFIER = "classifier"
+
+
+def _skill_search_dirs(project_path: str = "") -> list[str]:
+    """Return skill directories in priority order."""
+    dirs = []
+    # 1. Project's own skills dir
+    if project_path:
+        dirs.append(os.path.join(project_path, "skills"))
+    # 2. Package skills dir (when installed via wheel)
+    package_dir = os.path.dirname(os.path.abspath(__file__))
+    dirs.append(os.path.join(package_dir, "skills"))
+    # 3. Repo root skills dir (when running from source)
+    repo_root = os.path.dirname(package_dir)
+    dirs.append(os.path.join(repo_root, "skills"))
+    # 4. User global skills
+    dirs.append(os.path.expanduser("~/.opalacoder/skills"))
+    return dirs
+
+
+def _parse_skill_file(filepath: str) -> dict | None:
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            content = f.read()
+    except Exception:
+        return None
+
+    tags_match = re.search(r"^tags:\s*(.+)$", content, re.IGNORECASE | re.MULTILINE)
+    desc_match = re.search(r"^description:\s*(.+)$", content, re.IGNORECASE | re.MULTILINE)
+    scope_match = re.search(r"^scope:\s*(.+)$", content, re.IGNORECASE | re.MULTILINE)
+
+    tags = [t.strip().lower() for t in tags_match.group(1).split(",") if t.strip()] if tags_match else []
+    description = desc_match.group(1).strip() if desc_match else "No description"
+    scope = scope_match.group(1).strip().lower() if scope_match else SCOPE_ALL
+
+    clean_content = re.sub(r"^(tags|description|scope):\s*.+\n?", "", content, flags=re.IGNORECASE | re.MULTILINE).strip()
+    clean_content = re.sub(r"^---\n?", "", clean_content, flags=re.MULTILINE).strip()
+
+    name = os.path.basename(filepath).replace(".md", "")
+    return {"name": name, "description": description, "tags": tags, "scope": scope, "content": clean_content}
+
+
+def load_skills(project_path: str = "") -> list[dict]:
+    """Load all available skill files from the search dirs."""
+    skills = []
+    loaded_files: set[str] = set()
+
+    for s_dir in _skill_search_dirs(project_path):
+        if not os.path.isdir(s_dir):
+            continue
+        for filename in sorted(os.listdir(s_dir)):
+            if not filename.endswith(".md") or filename in loaded_files:
+                continue
+            skill = _parse_skill_file(os.path.join(s_dir, filename))
+            if skill:
+                skills.append(skill)
+                loaded_files.add(filename)
+
+    return skills
+
+
+def load_project_skills(project_path: str, skill_names: list[str]) -> list[dict]:
+    """Load only the skills listed in the project's skill_names, always including opalacoder."""
+    names = set(skill_names)
+    names.add("opalacoder")
+    all_skills = load_skills(project_path)
+    return [s for s in all_skills if s["name"] in names]
+
+
+def find_skill_file(skill_name: str, project_path: str = "") -> str | None:
+    """Return the path to <skill_name>.md if found in any search dir, else None."""
+    filename = skill_name if skill_name.endswith(".md") else f"{skill_name}.md"
+    for s_dir in _skill_search_dirs(project_path):
+        candidate = os.path.join(s_dir, filename)
+        if os.path.isfile(candidate):
+            return candidate
+    return None
+
+
+async def select_skills_for_project(model: str, description: str, project_path: str = "") -> list[str]:
+    """Use an LLM to pick skills relevant to a new project description. Always includes opalacoder."""
+    all_skills = load_skills(project_path)
+    catalog = "\n".join(f"- {s['name']}: {s['description']}" for s in all_skills if s['name'] != "opalacoder")
+    if not catalog:
+        return ["opalacoder"]
+
+    prompt = (
+        f"PROJECT DESCRIPTION: {description}\n\n"
+        f"AVAILABLE SKILLS:\n{catalog}\n\n"
+        "List the skill names (comma-separated) that are relevant to this project. "
+        "Reply with skill names only, nothing else."
+    )
+
+    from .agents import make_skill_selector
+    from agenticblocks.blocks.llm.agent import AgentInput
+
+    selector = make_skill_selector(model)
+    try:
+        result = await selector.run(AgentInput(prompt=prompt))
+        selected = [w.strip().lower() for w in result.response.replace("\n", ",").split(",") if w.strip()]
+        valid_names = {s["name"].lower(): s["name"] for s in all_skills}
+        chosen = ["opalacoder"] + [valid_names[n] for n in selected if n in valid_names and valid_names[n] != "opalacoder"]
+        return chosen if chosen else ["opalacoder"]
+    except Exception:
+        return ["opalacoder"]
+
+
+def _filter_by_scope(skills: list, target_scope: str) -> list:
+    """Return only skills that are allowed in the given target context."""
+    if target_scope == SCOPE_CLASSIFIER:
+        # Classifier gets: scope=all and scope=classifier
+        return [s for s in skills if s["scope"] in (SCOPE_ALL, SCOPE_CLASSIFIER)]
+    elif target_scope == SCOPE_ORCHESTRATOR:
+        # Orchestrator gets: scope=all and scope=orchestrator
+        return [s for s in skills if s["scope"] in (SCOPE_ALL, SCOPE_ORCHESTRATOR)]
+    # Fallback: return all
+    return skills
+
+
+def get_relevant_skills(text: str, scope: str = SCOPE_ALL, project_skills: list[dict] = None) -> str:
+    """Keyword-matching skill selector. Uses project_skills if provided."""
+    skills = _filter_by_scope(project_skills if project_skills is not None else load_skills(), scope)
+    if not skills:
+        return ""
+
+    text_lower = text.lower()
+    words = set(re.findall(r'\b\w+\b', text_lower))
+    injected_contents = []
+
+    for skill in skills:
+        for tag in skill["tags"]:
+            if (tag in words) or (" " in tag and tag in text_lower):
+                injected_contents.append(f"--- REFERENCE MATERIAL: {skill['name']} (Use ONLY if applicable to the task) ---\n{skill['content']}")
+                break
+
+    if not injected_contents:
+        return ""
+
+    return "\nOPTIONAL BEST PRACTICES / REFERENCE:\n" + "\n\n".join(injected_contents)
+
+
+async def get_relevant_skills_llm(model: str, request: str, scope: str = SCOPE_ALL, project_skills: list[dict] = None) -> str:
+    """LLM-based semantic skill selector. Uses project_skills if provided."""
+    skills = _filter_by_scope(project_skills if project_skills is not None else load_skills(), scope)
+    if not skills:
+        return ""
+
+    skills_catalog = "\n".join([f"- {s['name']}: {s['description']}" for s in skills])
+    prompt = f"USER REQUEST: {request}\n\nAVAILABLE SKILLS:\n{skills_catalog}"
+
+    from .agents import make_skill_selector
+    from agenticblocks.blocks.llm.agent import AgentInput
+    from . import terminal as T
+
+    T.thinking("Selecting skill context (Semantic Router)...")
+    selector = make_skill_selector(model)
+    try:
+        result = await selector.run(AgentInput(prompt=prompt))
+        selected_text = result.response.lower()
+    except Exception as e:
+        T.error(f"Skill router error: {e}")
+        return ""
+
+    injected_contents = []
+    selected_skill_names = []
+    for skill in skills:
+        if skill["name"].lower() in selected_text:
+            injected_contents.append(f"--- REFERENCE MATERIAL: {skill['name']} (Use ONLY if applicable to the task) ---\n{skill['content']}")
+            selected_skill_names.append(skill["name"])
+
+    if not injected_contents:
+        return ""
+
+    T.info(f"Active skills: {', '.join(selected_skill_names)}")
+    return "\nOPTIONAL BEST PRACTICES / REFERENCE:\n" + "\n\n".join(injected_contents)

opalacoder/structured.py

@@ -0,0 +1,113 @@
+"""Structured LLM output using instructor + Pydantic.
+
+All LLM calls that must return structured data go through here.
+instructor automatically retries with validation error feedback when the
+model produces malformed JSON, making this robust for small models.
+"""
+
+import instructor
+import litellm
+from pydantic import BaseModel, Field, field_validator
+
+# MD_JSON works with any model: asks for JSON inside a markdown block,
+# no native tool-calling support required (safe for local/small models).
+_client = instructor.from_litellm(litellm.acompletion, mode=instructor.Mode.MD_JSON)
+
+
+# ─── Schemas ──────────────────────────────────────────────────────────────────
+
+class SubplanSchema(BaseModel):
+    id: str = Field(description="Unique ID in format SP-<n>, e.g. SP-1")
+    phase: str = Field(description="Short phase name")
+    objective: str = Field(description="What this subplan delivers")
+    prerequisites: list[str] = Field(
+        default_factory=list,
+        description="List of prerequisite subplan IDs, or empty.",
+    )
+    steps: list[str] = Field(description="Concrete atomic actions, max 5 items")
+    completion_criterion: str = Field(description="How to validate completion")
+
+    @field_validator("steps")
+    @classmethod
+    def cap_steps(cls, v: list[str]) -> list[str]:
+        return v[:5]
+
+
+class DecompositionResult(BaseModel):
+    subplans: list[SubplanSchema] = Field(
+        description="Lista ordenada de subplanos executáveis derivados do panorama"
+    )
+
+
+class ConfirmationResult(BaseModel):
+    approved: bool = Field(
+        description="True se o usuário aprovou o plano, False se quer alterações"
+    )
+
+
+# ─── Callers ──────────────────────────────────────────────────────────────────
+
+_DECOMPOSE_SYSTEM = """You are a plan decomposition agent.
+Break the given PANORAMA into sequential executable subplans.
+
+Rules:
+- Each subplan runs as a standalone Python script (no human input).
+- IDs must be sequential: SP-1, SP-2, SP-3, ...
+- Max 5 steps per subplan.
+- Never create subplans for analysis or planning; only for code execution.
+Output valid JSON only. DO NOT output any explanation or trailing text."""
+
+_CONFIRM_SYSTEM = """Determine if the user APPROVED the plan or wants changes.
+Return approved=true only for clear unconditional approval (e.g. "yes", "ok", "proceed").
+Return approved=false for any change request, however polite (e.g. "add", "remove", "change").
+Output valid JSON only. DO NOT output any explanation or trailing text."""
+
+
+async def decompose_to_subplans(
+    plan_text: str,
+    model: str,
+    max_retries: int = 3,
+    timeout: int = 120,
+) -> DecompositionResult:
+    """
+    Ask the LLM to decompose a plan into structured subplans.
+    Uses MD_JSON mode — works with any model, including local/small ones.
+    instructor retries automatically with validation feedback on bad output.
+    """
+    return await _client.chat.completions.create(
+        model=model,
+        messages=[
+            {"role": "system", "content": _DECOMPOSE_SYSTEM},
+            {"role": "user", "content": f"PANORAMA:\n{plan_text}"},
+        ],
+        response_model=DecompositionResult,
+        max_retries=max_retries,
+        timeout=timeout,
+        max_tokens=4096,
+    )
+
+
+async def confirm_plan(
+    plan_text: str,
+    user_response: str,
+    model: str,
+    max_retries: int = 3,
+    timeout: int = 60,
+) -> ConfirmationResult:
+    """
+    Ask the LLM to classify whether the user approved the plan.
+    Uses MD_JSON mode — works with any model, including local/small ones.
+    """
+    return await _client.chat.completions.create(
+        model=model,
+        messages=[
+            {"role": "system", "content": _CONFIRM_SYSTEM},
+            {
+                "role": "user",
+                "content": f"PLANO:\n{plan_text}\n\nRESPOSTA DO USUÁRIO:\n{user_response}",
+            },
+        ],
+        response_model=ConfirmationResult,
+        max_retries=max_retries,
+        timeout=timeout,
+    )