Ltera-ai 1.0__py3-none-any.whl

Lterax/__init__.py

@@ -0,0 +1,12 @@
+"""
+Ltera - An agent that works on your behalf.
+
+Ltera is an open-source, pip-installable agent that works on your behalf, it uses an iterative agent loop to
+accomplish tasks.
+"""
+
+__version__ = "1.0"
+
+from Lterax.agent import Agent
+
+__all__ = ["Agent", "__version__"]

Lterax/__main__.py

@@ -0,0 +1,261 @@
+"""
+CLI entry point for Ltera.
+
+Supports two modes:
+
+1. **Single-shot**: ``python -m Ltera "your task"``
+2. **Interactive REPL**: ``python -m Ltera`` (no task argument)
+
+All configuration can be set via CLI flags or environment variables.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+import os
+from importlib.metadata import version, PackageNotFoundError
+
+from Lterax import __version__
+from Lterax.agent import Agent, AgentError, MaxIterationsError
+from Lterax.config import Config
+
+
+_RESET  = "\033[0m"
+_BOLD   = "\033[1m"
+_DIM    = "\033[2m"
+_ITALIC = "\033[3m"
+
+# Foreground colours
+_WHITE   = "\033[97m"
+_CYAN    = "\033[96m"      # bright cyan
+_BLUE    = "\033[94m"      # bright blue
+_GREEN   = "\033[92m"      # bright green
+_YELLOW  = "\033[93m"      # bright yellow
+_RED     = "\033[91m"      # bright red
+_MAGENTA = "\033[95m"      # bright magenta
+_GRAY    = "\033[90m"      # dark gray
+
+
+def _supports_color() -> bool:
+    return sys.stderr.isatty() and "NO_COLOR" not in os.environ
+
+
+def _c(text: str, *styles: str) -> str:
+    """Apply ANSI styles only when the terminal supports them."""
+    if not _supports_color():
+        return text
+    return f"{''.join(styles)}{text}{_RESET}"
+
+
+def _installed_version() -> str:
+    try:
+        return version("Ltera")
+    except PackageNotFoundError:
+        return __version__
+
+def main(argv: list | None = None) -> int:
+    """Main entry point for the Ltera CLI.
+
+    Returns 0 on success, 1 on error.
+    """
+    parser = argparse.ArgumentParser(
+        prog="Ltera",
+        description=(
+            "Ltera — an autonomous coding agent. "
+            "Give it a task and it will read, write, and explore files "
+            "to accomplish it."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "examples:\n"
+            '  Ltera "List all Python files"\n'
+            '  Ltera --model gemini-3.5-flash-thinking "Explain main.py"\n'
+            "  Ltera  # starts interactive mode\n"
+        ),
+    )
+
+    parser.add_argument(
+        "task",
+        nargs="?",
+        default=None,
+        help="Task to execute. Omit for interactive mode.",
+    )
+    parser.add_argument(
+        "--base-url",
+        default=None,
+        help=(
+            "OpenAI-compatible API base URL. "
+            "Default: http://localhost:8081/v1 (env: LTERA_BASE_URL)"
+        ),
+    )
+    parser.add_argument(
+        "--model",
+        default=None,
+        help="Model name. Default: gemini-3.5-flash (env: LTERA_MODEL)",
+    )
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        default=None,
+        help="Enable verbose/debug logging",
+    )
+    parser.add_argument(
+        "--version", "-V",
+        action="version",
+        version=f"Ltera {__version__}",
+    )
+
+    args = parser.parse_args(argv)
+
+    config_overrides = {}
+    if args.base_url is not None:
+        config_overrides["base_url"] = args.base_url
+    if args.model is not None:
+        config_overrides["model"] = args.model
+    if args.verbose is not None and args.verbose:
+        config_overrides["verbose"] = True
+
+    config = Config(**config_overrides, _explicit=set(config_overrides.keys()))
+
+    # -- Set up logging --
+    if config.verbose:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+            stream=sys.stderr,
+        )
+    else:
+        logging.basicConfig(
+            level=logging.WARNING,
+            format="%(message)s",
+            stream=sys.stderr,
+        )
+
+    # -- Start built-in server if requested --
+    if config.base_url == "auto":
+        from Lterax.server import start_background_server
+        if config.verbose:
+            sys.stderr.write("Starting built-in gemini-web2api backend...\n")
+        new_url = start_background_server()
+        config.base_url = new_url
+
+    # -- Print banner --
+    _print_banner(config)
+
+    # -- Create agent --
+    try:
+        agent = Agent(config)
+    except Exception as exc:
+        sys.stderr.write(f"\n✗ Failed to initialise agent: {exc}\n")
+        return 1
+
+    # -- Single-shot or interactive --
+    if args.task:
+        return _run_single(agent, args.task)
+    else:
+        return _run_interactive(agent)
+
+
+def _run_single(agent: Agent, task: str) -> int:
+    """Run a single task and exit."""
+    try:
+        answer = agent.run(task)
+        print(f"\n{answer}")
+        return 0
+    except MaxIterationsError as exc:
+        sys.stderr.write(f"\n✗ {exc}\n")
+        return 1
+    except AgentError as exc:
+        sys.stderr.write(f"\n✗ Agent error: {exc}\n")
+        return 1
+    except KeyboardInterrupt:
+        sys.stderr.write("\n\nInterrupted.\n")
+        return 130
+
+
+def _run_interactive(agent: Agent) -> int:
+    """Run an interactive REPL loop."""
+    sys.stderr.write(
+        "\nInteractive mode — type your task and press Enter.\n"
+        "Type 'quit' or 'exit' to leave.  Ctrl+C to cancel a task.\n\n"
+    )
+
+    while True:
+        try:
+            task = input("Ltera > ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nBye!")
+            return 0
+
+        if not task:
+            continue
+        if task.lower() in ("quit", "exit", "q"):
+            print("Tschau!")
+            return 0
+
+        try:
+            answer = agent.run(task)
+            print(f"\n{answer}\n")
+        except MaxIterationsError as exc:
+            sys.stderr.write(f"\n✗ {exc}\n\n")
+        except AgentError as exc:
+            sys.stderr.write(f"\n✗ Agent error: {exc}\n\n")
+        except KeyboardInterrupt:
+            sys.stderr.write("\n\nTask cancelled.\n\n")
+
+
+import sys
+from pathlib import Path
+
+_BANNER = r"""
+                                
+ooooo            .                                
+`888'          .o8                                
+ 888         .o888oo  .ooooo.  oooo d8b  .oooo.   
+ 888           888   d88' `88b `888""8P `P  )88b  
+ 888           888   888ooo888  888      .oP"888  
+ 888       o   888 . 888    .o  888     d8(  888  
+o888ooooood8   "888" `Y8bod8P' d888b    `Y888""8o   
+
+"""
+
+
+def _print_banner(config) -> None:
+    ver = _installed_version()
+
+    # ---- ASCII banner ----
+    if _supports_color():
+        lines = _BANNER.splitlines()
+        colors = [_CYAN, _CYAN, _BLUE, _BLUE, _MAGENTA, _MAGENTA, _BLUE]
+
+        for i, line in enumerate(lines):
+            col = colors[i] if i < len(colors) else _CYAN
+            print(_c(line, col, _BOLD), file=sys.stderr)
+    else:
+        print(_BANNER, file=sys.stderr)
+
+    # ---- Tagline row ----
+    tag = _c("  is a Simple AI Agent (without any API Keys)", _DIM)
+    ver_badge = _c(f" v{ver} ", _BOLD, _CYAN)
+    by = _c(" by Abodx9", _YELLOW)
+
+    print(f"{tag}{ver_badge}{by}", file=sys.stderr)
+
+    # ---- Runtime info ----
+    model = f"  {_c('Model:', _BLUE)}   {_c(config.model, _WHITE, _BOLD)}"
+    backend = f"  {_c('Backend:', _RED)} {_c(config.base_url, _WHITE, _BOLD)}"
+    root = f"  {_c('Root:', _GREEN)}    {_c(str(Path.cwd()), _WHITE, _BOLD)}"
+
+    print(model, file=sys.stderr)
+    print(backend, file=sys.stderr)
+    print(root, file=sys.stderr)
+
+    # ---- Separator ----
+    print(_c("  " + "─" * 52, _GRAY), file=sys.stderr)
+    print(file=sys.stderr)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

Lterax/agent.py

@@ -0,0 +1,224 @@
+"""
+Agent loop for Ltera.
+
+Usage::
+
+    from Ltera.agent import Agent
+    from Ltera.config import Config
+
+    agent = Agent(Config(project_root="."))
+    answer = agent.run("List all Python files in this project")
+    print(answer)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import sys
+from typing import Any, Dict, List, Optional
+from pathlib import Path
+
+from Lterax.config import Config
+from Lterax.llm import LLMClient, LLMError
+from Lterax.prompts import build_system_prompt
+from Lterax.sandbox import Sandbox, SandboxViolation
+from Lterax.tools import ToolError, ToolRegistry, default_registry
+
+logger = logging.getLogger("Ltera.agent")
+
+class MaxIterationsError(Exception):
+    """Raised when the agent loop exceeds the configured iteration limit."""
+
+
+class AgentError(Exception):
+    """General agent error."""
+
+class Agent:
+    """Iterative tool-calling agent.    """
+
+    def __init__(
+        self,
+        config: Optional[Config] = None,
+        registry: Optional[ToolRegistry] = None,
+    ) -> None:
+        self._config = config or Config()
+        self._registry = registry or default_registry
+
+        self._llm = LLMClient(
+            base_url=self._config.base_url,
+            model=self._config.model,
+            timeout=self._config.timeout,
+        )
+
+        self._sandbox = Sandbox(Path.cwd())
+
+        # Build the system prompt once (tools don't change mid-session).
+        self._system_prompt = build_system_prompt(
+            self._registry.list_tools()
+        )
+
+
+
+    def run(self, task: str) -> str:
+        """Execute *task* and return the agent's final answer. """
+        messages: List[Dict[str, Any]] = [
+            {"role": "system", "content": self._system_prompt},
+            {"role": "user", "content": task},
+        ]
+
+        max_iter = 7
+        consecutive_errors = 0
+        max_consecutive_errors = 3
+
+        for iteration in range(1, max_iter + 1):
+
+            try:
+                raw_reply = self._llm.chat(messages)
+            except LLMError as exc:
+                raise AgentError(f"LLM communication failed: {exc}")
+
+            if self._config.verbose:
+                logger.info("LLM reply: %s", raw_reply[:500])
+
+            action, parse_error = self._parse_action(raw_reply)
+
+            if parse_error is not None:
+                consecutive_errors += 1
+                if consecutive_errors >= max_consecutive_errors:
+                    raise AgentError(
+                        f"LLM failed to produce valid JSON "
+                        f"{max_consecutive_errors} times in a row. "
+                        f"Last response: {raw_reply[:300]}"
+                    )
+                # Ask the LLM to fix its output.
+                messages.append({"role": "assistant", "content": raw_reply})
+                messages.append({
+                    "role": "user",
+                    "content": (
+                        f"Error: {parse_error}\n\n"
+                        "Please respond with a single valid JSON object. "
+                        "Do NOT use markdown code fences."
+                    ),
+                })
+                self._print_status("⚠ Parse error, asking LLM to retry...")
+                continue
+
+            consecutive_errors = 0
+
+            if action["action"] == "final":
+                answer = action.get("answer", "")
+                return answer
+
+            tool_name = action["action"]
+            self._print_status(f"⚙ {tool_name}({self._summarise_args(action)})")
+
+            try:
+                result = self._registry.execute(
+                    tool_name, action, self._sandbox
+                )
+            except (ToolError, SandboxViolation) as exc:
+                result = f"Error: {exc}"
+                self._print_status(f"  ✗ {result}")
+            except Exception as exc:
+                result = f"Unexpected error: {type(exc).__name__}: {exc}"
+                self._print_status(f"  ✗ {result}")
+                logger.exception("Unexpected tool error")
+
+            messages.append({"role": "assistant", "content": raw_reply})
+            messages.append({
+                "role": "user",
+                "content": f"Tool result for `{tool_name}`:\n{result}",
+            })
+
+        # Exceeded iteration limit.
+        raise MaxIterationsError(
+            f"Agent did not finish within {max_iter} iterations."
+        )
+
+    @property
+    def config(self) -> Config:
+        """The agent's configuration."""
+        return self._config
+
+    @property
+    def registry(self) -> ToolRegistry:
+        """The agent's tool registry."""
+        return self._registry
+
+    def _parse_action(self, raw: str) -> tuple:
+        """Attempt to parse the LLM's response as a JSON action.
+
+        Returns ``(action_dict, None)`` on success, or
+        ``(None, error_message)`` on failure.
+        """
+        text = raw.strip()
+
+        # Strategy 1: Direct JSON parse.
+        action = self._try_parse_json(text)
+        if action is not None:
+            return self._validate_action(action)
+
+        # Strategy 2: Extract JSON from markdown code fences.
+        #   ```json\n{...}\n```  or  ```\n{...}\n```
+        fence_pattern = r"```(?:json)?\s*\n(\{.*?\})\s*\n```"
+        match = re.search(fence_pattern, text, re.DOTALL)
+        if match:
+            action = self._try_parse_json(match.group(1))
+            if action is not None:
+                return self._validate_action(action)
+
+        # Strategy 3: Find the first { ... } block.
+        brace_match = re.search(r"\{.*\}", text, re.DOTALL)
+        if brace_match:
+            action = self._try_parse_json(brace_match.group(0))
+            if action is not None:
+                return self._validate_action(action)
+
+        return None, (
+            "Could not parse your response as JSON. "
+            "Please respond with a single JSON object like: "
+            '{"action": "tool_name", ...} or {"action": "final", "answer": "..."}'
+        )
+
+    @staticmethod
+    def _try_parse_json(text: str) -> Optional[Dict[str, Any]]:
+        """Try to parse *text* as JSON.  Return None on failure."""
+        try:
+            data = json.loads(text)
+            if isinstance(data, dict):
+                return data
+        except (json.JSONDecodeError, ValueError):
+            pass
+        return None
+
+    @staticmethod
+    def _validate_action(action: Dict[str, Any]) -> tuple:
+        """Check that *action* has the required ``"action"`` key."""
+        if "action" not in action:
+            return None, (
+                'JSON object is missing the required "action" key. '
+                'Every response must include "action".'
+            )
+        return action, None
+
+    @staticmethod
+    def _summarise_args(action: Dict[str, Any]) -> str:
+        """Create a short summary of tool arguments for display."""
+        skip = {"action"}
+        parts = []
+        for k, v in action.items():
+            if k in skip:
+                continue
+            s = str(v)
+            if len(s) > 60:
+                s = s[:57] + "..."
+            parts.append(f"{k}={s!r}")
+        return ", ".join(parts)
+
+    @staticmethod
+    def _print_status(message: str) -> None:
+        """Print a status line to stderr."""
+        sys.stderr.write(f"  {message}\n")
+        sys.stderr.flush()

Lterax/config.py

@@ -0,0 +1,75 @@
+"""
+Configuration management for Ltera.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict
+
+
+_DEFAULTS: Dict[str, Any] = {
+    "base_url": "auto",
+    "model": "gemini-3.5-flash",
+    "timeout": 120,
+    "verbose": False,
+}
+
+# Maps environment variable names to config keys.
+_ENV_MAP: Dict[str, str] = {
+    "LTERA_BASE_URL": "base_url",
+    "LTERA_MODEL": "model",
+    "LTERA_TIMEOUT": "timeout",
+    "LTERA_VERBOSE": "verbose",
+}
+
+# Keys that should be coerced to int.
+_INT_KEYS = {"timeout"}
+
+# Keys that should be coerced to bool.
+_BOOL_KEYS = {"verbose"}
+
+@dataclass
+class Config:
+    """Immutable-ish configuration container for a Ltera session.
+
+    All fields have sensible defaults.  Override via constructor kwargs,
+    environment variables, or a JSON config file.
+    """
+
+    base_url: str = _DEFAULTS["base_url"]
+    model: str = _DEFAULTS["model"]
+    timeout: int = _DEFAULTS["timeout"]
+    verbose: bool = _DEFAULTS["verbose"]
+
+    _explicit: set = field(default_factory=set, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        for env_var, key in _ENV_MAP.items():
+            if key in self._explicit:
+                continue
+            value = os.environ.get(env_var)
+            if value is not None:
+                value = _coerce(key, value)
+                object.__setattr__(self, key, value)
+
+
+
+    def __repr__(self) -> str:
+        return (
+            f"Config(base_url={self.base_url!r}, model={self.model!r}, "
+            f"timeout={self.timeout}, verbose={self.verbose})"
+        )
+
+
+
+def _coerce(key: str, value: str) -> Any:
+    """Coerce a string environment variable to the correct Python type."""
+    if key in _INT_KEYS:
+        return int(value)
+    if key in _BOOL_KEYS:
+        return value.lower() in ("1", "true", "yes")
+    return value