lambda-agent 0.1.0__py3-none-any.whl

lambda_agent/subagent.py

@@ -0,0 +1,276 @@
+"""
+Sub-Agent Module
+================
+Provides a lightweight, disposable agent that the main Lambda agent can spawn
+to perform focused tasks in parallel.  Each sub-agent gets its own Gemini chat
+session, a restricted set of tools, and a tight iteration budget.
+
+The main agent uses the ``dispatch_subagent`` tool function to fire off work.
+"""
+
+import threading
+from concurrent.futures import ThreadPoolExecutor, Future
+
+from rich.text import Text
+from rich.panel import Panel
+from rich import box
+
+from . import config
+
+try:
+    from google import genai
+    from google.genai import types
+except ImportError:
+    pass
+
+# ---------------------------------------------------------------------------
+# Shared console for sub-agent output
+# ---------------------------------------------------------------------------
+try:
+    from .spinner import console
+except ImportError:
+    from rich.console import Console
+
+    console = Console()
+
+# ---------------------------------------------------------------------------
+# Sub-agent tool set (lazy-loaded to avoid circular imports with tools.py)
+# ---------------------------------------------------------------------------
+
+# Default tools — the main agent can override per-task
+_DEFAULT_TOOL_NAMES = ["read_file", "search_repo", "run_command", "write_file"]
+
+
+def _get_tool_set() -> dict:
+    """Lazily import tool functions from tools.py to avoid circular imports."""
+    from .tools import read_file, search_repo, run_command, write_file
+
+    return {
+        "read_file": read_file,
+        "search_repo": search_repo,
+        "run_command": run_command,
+        "write_file": write_file,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Thread-safe counter for sub-agent IDs
+# ---------------------------------------------------------------------------
+_id_lock = threading.Lock()
+_next_id = 1
+
+
+def _get_next_id() -> int:
+    global _next_id
+    with _id_lock:
+        current = _next_id
+        _next_id += 1
+        return current
+
+
+# ---------------------------------------------------------------------------
+# SubAgent class
+# ---------------------------------------------------------------------------
+
+_SUBAGENT_SYSTEM_INSTRUCTION = """\
+You are a Lambda sub-agent — a focused worker spawned by the main Lambda agent \
+to complete a specific task.
+
+RULES:
+1. Complete the assigned task efficiently.  You have a maximum of {max_iter} tool \
+calls before you must produce a final answer.
+2. Your final answer MUST be a concise summary of your findings or actions — \
+no more than a few sentences.  The main agent will read this summary.
+3. You are fully capable of reading, writing, and editing files. Do so if the task demands it, but otherwise avoid unnecessary modifications.
+4. Do NOT ask the user questions — you cannot interact with the user.
+5. If you hit an error, briefly report what went wrong in your summary.
+"""
+
+MAX_SUBAGENT_ITERATIONS = 5
+RESULT_MAX_CHARS = 500
+
+
+class SubAgent:
+    """A disposable, lightweight agent that runs a short task and returns a summary."""
+
+    def __init__(
+        self,
+        task: str,
+        context: str = "",
+        tool_names: list[str] | None = None,
+        model: str | None = None,
+    ):
+        self.id = _get_next_id()
+        self.task = task
+        self.context = context
+        self.model = model or "gemini-2.0-flash-lite"
+
+        # Resolve tool set (lazy-loaded to avoid circular imports)
+        all_tools = _get_tool_set()
+        names = tool_names if tool_names else _DEFAULT_TOOL_NAMES
+        self.tool_executors: dict = {}
+        self.tool_functions: list = []
+        for name in names:
+            fn = all_tools.get(name)
+            if fn:
+                self.tool_executors[name] = fn
+                self.tool_functions.append(fn)
+
+        # Build Gemini session
+        self.client = genai.Client(api_key=config.API_KEY)
+        sys_instr = _SUBAGENT_SYSTEM_INSTRUCTION.format(
+            max_iter=MAX_SUBAGENT_ITERATIONS
+        )
+
+        chat_config = types.GenerateContentConfig(
+            system_instruction=sys_instr,
+            tools=self.tool_functions if self.tool_functions else None,
+            automatic_function_calling=types.AutomaticFunctionCallingConfig(
+                disable=True
+            ),
+        )
+        self.chat_session = self.client.chats.create(
+            model=self.model, config=chat_config
+        )
+
+    def run(self) -> str:
+        """Execute the sub-agent task and return a concise result string."""
+        # Build the initial prompt
+        parts = []
+        if self.context:
+            parts.append(f"--- CONTEXT ---\n{self.context}\n--- END CONTEXT ---\n\n")
+        parts.append(f"Task: {self.task}")
+        prompt = "".join(parts)
+
+        try:
+            response = self.chat_session.send_message(prompt)
+        except Exception as e:
+            return f"[sub-agent {self.id}] Error on initial message: {e}"
+
+        iterations = 0
+        while True:
+            iterations += 1
+            if iterations > MAX_SUBAGENT_ITERATIONS:
+                return self._clip(
+                    f"[sub-agent {self.id}] Hit iteration limit. "
+                    f"Last response: {getattr(response, 'text', '(none)')}"
+                )
+
+            try:
+                tool_calls = response.function_calls if response.function_calls else []
+
+                if tool_calls:
+                    tool_responses = []
+                    for fc in tool_calls:
+                        fn_name = fc.name
+                        args = fc.args
+                        if hasattr(args, "items"):
+                            args = {k: v for k, v in args.items()}
+                        elif not isinstance(args, dict):
+                            args = dict(args) if args else {}
+
+                        if fn_name in self.tool_executors:
+                            result = self.tool_executors[fn_name](**args)
+                        else:
+                            result = (
+                                f"Error: Tool '{fn_name}' not available to sub-agent."
+                            )
+
+                        tool_responses.append(
+                            types.Part.from_function_response(
+                                name=fn_name,
+                                response={"result": str(result)},
+                            )
+                        )
+
+                    response = self.chat_session.send_message(tool_responses)
+                    continue
+                else:
+                    # Final text response
+                    return self._clip(response.text or "(no output)")
+            except Exception as e:
+                return f"[sub-agent {self.id}] Error during tool loop: {e}"
+
+    def _clip(self, text: str) -> str:
+        """Truncate result to RESULT_MAX_CHARS."""
+        if len(text) <= RESULT_MAX_CHARS:
+            return text
+        return text[:RESULT_MAX_CHARS] + f"\n...[TRUNCATED — {len(text)} chars total]"
+
+
+# ---------------------------------------------------------------------------
+# Tool function exposed to the main agent
+# ---------------------------------------------------------------------------
+
+# Thread pool for running sub-agents concurrently
+_executor = ThreadPoolExecutor(max_workers=4, thread_name_prefix="subagent")
+
+
+def dispatch_subagent(task: str, context: str = "", tools: str = "") -> str:
+    """Spawns a lightweight sub-agent to perform a focused task and returns its result.
+
+    Use this to delegate independent, parallelizable work such as reading and
+    analyzing files, searching the repo, or running investigative commands.
+    Multiple dispatch_subagent calls in the *same turn* run in parallel.
+
+    Args:
+        task: A clear, specific description of what the sub-agent should do.
+              Must be self-contained — the sub-agent has no access to your
+              chat history.
+        context: Optional context string to give the sub-agent (e.g. file
+                 contents, prior findings).  Keep this minimal.
+        tools: Optional comma-separated list of tool names the sub-agent can
+               use.  Defaults to 'read_file,search_repo,run_command,write_file'.
+    """
+    # Parse tool list
+    tool_names = None
+    if tools.strip():
+        tool_names = [t.strip() for t in tools.split(",") if t.strip()]
+
+    agent = SubAgent(task=task, context=context, tool_names=tool_names)
+    agent_id = agent.id
+
+    # Show dispatch in the terminal
+    console.print()
+    dispatch_label = Text.assemble(
+        (" ⚡ SUB-AGENT ", "bold black on green"),
+        (f"  #{agent_id}", "bold green"),
+        ("  →  ", "dim"),
+        (task[:80] + ("…" if len(task) > 80 else ""), "green"),
+    )
+    console.print(dispatch_label)
+
+    # Run the sub-agent in a thread (blocks until done — Gemini processes
+    # all tool_calls in a batch, so parallel calls happen naturally)
+    future: Future = _executor.submit(agent.run)
+    result = future.result(timeout=120)  # 2 min hard timeout
+
+    # Show completion
+    status_label = Text.assemble(
+        (" ✓ SUB-AGENT ", "bold black on green"),
+        (f"  #{agent_id} done", "bold green"),
+    )
+    console.print(status_label)
+    console.print(
+        Panel(
+            result,
+            border_style="green",
+            box=box.SIMPLE,
+            padding=(0, 2),
+        )
+    )
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Registration dicts (imported by tools.py)
+# ---------------------------------------------------------------------------
+
+SUBAGENT_EXECUTORS = {
+    "dispatch_subagent": dispatch_subagent,
+}
+
+SUBAGENT_FUNCTIONS = [
+    dispatch_subagent,
+]

lambda_agent/tools.py

@@ -0,0 +1,217 @@
+import subprocess
+import os
+
+from rich.panel import Panel
+from rich.text import Text
+from rich.prompt import Prompt
+from rich import box
+from rich.console import Console
+
+from .scratchpad import SCRATCHPAD_EXECUTORS, SCRATCHPAD_FUNCTIONS
+from .subagent import SUBAGENT_EXECUTORS, SUBAGENT_FUNCTIONS
+
+# Use the same console as the rest of the app if available; else create one
+try:
+    from .spinner import console
+except ImportError:
+    console = Console()
+
+
+def read_file(path: str) -> str:
+    """Reads the contents of a file.
+
+    Args:
+        path: The absolute or relative path to the file.
+    """
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return f.read()
+    except Exception as e:
+        return f"Error reading file {path}: {str(e)}"
+
+
+def write_file(path: str, content: str) -> str:
+    """Writes content to a specific file path.
+
+    Args:
+        path: The path to the file to write.
+        content: The text content to write to the file.
+    """
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(content)
+        return f"Successfully wrote to {path}"
+    except Exception as e:
+        return f"Error writing to file {path}: {str(e)}"
+
+
+def run_command(command: str) -> str:
+    """Executes a shell command on the host system.
+
+    Args:
+        command: The shell command to execute.
+    """
+    try:
+        result = subprocess.run(
+            command, shell=True, capture_output=True, text=True, timeout=30
+        )
+        output = result.stdout + result.stderr
+        return output if output else "Command executed successfully with no output."
+    except subprocess.TimeoutExpired:
+        return "Error: Command timed out after 30 seconds."
+    except Exception as e:
+        return f"Error executing command: {str(e)}"
+
+
+def get_workspace_summary() -> str:
+    """Gathers git context, branch, status, recent commits, and project documentation (like README.md or rule files) to help the agent understand the whole project."""
+    summary_parts = []
+
+    # 1. Gather Git Context
+    try:
+        branch = subprocess.check_output(
+            ["git", "branch", "--show-current"], text=True, stderr=subprocess.STDOUT
+        ).strip()
+        status = subprocess.check_output(
+            ["git", "status", "-s"], text=True, stderr=subprocess.STDOUT
+        )
+        log = subprocess.check_output(
+            ["git", "log", "-n", "5", "--oneline"], text=True, stderr=subprocess.STDOUT
+        )
+
+        summary_parts.append(
+            f"### Git Context\n**Branch**: {branch}\n**Status**:\n{status if status else 'Clean'}\n**Recent Commits**:\n{log}"
+        )
+    except Exception:
+        summary_parts.append("### Git Context\nNot a git repository or git error.")
+
+    # 2. Gather Directory Structure (limited to root)
+    try:
+        files = os.listdir(".")
+        summary_parts.append(f"### Root Directory Files\n{', '.join(files)}")
+    except Exception as e:
+        summary_parts.append(f"### Directory Listing Error\n{e}")
+
+    # 3. Read important docs
+    docs_to_check = [
+        "README.md",
+        "README",
+        ".cursorrules",
+        ".agentrules",
+        ".agent/scratchpad.md",
+        "pyproject.toml",
+        "package.json",
+    ]
+    for doc in docs_to_check:
+        if os.path.exists(doc) and os.path.isfile(doc):
+            try:
+                with open(doc, "r", encoding="utf-8") as f:
+                    content = f.read()
+                    # Truncate to save tokens if massive
+                    if len(content) > 3000:
+                        content = content[:3000] + "\n...[TRUNCATED]"
+                    summary_parts.append(f"### Document: {doc}\n```\n{content}\n```")
+            except Exception:
+                pass
+
+    return "\n\n".join(summary_parts)
+
+
+def search_repo(query: str, path: str = ".") -> str:
+    """Searches for a specific string query across all text files in the repository.
+
+    Args:
+        query: The substring to search for.
+        path: The directory path to search within (defaults to current directory '.').
+    """
+    try:
+        # Use grep for faster searching.
+        # -r: recursive, -n: line numbers, -I: ignore binary files
+        # -F: fixed strings (prevents regex injection if query has special chars)
+        command = [
+            "grep",
+            "-rnIF",
+            "--exclude-dir=.git",
+            "--exclude-dir=.venv",
+            "--exclude-dir=venv",
+            "--exclude-dir=env",
+            "--exclude-dir=__pycache__",
+            "--exclude-dir=node_modules",
+            "--exclude-dir=.ruff_cache",
+            query,
+            path,
+        ]
+
+        result = subprocess.run(command, capture_output=True, text=True)
+
+        if result.returncode == 0:
+            # grep output is already in the format we want (file:line: content)
+            # but we strip it to clean it up lightly
+            results = result.stdout.strip().split("\n")
+            if not results or not results[0]:
+                return f"No matches found for '{query}'"
+
+            if len(results) > 100:
+                return (
+                    "\n".join(results[:100])
+                    + f"\n\n... and {len(results) - 100} more matches."
+                )
+            return "\n".join(results)
+        elif result.returncode == 1:
+            return f"No matches found for '{query}'"
+        else:
+            return f"Error searching repository: {result.stderr.strip()}"
+    except FileNotFoundError:
+        return "Error: 'grep' is not installed or available in PATH."
+    except Exception as e:
+        return f"Error executing search: {str(e)}"
+
+
+def ask_user(question: str) -> str:
+    """Asks the user a clarifying question and returns their answer.
+
+    Args:
+        question: The question to ask the user.
+    """
+    try:
+        console.print()
+        console.print(
+            Panel(
+                Text(question, style="bold white"),
+                border_style="yellow",
+                box=box.ROUNDED,
+                title=Text(" 🤔 Lambda asks ", style="bold black on bright_yellow"),
+                title_align="left",
+                padding=(0, 2),
+            )
+        )
+        answer = Prompt.ask(
+            "[bold bright_yellow]  Your answer[/bold bright_yellow]",
+            console=console,
+        )
+        return answer
+    except Exception as e:
+        return f"Error asking user: {str(e)}"
+
+
+# A dictionary mapping tool names to Python functions for dynamic execution
+TOOL_EXECUTORS = {
+    "read_file": read_file,
+    "write_file": write_file,
+    "run_command": run_command,
+    "search_repo": search_repo,
+    "ask_user": ask_user,
+    **SCRATCHPAD_EXECUTORS,
+    **SUBAGENT_EXECUTORS,
+}
+
+# The list of raw Python functions for the Gemini SDK to auto-generate schemas
+TOOL_FUNCTIONS = [
+    read_file,
+    write_file,
+    run_command,
+    search_repo,
+    ask_user,
+    *SCRATCHPAD_FUNCTIONS,
+    *SUBAGENT_FUNCTIONS,
+]

lambda_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: lambda-agent
+Version: 0.1.0
+Summary: Lambda - A minimal AI coding agent
+Author: Ayush Ranjan
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/ayusrjn/lambda
+Project-URL: Repository, https://github.com/ayusrjn/lambda.git
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-genai>=1.71.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.7.0
+Dynamic: license-file
+
+<p align="center">
+  <img src="images/logo.png" alt="Lambda Logo" width="120">
+</p>
+
+<h1 align="center">Lambda Agent</h1>
+
+<p align="center">
+  <strong>A minimal, function-driven AI coding assistant built for speed and simplicity.</strong>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
+  <img src="https://img.shields.io/badge/Python-3.10%2B-blue" alt="Python Version">
+  <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
+  <img src="https://img.shields.io/badge/Maintained%3F-yes-green.svg" alt="Maintained">
+</p>
+
+---
+
+<p align="center">
+  <img src="images/screen.png" alt="Lambda Interface" width="auto">
+</p>
+
+---
+
+## Overview
+
+**Lambda** is a lightweight, command-line AI coding agent driven by Google's Gemini models. Unlike massive IDE extensions or bloated web setups, Lambda lives right in your terminal. It uses a ReAct (Reasoning and Acting) loop to autonomously navigate your codebase, read and write files, run shell commands, and orchestrate complex coding tasks from a single prompt.
+
+With a beautiful UI powered by Rich, Lambda makes pair programming with AI feel fast, natural, and highly contextual.
+
+## Key Features
+
+- **Autonomous Tool Execution**: Powered by Gemini's function calling, Lambda can `read_file`, `write_file`, `search_repo`, and `run_command` directly on your host machine to get things done.
+- **Agentic Scratchpad**: Lambda uses a hidden local scratchpad (`.scratchpad/`) to draft implementation plans, think through complex logic, and maintain context across long execution chains.
+- **Stunning CLI Experience**: Built with [Rich](https://github.com/Textualize/rich), featuring distinct conversational bubbles, syntax highlighting, active token monitoring, and beautiful live spinners.
+- **Hot-Swappable Models**: Instantly switch between different Gemini models mid-conversation using the `/models` slash command.
+- **Zero-Friction Configuration**: Global configurations (`~/.config/lambda-agent/config.env`) mean you can run `lambda` in *any* directory on your machine instantly.
+
+## Installation
+
+Requires **Python 3.10+**. Install Lambda straight from the repository:
+
+```bash
+git clone https://github.com/ayusrjn/lambda.git
+cd lambda
+pip install .
+```
+
+*For local development and modifying the agent, use `pip install -e .` instead.*
+
+## Usage
+
+Spin up the agent from any directory simply by running:
+
+```bash
+lambda
+```
+
+### First-Time Setup
+On your first run, Lambda will securely prompt you for your [Gemini API Key](https://aistudio.google.com/app/apikey) and model preference. This is saved to `~/.config/lambda-agent/config.env`.
+
+*Note: You can override global settings by placing a `.env` file in your specific project directory.*
+
+### Built-in Slash Commands
+
+During your interactive session, you can use the following commands:
+- `/models` — Display a menu to hot-swap your active AI model (e.g., from Gemini Flash to Pro).
+- `/config` — Quickly update your API key mid-session.
+- `/help`   — List all available slash commands.
+- `exit` or `quit` — End the session and review your total token usage.
+
+## Under the Hood
+
+Lambda acts autonomously using an extensible set of Python tools:
+- `search_repo(query, path)`: Deep file inspection ignoring `.git`, `.venv`, and binary caches.
+- `run_command(command)`: Real shell execution (with 30s timeout guards).
+- `ask_user(question)`: Ability to explicitly pause and ask the human for clarification.
+- `read_file`, `write_file`: Direct file manipulations.
+- **Scratchpad API**: `read_scratchpad`, `write_scratchpad`, `append_scratchpad` for planning.
+
+## Contributing
+
+Contributions make the open-source community an amazing place to learn and build!
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## License & Attribution
+
+Distributed under the Apache 2.0 License. See `LICENSE` for more information.
+
+- Engine powered by [Google GenAI SDK](https://github.com/google/genai-python).
+- Lambda icon by [shohanur.rahman13](https://www.flaticon.com/authors/shohanur-rahman13) from [Flaticon](https://www.flaticon.com/free-icons/lambda)

lambda_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+lambda_agent/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lambda_agent/agent.py,sha256=6m3-26GdW_mtwe_tnUTlTUQmbSEwYXIcaI0EdVrDD48,13162
+lambda_agent/cli_setup.py,sha256=qmP42G9kZch5e3i3vtzJRCeiNppaoJ4zpJpws_2O7OI,1495
+lambda_agent/config.py,sha256=f9BjoAvpFd8nnHn_J2SmNhh3buod3ua2WHzgdDSUKIA,832
+lambda_agent/context.py,sha256=DWBUb8DJ21dbhCx3syjp47tVqr_8ak0mufdjf4Ow6R4,4641
+lambda_agent/main.py,sha256=dcCWZxS7XpyNLlHXrOYkaxER69xH8TAU-OolcT_T31s,10856
+lambda_agent/scratchpad.py,sha256=w_lID1Ntrq-caWuFTFIhnnAnFHCoKdkZgulLE7wIiXY,4622
+lambda_agent/spinner.py,sha256=06sV_GCAlhqQaCy_Qouow-HMpLWSsJNZ3ibknFzbqOM,1404
+lambda_agent/subagent.py,sha256=P6FOntn7loMVl093bSm18Wxgxq99UF48bkDlV7R2IP0,9739
+lambda_agent/tools.py,sha256=zOeSLsapR31forDvPjKmvKuko2ynGwxn-ZHyvGNu9do,6968
+lambda_agent-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+lambda_agent-0.1.0.dist-info/METADATA,sha256=YAjYGfKnqwukJy5liRYuNOKP_IUL3U5jFX3vN83w07U,5099
+lambda_agent-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+lambda_agent-0.1.0.dist-info/entry_points.txt,sha256=-VGh5epNi7PKGtyyePa75HjslMiLPj3IOS4db5r2bpg,50
+lambda_agent-0.1.0.dist-info/top_level.txt,sha256=DAiCRH5PGk9CdMWklXx332bwemnUpZ9lVjHw0h3hWgg,13
+lambda_agent-0.1.0.dist-info/RECORD,,

lambda_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lambda_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lambda = lambda_agent.main:main