beamlab 0.1.0__py3-none-any.whl

beamlab/__init__.py

@@ -0,0 +1,24 @@
+"""
+beam/__init__.py — Package root.
+"""
+
+import os as _os
+import warnings as _warnings
+
+# Suppress HuggingFace / transformers / sentence-transformers noise.
+# Must be set BEFORE any of those packages are imported.
+_os.environ.setdefault("HF_HUB_DISABLE_PROGRESS_BARS", "1")
+_os.environ.setdefault("TRANSFORMERS_NO_ADVISORY_WARNINGS", "1")
+_os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+_os.environ.setdefault("HF_HUB_DISABLE_TELEMETRY", "1")
+_os.environ.setdefault("SAFETENSORS_FAST_GPU", "0")
+# Suppress the "BertModel LOAD REPORT" and "unauthenticated requests" warnings
+_warnings.filterwarnings("ignore", message=".*unauthenticated.*")
+_warnings.filterwarnings("ignore", message=".*LOAD REPORT.*")
+
+import logging as _logging
+for _name in ("huggingface_hub", "transformers", "sentence_transformers", "safetensors"):
+    _logging.getLogger(_name).setLevel(_logging.ERROR)
+
+__version__ = "0.1.0"
+__app_name__ = "beamlab"

beamlab/agent/__init__.py

@@ -0,0 +1 @@
+# beam/agent/__init__.py

beamlab/agent/context.py

@@ -0,0 +1,223 @@
+"""
+beam/agent/context.py — Context Engineering: builds the full ContextPacket.
+
+The ContextPacket is everything the LLM receives per-turn:
+  - system prompt (identity, rules, tool schemas)
+  - conversation history (trimmed to budget)
+  - retrieved code chunks (RAG, populated in Phase 4)
+  - workspace state (open files, cwd, OS)
+
+This module is intentionally stateless — it just assembles and returns.
+"""
+
+from __future__ import annotations
+
+import platform
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class WorkspaceState:
+    """Snapshot of the user's current working environment."""
+    cwd: str = ""
+    os: str = ""
+    python_version: str = ""
+    shell: str = ""
+    git_branch: str = "unknown"
+    git_status: str = "unknown"
+    active_task: str = "None"
+    session_id: str = "latest"
+    current_time: str = ""
+
+    @classmethod
+    def capture(cls) -> "WorkspaceState":
+        import sys
+        import os as _os
+        import subprocess
+
+        shell = _os.environ.get("SHELL", _os.environ.get("COMSPEC", "unknown"))
+        branch = "unknown"
+        status = "unknown"
+        try:
+            branch = subprocess.check_output(
+                ["git", "branch", "--show-current"], stderr=subprocess.DEVNULL, text=True
+            ).strip()
+            status = subprocess.check_output(
+                ["git", "status", "--short"], stderr=subprocess.DEVNULL, text=True
+            ).strip() or "clean"
+        except Exception:
+            pass
+
+        from datetime import datetime
+        now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+        return cls(
+            cwd=str(Path.cwd()),
+            os=platform.system(),
+            python_version=sys.version.split()[0],
+            shell=shell,
+            git_branch=branch,
+            git_status=status,
+            current_time=now,
+        )
+
+
+@dataclass
+class ContextPacket:
+    """Everything assembled for a single LLM call."""
+    system_prompt: str
+    messages: list[dict[str, str]]   # OpenAI message format
+    workspace: WorkspaceState = field(default_factory=WorkspaceState.capture)
+    token_estimate: int = 0           # rough estimate, updated by assembler
+
+
+# ---------------------------------------------------------------------------
+# System prompt template
+# ---------------------------------------------------------------------------
+
+def _load_system_prompt_template() -> str:
+    prompt_path = Path(__file__).parent.parent / "prompts" / "system_prompt.md"
+    try:
+        return prompt_path.read_text(encoding="utf-8")
+    except Exception as e:
+        return f"System prompt loading failed: {e}\\n\\nOS: {{os}}\\nCWD: {{cwd}}\\nPython: {{python_version}}\\nTools: {{tool_list}}"
+
+
+# ---------------------------------------------------------------------------
+# Assembler
+# ---------------------------------------------------------------------------
+
+class ContextAssembler:
+    """
+    Builds a ContextPacket for the LLM.
+
+    Token budget (approximate, based on 4 chars/token):
+      - System prompt: ~2K tokens
+      - History:      ~20K tokens
+      - Code chunks:  ~30K tokens (Phase 4 — RAG)
+      - Output reserve: ~8K tokens
+    """
+
+    HISTORY_CHAR_LIMIT = 80_000   # ~20K tokens
+    CHUNKS_CHAR_LIMIT  = 120_000  # ~30K tokens
+
+    def __init__(self, tools: list[str] | None = None, model_config: Any = None) -> None:
+        # Tools list will be populated in Phase 5 from the tool registry
+        self._tools = tools or []
+        self._model_config = model_config
+
+    def build(
+        self,
+        user_message: str,
+        history: list[dict[str, str]],
+        code_chunks: list[str] | None = None,
+    ) -> ContextPacket:
+        """
+        Assemble a ContextPacket for this turn.
+
+        Args:
+            user_message: The user's latest input.
+            history: Previous turns in OpenAI message format.
+            code_chunks: Relevant code snippets from RAG (Phase 4).
+        """
+        workspace = WorkspaceState.capture()
+        system_prompt = self._build_system_prompt(workspace)
+        messages = self._build_messages(user_message, history, code_chunks or [])
+        token_estimate = sum(len(m["content"]) for m in messages) // 4
+
+        return ContextPacket(
+            system_prompt=system_prompt,
+            messages=messages,
+            workspace=workspace,
+            token_estimate=token_estimate,
+        )
+
+    def _build_system_prompt(self, workspace: WorkspaceState) -> str:
+        from beamlab.tools.registry import registry
+        tool_list = registry.tool_list_for_prompt()
+        
+        # ── Thinking Protocol ─────────────────────────────────────────
+        thinking_protocol = ""
+        if self._model_config and hasattr(self._model_config, "is_thinking_model"):
+            if self._model_config.is_thinking_model():
+                thinking_protocol = (
+                    "### 🧠 THINKING PROTOCOL\n"
+                    "- Before any tool call or complex response, you MUST perform an internal reasoning step.\n"
+                    "- Wrap your internal monologue in `<thinking>` tags.\n"
+                    "- Analyze the problem, identify edge cases, and verify your logic *before* acting.\n"
+                )
+
+        class SafeDict(dict):
+            def __missing__(self, key):
+                return f"{{{key}}}"
+
+        template = _load_system_prompt_template()
+        return template.format_map(SafeDict(
+            os=workspace.os,
+            cwd=workspace.cwd,
+            python_version=workspace.python_version,
+            shell=workspace.shell,
+            git_branch=workspace.git_branch,
+            git_status=workspace.git_status,
+            active_task=workspace.active_task,
+            session_id=workspace.session_id,
+            current_time=workspace.current_time,
+            tool_list=tool_list,
+            thinking_protocol=thinking_protocol,
+        ))
+
+    def _build_messages(
+        self,
+        user_message: str,
+        history: list[dict[str, str]],
+        code_chunks: list[str],
+    ) -> list[dict[str, str]]:
+        messages: list[dict[str, str]] = []
+
+        # Trim history to stay within token budget
+        trimmed_history = _trim_to_char_limit(history, self.HISTORY_CHAR_LIMIT)
+        messages.extend(trimmed_history)
+
+        # Inject relevant code chunks as context (before the user message)
+        if code_chunks:
+            chunks_text = _trim_to_char_limit(
+                [{"role": "user", "content": c} for c in code_chunks],
+                self.CHUNKS_CHAR_LIMIT,
+            )
+            # Merge all chunks into one context message
+            combined = "\n\n---\n\n".join(m["content"] for m in chunks_text)
+            messages.append({
+                "role": "user",
+                "content": f"[CONTEXT — relevant code from your codebase]\n\n{combined}",
+            })
+            messages.append({"role": "assistant", "content": "Understood, I have the context."})
+
+        # The actual user turn
+        messages.append({"role": "user", "content": user_message})
+        return messages
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _trim_to_char_limit(
+    messages: list[dict[str, str]],
+    char_limit: int,
+) -> list[dict[str, str]]:
+    """
+    Drop oldest messages until total character count is within limit.
+    Always keeps at least the most recent message.
+    """
+    total = sum(len(m["content"]) for m in messages)
+    result = list(messages)
+    while total > char_limit and len(result) > 1:
+        removed = result.pop(0)
+        total -= len(removed["content"])
+    return result

beamlab/agent/controller.py

@@ -0,0 +1,279 @@
+"""
+beam/agent/controller.py — Core agent loop (ReAct / tool-calling pattern).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+import time
+from pathlib import Path
+from typing import AsyncIterator, Any
+
+from beamlab.agent.context import ContextAssembler
+from beamlab.agent.validator import Validator
+from beamlab.config import AgentConfig
+from beamlab.llm.orchestrator import Orchestrator, OrchestratorError
+from beamlab.tools.tool_schemas import get_tool_schemas
+from beamlab.safety.guardrails import Guardrails
+
+_INPUT_CHAR_LIMIT = 50_000
+_RAG_TOP_K = 6
+_MAX_TURNS = 15
+
+logger = logging.getLogger(__name__)
+
+
+class AgentController:
+    """
+    One instance per session. Call run() for each user turn.
+    """
+
+    def __init__(
+        self,
+        config: AgentConfig,
+        orchestrator: Orchestrator,
+        tool_registry: Any, # ToolRegistry
+        project_root: Path | str = ".",
+        vector_store=None,
+        initial_history: list[dict] | None = None,
+        session: Any = None,
+    ) -> None:
+        self._config = config
+        self._orch = orchestrator
+        self._tool_registry = tool_registry
+        self._history: list[dict] = initial_history or []
+        self._project_root = Path(project_root).resolve()
+        self._vector_store = vector_store
+        self._session = session
+
+        self._context = ContextAssembler(tools=tool_registry.all_names())
+        self._validator = Validator(self._project_root)
+        self._tool_schemas = get_tool_schemas(tool_registry.all_names())
+        self._active_plan: list[str] = []
+        self._full_plan_size: int = 0
+        
+        # HITL State
+        self.auto_approve = False
+        self._guardrails = Guardrails(config.safety)
+
+    async def initialize(self):
+        """Must be called after tools are registered."""
+        # Wrap tools with safety logic, passing this controller for HITL
+        await self._guardrails.wrap_registry(self._tool_registry, self)
+
+    # ------------------------------------------------------------------
+    # HITL Interface
+    # ------------------------------------------------------------------
+
+    async def request_approval(self, name: str, params: dict) -> bool:
+        """
+        Called by Guardrails (safe_fn). 
+        Yields a PROMPT to the renderer and waits for asend() response.
+        """
+        prompt_msg = f"Approve {name}?"
+        if name == "run_command":
+            prompt_msg = f"Execute: {params.get('command', '')}"
+        elif name == "write_file":
+            prompt_msg = f"Write to: {params.get('path', '')}"
+
+        # This is a bit tricky: Guardrails is inside _execute_tool, 
+        # which is inside run(). We need to reach the 'yield' in run().
+        # We raise a special exception that run() catches to perform the yield.
+        raise NeedsApproval(name, prompt_msg)
+
+    # ------------------------------------------------------------------
+    # Main entry point
+    # ------------------------------------------------------------------
+
+    async def run(self, user_message: str) -> AsyncIterator[str]:
+        """Process one user turn. Yields protocol lines for the renderer."""
+        from beamlab.agent.memory.active_context import set_active_session, set_active_vector_store
+        set_active_session(self._session)
+        set_active_vector_store(self._vector_store)
+
+        user_message = user_message.strip()
+        if not user_message: return
+
+        # ── Context & History ─────────────────────────────────────────
+        code_chunks: list[str] = []
+        if self._vector_store and len(self._vector_store) > 0:
+            try:
+                results = self._vector_store.search(user_message, top_k=_RAG_TOP_K)
+                code_chunks = [r.chunk.text for r in results]
+            except Exception: pass
+
+        self._context._model_config = self._config.model
+        ctx = self._context.build(user_message, self._history, code_chunks=code_chunks)
+        
+        messages: list[dict] = [
+            {"role": "system", "content": ctx.system_prompt},
+            *self._history[-10:],
+            {"role": "user", "content": user_message},
+        ]
+
+        yield "STATUS:thinking\n"
+        start_time = time.time()
+        tool_call_count = 0
+        consecutive_tool_failures = 0
+        last_failed_tool = None
+
+        for turn in range(_MAX_TURNS):
+            yield "STATUS:thinking\n"
+            try:
+                stream = self._orch.chat_with_tools_stream(messages, tools=self._tool_schemas)
+                response = None
+                combined_text = ""
+                
+                async for chunk in stream:
+                    if isinstance(chunk, str):
+                        combined_text += chunk
+                        # Escape newlines to avoid breaking the line-based protocol
+                        safe_chunk = chunk.replace("\n", "<BR>")
+                        yield f"TEXT:{safe_chunk}\n"
+                    else:
+                        response = chunk
+                
+                if turn == 0:
+                    elapsed = int(time.time() - start_time)
+                    yield f"METADATA:thought_seconds:{elapsed}\n"
+
+            except OrchestratorError as e:
+                yield f"ERR:{e}\n"
+                break
+            
+            if response is None:
+                if combined_text:
+                    yield "STATUS:responding\n"
+                    self._history.append({"role": "user", "content": user_message})
+                    self._history.append({"role": "assistant", "content": combined_text})
+                    yield "STATUS:done\n"
+                    return
+                break
+
+            # ── Check for Plan ──
+            plan_match = re.search(r"<plan>([\s\S]*?)</plan>", combined_text)
+            if plan_match and not self._active_plan:
+                lines = [s.strip() for s in plan_match.group(1).split("\n") if s.strip()]
+                self._active_plan = [re.sub(r"^\d+[\.\)]\s*", "", s) for s in lines]
+                self._full_plan_size = len(self._active_plan)
+                yield f"PLAN:{'|'.join(self._active_plan)}\n"
+                yield "PLAN_PTR:0\n"
+                yield "STATUS:planning\n"
+
+            # ── Process Step Completion ──
+            if not response.has_tool_calls:
+                if self._active_plan:
+                    self._active_plan.pop(0)
+                    yield f"PLAN_PTR:{self._full_plan_size - len(self._active_plan)}\n"
+
+                if not self._active_plan:
+                    yield "STATUS:responding\n"
+                    self._history.append({"role": "user", "content": user_message})
+                    self._history.append({"role": "assistant", "content": combined_text})
+                    yield "STATUS:done\n"
+                    break
+                else:
+                    messages.append({"role": "assistant", "content": combined_text})
+                    messages.append({"role": "user", "content": f"Proceeding to next step: {self._active_plan[0]}"})
+                    continue
+
+            # ── Execute Tools ─────────────────────────────────────────
+            yield "STATUS:executing\n"
+            assistant_msg = {
+                "role": "assistant",
+                "content": response.text or None,
+                "tool_calls": [
+                    {
+                        "id": tc.id,
+                        "type": "function",
+                        "function": {"name": tc.name, "arguments": json.dumps(tc.arguments)},
+                    }
+                    for tc in response.tool_calls if tc.name # DEFENSIVE
+                ]
+            }
+            messages.append(assistant_msg)
+
+            for tc in response.tool_calls:
+                if not tc.name: continue # KILL ARTIFACTS
+                tool_call_count += 1
+                yield f"TASK:t{tool_call_count:03d}:{tc.name}({_summarize_args(tc.arguments)}):{tc.name}\n"
+                
+                # HITL Loop for this tool
+                result = ""
+                while True:
+                    try:
+                        result = await self._execute_tool(tc.name, tc.arguments)
+                        break
+                    except NeedsApproval as e:
+                        # Yield the prompt and WAIT for asend() response.
+                        # The renderer will call gen.asend(answer), which makes 'answer' the result of this yield.
+                        answer = (yield f"PROMPT:t{tool_call_count:03d}:{e.message}\n")
+                        
+                        if answer == "a": # All
+                            self.auto_approve = True
+                            continue # Retry tool with global auto-approve
+                        elif answer in ("y", "yes"):
+                            # Temporary override for current tool instance
+                            self._temp_approved = True
+                            continue
+                        else:
+                            result = f"Error: User declined tool call {tc.name}."
+                            break
+
+                short = result[:300].replace("\n", " ")
+                is_error = result.startswith("Error:") or "[VALIDATE FAILED]" in result
+                yield f"RESULT:t{tool_call_count:03d}:{'err' if is_error else 'ok'}:{short}\n"
+
+                if is_error:
+                    consecutive_tool_failures += 1
+                    if consecutive_tool_failures >= 2:
+                        # Inject a recovery hint into the next turn
+                        result += "\n\n[SYSTEM HINT]: Multiple tools have failed. Please run 'ls -R' or use a file-discovery tool to re-verify the workspace state before continuing."
+                        consecutive_tool_failures = 0 # reset once hinted
+                else:
+                    consecutive_tool_failures = 0
+
+                messages.append({
+                    "role": "tool",
+                    "tool_call_id": tc.id,
+                    "content": result[:12000],
+                })
+        else:
+            yield "ERR:Agent reached maximum turns.\n"
+
+    async def _execute_tool(self, name: str, arguments: dict) -> str:
+        # ToolRegistry has as .get() method
+        tool_fn = self._tool_registry.get(name)
+        if not tool_fn: return f"Error: unknown tool '{name}'"
+        
+        # Note: tool_fn might have been wrapped by Guardrails._wrap
+        # If so, it might raise NeedsApproval
+        if hasattr(self, "_temp_approved") and self._temp_approved:
+             # This is a bit hacky — we need to tell the wrapped fn it's approved
+             # For now, let's just use self.auto_approve or a context var
+             self._temp_approved_context = True # used by Guardrail
+        
+        try:
+            return str(await tool_fn(arguments))
+        finally:
+            if hasattr(self, "_temp_approved"): del self._temp_approved
+
+    @classmethod
+    def from_config(cls, config: AgentConfig, tool_registry: Any, project_root: Path | str = ".", vector_store=None, initial_history: list[dict] | None = None, session: Any = None) -> AgentController:
+        orch = Orchestrator.from_config(config)
+        return cls(config=config, orchestrator=orch, tool_registry=tool_registry, project_root=project_root, vector_store=vector_store, initial_history=initial_history, session=session)
+
+
+class NeedsApproval(Exception):
+    def __init__(self, tool_name: str, message: str):
+        self.tool_name = tool_name
+        self.message = message
+
+def _summarize_args(args: dict) -> str:
+    if "path" in args: return Path(args["path"]).name
+    if "query" in args: return args["query"]
+    if "command" in args: return args["command"].split(" ", 1)[0]
+    return str(args)[:40]

beamlab/agent/memory/__init__.py

@@ -0,0 +1 @@
+# beam/agent/memory/__init__.py

beamlab/agent/memory/active_context.py

@@ -0,0 +1,27 @@
+"""
+beam/agent/memory/active_context.py — Global context for tool access.
+Allows isolated tool functions to reach the current session and vector store.
+"""
+from __future__ import annotations
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from beamlab.agent.memory.session import Session
+    from beamlab.agent.memory.vector import VectorStore
+
+_active_session: Session | None = None
+_active_vector_store: VectorStore | None = None
+
+def set_active_session(session: Session | None):
+    global _active_session
+    _active_session = session
+
+def get_active_session() -> Session | None:
+    return _active_session
+
+def set_active_vector_store(store: VectorStore | None):
+    global _active_vector_store
+    _active_vector_store = store
+
+def get_active_vector_store() -> VectorStore | None:
+    return _active_vector_store