librarian-code 0.1.0__py3-none-any.whl

librarian/__init__.py

@@ -0,0 +1,3 @@
+"""Librarian — a CLI coding agent with persistent project memory."""
+
+__version__ = "0.1.0"

librarian/__main__.py

@@ -0,0 +1,3 @@
+from librarian.cli import app
+
+app()

librarian/actions/file_ops.py

@@ -0,0 +1,47 @@
+import os
+from pathlib import Path
+
+IGNORED_PATHS = [".git", "node_modules", "__pycache__", ".librarian", "venv", ".env"]
+
+
+def read_file(path: str) -> str:
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return Path(path).read_text(encoding="latin-1")
+
+
+def write_file(path: str, content: str) -> bool:
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    Path(path).write_text(content, encoding="utf-8")
+    return True
+
+
+def edit_file(path: str, old: str, new: str) -> bool:
+    content = read_file(path)
+    count = content.count(old)
+    if count == 0:
+        raise ValueError(f"String not found in {path}")
+    if count > 1:
+        raise ValueError(f"Ambiguous edit: string appears {count} times in {path}")
+    content = content.replace(old, new, 1)
+    write_file(path, content)
+    return True
+
+
+def list_files(directory: str, extensions: list[str] = None) -> list[str]:
+    ignored = get_ignored_paths()
+    results = []
+    for root, dirs, files in os.walk(directory):
+        dirs[:] = [d for d in dirs if d not in ignored]
+        for f in files:
+            if extensions:
+                ext = os.path.splitext(f)[1].lower()
+                if ext not in extensions:
+                    continue
+            results.append(os.path.join(root, f))
+    return sorted(results)
+
+
+def get_ignored_paths() -> list[str]:
+    return IGNORED_PATHS

librarian/actions/safety.py

@@ -0,0 +1,29 @@
+from enum import Enum
+
+
+class RiskLevel(Enum):
+    SAFE = "safe"
+    CONFIRM = "confirm"
+
+
+CONFIRM_ACTIONS = [
+    "git push",
+    "git reset --hard",
+    "rm ",
+    "delete",
+    "drop table",
+    "truncate",
+]
+
+
+def classify_action(action: str) -> RiskLevel:
+    action_lower = action.lower()
+    for pattern in CONFIRM_ACTIONS:
+        if pattern in action_lower:
+            return RiskLevel.CONFIRM
+    return RiskLevel.SAFE
+
+
+def request_confirm(action: str) -> bool:
+    from rich.prompt import Confirm
+    return Confirm.ask(f"[bold #F59E0B]confirm:[/bold #F59E0B] {action}")

librarian/actions/shell_ops.py

@@ -0,0 +1,49 @@
+import subprocess
+import shlex
+from librarian.actions.safety import classify_action, RiskLevel, request_confirm
+
+
+def run_command(cmd: str, cwd: str = None) -> tuple[int, str, str]:
+    if isinstance(cmd, str):
+        args = shlex.split(cmd)
+    else:
+        args = cmd
+    result = subprocess.run(
+        args, shell=False, cwd=cwd,
+        capture_output=True, text=True,
+    )
+    return result.returncode, result.stdout, result.stderr
+
+
+def git_stage(files: list[str]) -> bool:
+    args = ["git", "add"] + files
+    code, _, err = run_command(args)
+    if code != 0:
+        raise RuntimeError(f"git add failed: {err}")
+    return True
+
+
+def git_commit(message: str) -> bool:
+    args = ["git", "commit", "-m", message]
+    code, _, err = run_command(args)
+    if code != 0:
+        raise RuntimeError(f"git commit failed: {err}")
+    return True
+
+
+def git_push() -> bool:
+    risk = classify_action("git push")
+    if risk == RiskLevel.CONFIRM:
+        if not request_confirm("push to remote?"):
+            return False
+    code, _, err = run_command("git push")
+    if code != 0:
+        raise RuntimeError(f"git push failed: {err}")
+    return True
+
+
+def git_status() -> str:
+    code, out, err = run_command("git status --short")
+    if code != 0:
+        return err
+    return out.strip()

librarian/adapter/base.py

@@ -0,0 +1,11 @@
+from abc import ABC, abstractmethod
+
+
+class LLMAdapter(ABC):
+    @abstractmethod
+    def complete(self, system: str, prompt: str) -> str:
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        pass

librarian/adapter/groq_adapter.py

@@ -0,0 +1,40 @@
+from groq import Groq, RateLimitError as GroqRateLimitError, APIConnectionError
+from librarian.adapter.base import LLMAdapter
+from librarian.exceptions import RateLimitError, ProviderUnavailableError
+from librarian.utils.config import GROQ_API_KEY
+
+
+class GroqAdapter(LLMAdapter):
+    def __init__(self):
+        self.client = Groq(api_key=GROQ_API_KEY) if GROQ_API_KEY else None
+        self.model = "llama-3.3-70b-versatile"
+        self.tokens_used = 0
+
+    def complete(self, system: str, prompt: str) -> str:
+        if not self.client:
+            raise ProviderUnavailableError("GROQ_API_KEY not set")
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": prompt},
+                ],
+                temperature=0.2,
+                max_tokens=4096,
+            )
+            self.tokens_used += response.usage.total_tokens
+            return response.choices[0].message.content
+        except GroqRateLimitError:
+            raise RateLimitError("Groq rate limit exceeded")
+        except APIConnectionError:
+            raise ProviderUnavailableError("Cannot connect to Groq")
+
+    def is_available(self) -> bool:
+        if not self.client:
+            return False
+        try:
+            self.client.models.list()
+            return True
+        except Exception:
+            return False

librarian/adapter/openrouter_adapter.py

@@ -0,0 +1,58 @@
+import httpx
+from librarian.adapter.base import LLMAdapter
+from librarian.exceptions import RateLimitError, ProviderUnavailableError
+from librarian.utils.config import OPENROUTER_API_KEY
+
+ENDPOINT = "https://openrouter.ai/api/v1/chat/completions"
+MODEL = "qwen/qwen3-coder:free"
+HEADERS = {
+    "HTTP-Referer": "https://github.com/Humble-Librarian/librarian-code",
+    "X-Title": "librarian",
+}
+
+
+class OpenRouterAdapter(LLMAdapter):
+    def __init__(self):
+        self.api_key = OPENROUTER_API_KEY
+        self.tokens_used = 0
+
+    def complete(self, system: str, prompt: str) -> str:
+        if not self.api_key:
+            raise ProviderUnavailableError("OPENROUTER_API_KEY not set")
+        headers = {**HEADERS, "Authorization": f"Bearer {self.api_key}"}
+        payload = {
+            "model": MODEL,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": prompt},
+            ],
+            "temperature": 0.2,
+            "max_tokens": 4096,
+        }
+        try:
+            with httpx.Client(timeout=60) as client:
+                resp = client.post(ENDPOINT, headers=headers, json=payload)
+            if resp.status_code == 429:
+                raise RateLimitError("OpenRouter rate limit exceeded")
+            resp.raise_for_status()
+            data = resp.json()
+            self.tokens_used += data.get("usage", {}).get("total_tokens", 0)
+            choices = data.get("choices", [])
+            if not choices or "message" not in choices[0]:
+                raise ProviderUnavailableError("Invalid API response format")
+            return choices[0]["message"]["content"]
+        except httpx.ConnectError:
+            raise ProviderUnavailableError("Cannot connect to OpenRouter")
+        except httpx.TimeoutException:
+            raise ProviderUnavailableError("OpenRouter request timed out")
+
+    def is_available(self) -> bool:
+        if not self.api_key:
+            return False
+        try:
+            headers = {**HEADERS, "Authorization": f"Bearer {self.api_key}"}
+            with httpx.Client(timeout=10) as client:
+                resp = client.get("https://openrouter.ai/api/v1/models", headers=headers)
+            return resp.status_code == 200
+        except Exception:
+            return False

librarian/cli.py

@@ -0,0 +1,26 @@
+import typer
+from librarian.commands import init, ask, do, why, undo, status
+from librarian.utils.ui import print_banner, print_muted, print_warning
+
+app = typer.Typer(
+    name="librarian",
+    help="A CLI coding agent with persistent project memory.",
+    add_completion=False,
+)
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context):
+    if ctx.invoked_subcommand is None:
+        print_banner()
+
+
+app.command(name="init")(init.run)
+app.command(name="ask")(ask.run)
+app.command(name="do")(do.run)
+app.command(name="why")(why.run)
+app.command(name="undo")(undo.run)
+app.command(name="status")(status.run)
+
+if __name__ == "__main__":
+    app()

librarian/commands/ask.py

@@ -0,0 +1,46 @@
+from pathlib import Path
+from librarian.utils.ui import print_header, print_warning, print_panel, print_muted
+from librarian.utils.token_tracker import tracker
+from librarian.orchestrator.core import ask as ask_llm
+from librarian.memory.retriever import retrieve
+
+
+def _check_api_keys():
+    from librarian.utils.config import GROQ_API_KEY, OPENROUTER_API_KEY
+    if not GROQ_API_KEY and not OPENROUTER_API_KEY:
+        print_warning("no API keys found")
+        print_muted("  set at least one API key in .env file:")
+        print_muted("")
+        print_muted("  GROQ_API_KEY=gsk_...        (free at console.groq.com)")
+        print_muted("  OPENROUTER_API_KEY=sk-or-... (free at openrouter.ai)")
+        print_muted("")
+        return False
+    return True
+
+
+def run(task: str):
+    if not Path(".librarian").exists():
+        print_header("librarian ask")
+        print_warning("project not initialised — run 'librarian init' first")
+        return
+
+    if not _check_api_keys():
+        return
+
+    print_header("librarian ask")
+
+    try:
+        chunks = retrieve(task, n_results=5)
+        sources = []
+        for c in chunks:
+            meta = c["metadata"]
+            sources.append(f"{meta['file_path']}:{meta.get('start_line', '?')}-{meta.get('end_line', '?')}")
+
+        response, provider, tokens = ask_llm(task)
+        tracker.add(provider, tokens)
+        print_panel(response, title="answer")
+        if sources:
+            print_muted(f"  sources   {', '.join(sources[:3])}")
+        print_muted(f"  tokens    {tokens}  provider  {provider}")
+    except Exception as e:
+        print_warning(f"error: {e}")

librarian/commands/do.py

@@ -0,0 +1,232 @@
+import json
+import re
+import shutil
+from pathlib import Path
+from librarian.utils.ui import (
+    print_header, print_warning, print_success, print_muted,
+    print_panel, confirm_action, console, INDIGO, WARNING, SUCCESS,
+)
+from librarian.utils.token_tracker import tracker
+from librarian.orchestrator.core import read_librarian_md, build_system_prompt
+from librarian.orchestrator.router import get_response
+from librarian.memory.retriever import retrieve
+from librarian.memory import capsule, decision_log
+from librarian.actions.file_ops import read_file, write_file, edit_file
+from librarian.actions.shell_ops import run_command
+from librarian.actions.safety import classify_action, RiskLevel
+from librarian.skills.loader import build_skill_context
+
+DO_SYSTEM_PROMPT = """You are Librarian, a CLI coding agent. Respond ONLY with a JSON plan.
+
+ACTION TYPES:
+
+1. create_file — for new files:
+{"type":"create_file","file":"path","description":"what","content":"COMPLETE file"}
+
+2. edit_file — modify existing files:
+{"type":"edit_file","file":"path","description":"what","old_code":"EXACT text","new_code":"replacement"}
+
+3. delete_file — remove files/folders:
+{"type":"delete_file","file":"path","description":"why"}
+
+4. shell_command — run terminal commands:
+{"type":"shell_command","command":"cmd","description":"what"}
+
+RESPONSE FORMAT:
+{"reasoning":"approach","actions":[...]}
+
+RULES:
+- content in create_file MUST be the complete, working, FULL file — never a stub, placeholder, or comment
+- NEVER generate content like "// add code here" or empty tags — always write real, functional code
+- For web projects (HTML/CSS/JS): prefer a single index.html with inline <style> and <script>
+- old_code in edit_file must match the file EXACTLY including whitespace — if unsure, use create_file instead
+- Return ONLY valid JSON — no markdown fences, no explanation
+- Keep file contents under 200 lines to avoid truncation
+"""
+
+
+def _parse_plan(raw: str) -> dict:
+    raw = raw.strip()
+    if raw.startswith("```"):
+        raw = re.sub(r"^```(?:json)?\n?", "", raw)
+        raw = re.sub(r"\n?```$", "", raw)
+
+    raw = raw.replace("\\'", "'")
+
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        pass
+
+    last_bracket = raw.rfind("]")
+    if last_bracket == -1:
+        raise json.JSONDecodeError("No JSON array found", raw, 0)
+    truncated = raw[:last_bracket] + "]}"
+
+    try:
+        return json.loads(truncated)
+    except json.JSONDecodeError:
+        raise json.JSONDecodeError("Could not parse plan", raw, 0)
+
+
+def _format_chunks(chunks: list[dict]) -> str:
+    parts = []
+    for c in chunks:
+        meta = c["metadata"]
+        parts.append(f"--- {meta['file_path']}:{meta.get('start_line', '?')}-{meta.get('end_line', '?')} ---\n{c['content']}")
+    return "\n\n".join(parts)
+
+
+def _show_plan(plan: dict, task: str):
+    print_panel(
+        f"  task      {task}\n\n  reasoning {plan.get('reasoning', '—')}",
+        title="execution plan",
+    )
+    from rich.table import Table
+    table = Table(show_header=True, header_style=f"bold {INDIGO}")
+    table.add_column("#", width=3)
+    table.add_column("type", width=14)
+    table.add_column("description", width=40)
+    for i, action in enumerate(plan.get("actions", []), 1):
+        table.add_row(
+            str(i),
+            action.get("type", "?"),
+            action.get("description", "—"),
+        )
+    console.print(table)
+
+
+def _execute_action(action: dict) -> dict:
+    action_type = action.get("type")
+    if action_type == "edit_file":
+        path = Path(action["file"])
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {action['file']}")
+        content = read_file(action["file"])
+        if action["old_code"] not in content:
+            raise ValueError(f"old_code not found in {action['file']} — file may have changed")
+        edit_file(action["file"], action["old_code"], action["new_code"])
+        return {"type": "edit_file", "file": action["file"], "status": "done"}
+    elif action_type == "create_file":
+        path = Path(action["file"])
+        if path.exists() and path.stat().st_size > 0:
+            content = action.get("content", "")
+            if not content or len(content.strip()) < 20:
+                raise ValueError(f"Refusing to overwrite {action['file']} with empty/stub content")
+        write_file(action["file"], action["content"])
+        return {"type": "create_file", "file": action["file"], "status": "done"}
+    elif action_type == "delete_file":
+        target = Path(action["file"])
+        if target.is_dir():
+            shutil.rmtree(target)
+        elif target.is_file():
+            target.unlink()
+        else:
+            raise FileNotFoundError(f"Not found: {action['file']}")
+        return {"type": "delete_file", "file": action["file"], "status": "done"}
+    elif action_type == "shell_command":
+        cmd = action["command"]
+        if cmd.strip().startswith("rm "):
+            import re as _re
+            paths = _re.findall(r"(?:^|\s)(\S+)", cmd.replace("rm ", "", 1))
+            for p in paths:
+                p = p.lstrip("-").lstrip("r").lstrip("f").strip()
+                target = Path(p)
+                if target.is_dir():
+                    shutil.rmtree(target)
+                elif target.is_file():
+                    target.unlink()
+            return {"type": "shell_command", "command": cmd, "status": "done"}
+        code, out, err = run_command(cmd)
+        return {"type": "shell_command", "command": cmd, "status": "done" if code == 0 else f"exit {code}"}
+    return {"type": action_type, "status": "unknown"}
+
+
+def _check_api_keys():
+    from librarian.utils.config import GROQ_API_KEY, OPENROUTER_API_KEY
+    if not GROQ_API_KEY and not OPENROUTER_API_KEY:
+        print_warning("no API keys found")
+        print_muted("  set at least one API key in .env file:")
+        print_muted("")
+        print_muted("  GROQ_API_KEY=gsk_...        (free at console.groq.com)")
+        print_muted("  OPENROUTER_API_KEY=sk-or-... (free at openrouter.ai)")
+        print_muted("")
+        return False
+    return True
+
+
+def run(task: str):
+    if not Path(".librarian").exists():
+        print_header("librarian do")
+        print_warning("project not initialised — run 'librarian init' first")
+        return
+
+    if not _check_api_keys():
+        return
+
+    print_header("librarian do")
+
+    chunks = retrieve(task, n_results=7)
+    conventions = read_librarian_md()
+    skill_ctx = build_skill_context()
+
+    parts = [f"Project conventions:\n{conventions}"]
+    if skill_ctx:
+        parts.append(f"Domain best practices:\n{skill_ctx}")
+    if chunks:
+        context = _format_chunks(chunks)
+        parts.append(f"Relevant code:\n{context}")
+    parts.append(f"Task: {task}")
+    prompt = "\n\n".join(parts)
+
+    try:
+        raw_response, provider, tokens = get_response(DO_SYSTEM_PROMPT, prompt)
+        tracker.add(provider, tokens)
+        plan = _parse_plan(raw_response)
+    except json.JSONDecodeError:
+        print_warning("LLM returned invalid JSON — try rephrasing your task")
+        return
+    except Exception as e:
+        print_warning(f"error: {e}")
+        return
+
+    _show_plan(plan, task)
+
+    if not confirm_action("proceed with execution?"):
+        print_muted("  cancelled")
+        return
+
+    results = []
+    files_changed = []
+    for action in plan.get("actions", []):
+        risk_text = action.get("description", "") + " " + action.get("command", "") + " " + action.get("file", "")
+        if action.get("type") in ("delete_file",):
+            risk_text += " delete"
+        risk = classify_action(risk_text)
+        if risk == RiskLevel.CONFIRM:
+            if not confirm_action(f"execute: {action.get('description', '?')}"):
+                print_muted(f"  skipped: {action.get('description', '?')}")
+                continue
+        try:
+            result = _execute_action(action)
+            results.append(result)
+            if "file" in action:
+                files_changed.append(action["file"])
+            print_success(f"done: {action.get('description', '?')}")
+        except Exception as e:
+            print_warning(f"failed: {action.get('description', '?')} — {e}")
+
+    decision_log.append({
+        "command": "do",
+        "task": task,
+        "actions_taken": results,
+        "files_changed": files_changed,
+        "llm_provider": provider,
+        "tokens_used": tokens,
+        "reasoning": plan.get("reasoning", ""),
+    })
+
+    if results:
+        capsule.create(task, plan.get("reasoning", ""), files_changed)
+        print_success(f"{len(results)} actions completed")
+    print_muted(f"  tokens: {tokens}  provider: {provider}")

librarian/commands/init.py

@@ -0,0 +1,96 @@
+import os
+from pathlib import Path
+from librarian.utils.ui import print_header, print_success, print_warning, print_muted
+from librarian.memory.indexer import index_project
+
+
+def _detect_languages() -> list[str]:
+    from librarian.actions.file_ops import list_files
+    files = list_files(".", None)
+    exts = set()
+    for f in files:
+        ext = os.path.splitext(f)[1].lower()
+        if ext:
+            exts.add(ext)
+    lang_map = {
+        ".py": "Python", ".js": "JavaScript", ".ts": "TypeScript",
+        ".jsx": "React JSX", ".tsx": "React TSX", ".go": "Go",
+        ".rs": "Rust", ".java": "Java", ".rb": "Ruby",
+        ".md": "Markdown", ".txt": "Text",
+    }
+    return [lang_map.get(e, e) for e in sorted(exts) if e in lang_map]
+
+
+def _detect_package_manager() -> str:
+    if Path("pyproject.toml").exists():
+        return "uv / pip"
+    if Path("setup.py").exists():
+        return "pip"
+    if Path("package.json").exists():
+        return "npm"
+    if Path("Cargo.toml").exists():
+        return "cargo"
+    return "unknown"
+
+
+def _generate_librarian_md(languages: list[str], package_manager: str):
+    content = f"""# LIBRARIAN.md — project conventions
+
+## language
+{', '.join(languages) if languages else 'unknown'}
+
+## package manager
+{package_manager}
+
+## style
+- follow existing code conventions in the project
+- use type hints where applicable
+- keep functions focused and small
+
+## structure
+(add project structure notes here)
+
+## things to avoid
+- importing specific adapters directly (always use base.LLMAdapter)
+- hardcoding API keys
+- deleting files without confirmation
+
+## notes
+(add project-specific notes here — librarian reads this on every run)
+"""
+    Path("LIBRARIAN.md").write_text(content, encoding="utf-8")
+
+
+def run():
+    print_header("initialising project")
+
+    cwd = os.getcwd()
+    basename = os.path.basename(cwd)
+    if not basename or len(basename) < 2:
+        print_warning("cannot initialise from a root or drive directory")
+        print_muted("  cd into your project folder first, then run: librarian init")
+        return
+
+    librarian_dir = Path(".librarian")
+    if librarian_dir.exists():
+        print_warning(".librarian/ already exists — re-indexing")
+
+    librarian_dir.mkdir(exist_ok=True)
+
+    if not Path("LIBRARIAN.md").exists():
+        languages = _detect_languages()
+        pkg = _detect_package_manager()
+        _generate_librarian_md(languages, pkg)
+        print_success("LIBRARIAN.md created")
+    else:
+        print_muted("  LIBRARIAN.md already exists — skipping")
+
+    try:
+        meta = index_project()
+        print_success(f"{meta['file_count']} files, {meta['chunk_count']} chunks")
+    except Exception as e:
+        print_warning(f"indexing error: {e}")
+        return
+
+    print_success(".librarian/ initialised")
+    print_muted("\n  ready. run: librarian ask \"what does this project do?\"")