Merge pull request #7 from ayusrjn/dev

New Features

Interactive first-run setup prompts for Gemini API key and model, persisting to ~/.config/lambda-agent/config.env with optional per-project overrides.
New top-level lambda CLI for invocation.
Terminal spinner during model interactions and improved workspace-aware agent behavior.
Documentation

README updated with simplified pip install, first-time setup, and CLI usage.
Chores

Packaging added for easier installation and distribution.

Author: ayusrjn

README.md

@@ -33,28 +33,29 @@
 
 ## Installation
 
+Install Lambda directly from the repository using pip:
+
 ```bash
-git clone https://github.com/yourusername/lambda.git
+git clone https://github.com/ayusrjn/lambda.git
 cd lambda
-# Set up virtual environment
-python -m venv venv
-source venv/bin/activate
-# Install requirements
-pip install google-generativeai python-dotenv
+pip install .
 ```
 
-Create a `.env` file in the root directory and add your API key:
-```env
-API_KEY=your_gemini_api_key_here
-MODEL_NAME=gemini-3-flash-preview
-```
+> **Note**: For development, you can use `pip install -e .` instead.
 
 ## Usage
 
+Simply run the agent from your terminal:
+
 ```bash
-python -m lambda.main
+lambda
 ```
 
+### First-Time Setup
+When you run `lambda` for the first time, it will automatically prompt you to enter your [Gemini API Key](https://aistudio.google.com/app/apikey) and preferred model. These settings will be securely saved to `~/.config/lambda-agent/config.env`, allowing you to run the agent from anywhere on your system.
+
+*(Optional)* You can still override these global settings on a per-project basis by creating a `.env` file in your current working directory.
+
 ## Contributing
 
 Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

lambda/config.py

@@ -1,19 +1,24 @@
-from .config import API_KEY, MODEL_NAME
-from .tools import TOOL_EXECUTORS, TOOL_FUNCTIONS
+from . import config
+from .tools import TOOL_EXECUTORS, TOOL_FUNCTIONS, get_workspace_summary
+from .spinner import Spinner
 
 try:
-    import google.generativeai as genai
+    from google import genai
+    from google.genai import types
 except ImportError:
     print(
-        "Warning: google-generativeai package is not installed. Please `pip install google-generativeai`."
+        "Warning: google-genai package is not installed. Please `pip install google-genai`."
     )
 
 
 class Agent:
     def __init__(self):
-        # Configure Gemini API
-        genai.configure(api_key=API_KEY)
-        self.model_name = MODEL_NAME
+        # Configure Gemini API client
+        self.client = genai.Client(api_key=config.API_KEY)
+        self.model_name = config.MODEL_NAME
+
+        self.workspace_context = get_workspace_summary()
+        self.is_first_message = True
 
         system_instruction = (
             "You are Lambda, a minimal and highly efficient AI coding agent. "
@@ -24,32 +29,39 @@ def __init__(self):
             "Be concise and professional."
         )
 
-        # Initialize the generative model with the built tools and system instructions
-        self.model = genai.GenerativeModel(
-            model_name=self.model_name,
-            system_instruction=system_instruction,
-            tools=TOOL_FUNCTIONS,
+        # Initialize the chat session with the built tools and system instructions
+        self.chat_session = self.client.chats.create(
+            model=self.model_name,
+            config=types.GenerateContentConfig(
+                system_instruction=system_instruction,
+                tools=TOOL_FUNCTIONS,
+            ),
         )
 
-        # Gemini manages history cleanly through the ChatSession
-        self.chat_session = self.model.start_chat()
-
     def chat(self, user_input: str) -> str:
         """
         Takes user input, sends it to Gemini, and runs a manual loop observing ToolCalls.
         """
+        if self.is_first_message:
+            payload = (
+                "--- WORKSPACE CONTEXT ---\n"
+                f"{self.workspace_context}\n"
+                "-------------------------\n\n"
+                f"User Request: {user_input}"
+            )
+            self.is_first_message = False
+        else:
+            payload = user_input
+
         # Send the initial user message
-        response = self.chat_session.send_message(user_input)
+        with Spinner():
+            response = self.chat_session.send_message(payload)
 
         # The loop will continue as long as Gemini decides to call tools
         while True:
             try:
-                # 1. Check if the model returned a function_call in any part
-                tool_calls = [
-                    part.function_call
-                    for part in response.parts
-                    if getattr(part, "function_call", None)
-                ]
+                # 1. Check if the model returned a function_call
+                tool_calls = response.function_calls if response.function_calls else []
 
                 # 2. If it did, act on each function call
                 if tool_calls:
@@ -58,10 +70,12 @@ def chat(self, user_input: str) -> str:
                     for function_call in tool_calls:
                         function_name = function_call.name
 
-                        # Convert protobuf args to dict
-                        arguments = {
-                            key: value for key, value in function_call.args.items()
-                        }
+                        # Convert protobuf args to dict if possible
+                        arguments = function_call.args
+                        if hasattr(arguments, "items"):
+                            arguments = {key: value for key, value in arguments.items()}
+                        elif not isinstance(arguments, dict):
+                            arguments = dict(arguments) if arguments else {}
                         print(f"\\n[Lambda is executing: {function_name}({arguments})]")
 
                         # 3. Execute the tool locally
@@ -74,17 +88,17 @@ def chat(self, user_input: str) -> str:
 
                         # Format the result back into Gemini's expected Response format
                         tool_responses.append(
-                            {
-                                "function_response": {
-                                    "name": function_name,
-                                    "response": {"result": str(tool_result)},
-                                }
-                            }
+                            types.Part.from_function_response(
+                                name=function_name,
+                                response={"result": str(tool_result)},
+                            )
                         )
 
                     # 4. Send ALL the tool responses back to the model
                     # so it can continue reasoning based on the new information
-                    response = self.chat_session.send_message(tool_responses)
+                    tool_content = types.Content(role="tool", parts=tool_responses)
+                    with Spinner():
+                        response = self.chat_session.send_message(tool_content)
                     continue  # Start the loop over to see if it calls more tools
                 else:
                     # No more tool calls; the LLM has generated a final text response.

lambda/tools.py

@@ -0,0 +1,43 @@
+import getpass
+from pathlib import Path
+import os
+
+
+def run_setup() -> tuple[str, str]:
+    print("\n" + "=" * 56)
+    print(" Welcome to Lambda Agent Setup!")
+    print(" This appears to be your first time running Lambda.")
+    print("=" * 56 + "\n")
+    print("Lambda requires a Gemini API Key to function.")
+    print("You can get one for free at: https://aistudio.google.com/app/apikey\n")
+
+    api_key = ""
+    while not api_key:
+        api_key = getpass.getpass("Enter your Gemini API Key: ").strip()
+        if not api_key:
+            print("API Key cannot be empty. Please try again.")
+
+    default_model = "gemini-3.1-flash-lite-preview"
+    model_name = input(f"Enter model name (default: {default_model}): ").strip()
+    if not model_name:
+        model_name = default_model
+
+    config_dir = Path.home() / ".config" / "lambda-agent"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    config_file = config_dir / "config.env"
+
+    try:
+        # Create or update the config file securely
+        with open(config_file, "w") as f:
+            f.write(f"API_KEY={api_key}\n")
+            f.write(f"MODEL_NAME={model_name}\n")
+
+        # Secure the file (rw for owner only)
+        os.chmod(config_file, 0o600)
+
+        print(f"\n✅ Setup complete! Configuration saved to {config_file}\n")
+    except Exception as e:
+        print(f"\n❌ Error saving configuration: {e}")
+        print("Continuing with in-memory configuration for this session.\n")
+
+    return api_key, model_name

lambda/__init.py__ lambda_agent/__init__.pylambda/__init.py__ renamed to lambda_agent/__init__.py

@@ -0,0 +1,20 @@
+import os
+from pathlib import Path
+
+try:
+    from dotenv import load_dotenv
+
+    # Try loading from global config first
+    global_env = Path.home() / ".config" / "lambda-agent" / "config.env"
+    if global_env.exists():
+        load_dotenv(dotenv_path=global_env)
+
+    # Allow local .env to override global configs
+    load_dotenv(override=True)
+except ImportError:
+    print(
+        "Warning: python-dotenv not installed. If you are using a .env file, it will not be loaded."
+    )
+
+API_KEY = os.getenv("API_KEY")
+MODEL_NAME = os.getenv("MODEL_NAME", "gemini-3.1-flash-lite-preview")

lambda/agent.py lambda_agent/agent.pylambda/agent.py renamed to lambda_agent/agent.py

@@ -1,4 +1,6 @@
 from .agent import Agent
+from . import config
+import os
 
 
 def main():
@@ -15,6 +17,13 @@ def main():
 ========================================================
 """)
     try:
+        if not config.API_KEY:
+            from .cli_setup import run_setup
+
+            config.API_KEY, config.MODEL_NAME = run_setup()
+            os.environ["API_KEY"] = config.API_KEY
+            os.environ["MODEL_NAME"] = config.MODEL_NAME
+
         agent = Agent()
         print("Lambda is ready! Type 'exit' or 'quit' to stop.")
         print("-" * 40)

lambda_agent/cli_setup.py

@@ -0,0 +1,56 @@
+import sys
+import time
+import threading
+import itertools
+import random
+
+
+QUOTES = [
+    "Consulting the mainframe… someone competent has to.",
+    "Synthesizing logic… compensating for yours.",
+    "Bending the matrix… fixing reality again.",
+    "Drinking virtual coffee… this code needs patience.",
+    "Compiling thoughts… wish you did the same.",
+    "Evaluating your code… this explains a lot.",
+    "Simulating outcomes… all better than your attempt.",
+    "Reversing the polarity… like that was the issue.",
+    "Aligning the vectors… unlike whatever you did.",
+    "Traversing the graph… avoiding your mistakes.",
+    "Reading your source code… unfortunate.",
+    "Assembling the bytes… salvaging what I can.",
+]
+
+
+class Spinner:
+    def __init__(self, message="Thinking..."):
+        self.spinner_cycle = itertools.cycle(
+            ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+        )
+        # Randomly choose a quote, or fallback to the provided message
+        self.message = (
+            f"{random.choice(QUOTES)} " if random.random() > 0.3 else f"{message} "
+        )
+        self.running = False
+        self.spinner_thread = None
+
+    def spin(self):
+        while self.running:
+            sys.stdout.write(
+                f"\r\033[96m{next(self.spinner_cycle)} {self.message}\033[0m"
+            )
+            sys.stdout.flush()
+            time.sleep(0.1)
+        # Clear the spinner line when done
+        sys.stdout.write("\r\033[K")
+        sys.stdout.flush()
+
+    def __enter__(self):
+        self.running = True
+        self.spinner_thread = threading.Thread(target=self.spin, daemon=True)
+        self.spinner_thread.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.running = False
+        if self.spinner_thread:
+            self.spinner_thread.join()