librarian-code 0.1.0__tar.gz

librarian_code-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.env
+.librarian/
+LIBRARIAN.md
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

librarian_code-0.1.0/.mimocode/plans/1782009063038-gentle-garden.md

@@ -0,0 +1,95 @@
+# Plan: Publish to PyPI for `pip install -g librarian-code`
+
+## Goal
+Make the package installable globally via `pip install -g librarian-code`.
+
+---
+
+## Phase 1: Fix Package Metadata
+
+### 1. Update `pyproject.toml`
+Add missing fields: `readme`, `license`, `authors`, `classifiers`, `urls`, and build artifacts for bundled skills.
+
+### 2. Add `__version__` to `librarian/__init__.py`
+```python
+__version__ = "0.1.0"
+```
+
+### 3. Fix `README.md`
+Remove `.env.example` reference (file doesn't exist).
+
+---
+
+## Phase 2: Set Up PyPI Account
+
+1. Go to https://pypi.org/account/register/
+2. Create account (use a dedicated email)
+3. Verify email
+
+### Generate API Token
+1. Go to https://pypi.org/manage/account/token/
+2. Click "Add API token"
+3. Name: `librarian-code-publish`
+4. Scope: "Entire account" (or project-specific after first upload)
+5. Copy token — **it won't be shown again**
+
+### Store Token Locally
+```bash
+pip install twine
+# Create ~/.pypirc (Windows: %USERPROFILE%\.pypirc)
+```
+
+Contents:
+```ini
+[pypi]
+username = __token__
+password = pypi-YOUR_TOKEN_HERE
+```
+
+---
+
+## Phase 3: Build & Publish
+
+```bash
+# 1. Install build tools
+pip install build twine
+
+# 2. Clean old builds
+rm -rf dist/ build/ *.egg-info
+
+# 3. Build
+python -m build
+
+# 4. Verify package contents
+twine check dist/*
+
+# 5. Upload to PyPI
+twine upload dist/*
+```
+
+---
+
+## Phase 4: Verify
+
+```bash
+# Test install from PyPI
+pip install -g librarian-code
+
+# Should work
+librarian --version
+librarian --help
+```
+
+---
+
+## Files to Modify
+- `pyproject.toml`
+- `librarian/__init__.py`
+- `README.md`
+
+## Verification
+1. `python -m build` — produces `.whl` + `.tar.gz`
+2. `twine check dist/*` — passes
+3. `pip install dist/*.whl` — installs correctly
+4. `librarian --version` — prints `0.1.0`
+5. Bundled skills `.md` files included in wheel

librarian_code-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neel Sorathiya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

librarian_code-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: librarian-code
+Version: 0.1.0
+Summary: A local-first CLI coding agent with persistent project memory
+Project-URL: Homepage, https://github.com/Humble-Librarian/Librarian-Code
+Project-URL: Repository, https://github.com/Humble-Librarian/Librarian-Code
+Project-URL: Issues, https://github.com/Humble-Librarian/Librarian-Code/issues
+Author: Neel Sorathiya
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: chromadb>=0.5.0
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: groq>=0.11.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyfiglet>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sentence-transformers>=3.0.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# librarian
+
+> a CLI coding agent that remembers your project
+
+## what it does differently
+
+Librarian is a local-first CLI coding agent with persistent project memory. Unlike tools that call an LLM on every request regardless of confidence, Librarian builds a capsule-based memory of your project's decisions — remembering why edits were made, adjusting confidence over time, and routing between Groq and OpenRouter intelligently when rate limits hit.
+
+Built without LangChain — pure Python, owned stack. Every file operation, every LLM call, every decision is transparent and logged.
+
+## install
+
+```bash
+pip install -g librarian-code
+```
+
+## setup
+
+You need at least one free API key:
+
+| Provider | Get Key | Cost |
+|----------|---------|------|
+| **Groq** | https://console.groq.com | Free tier available |
+| **OpenRouter** | https://openrouter.ai | Free models available |
+
+Create `.env` in your project root:
+
+```bash
+# option 1: groq (fast)
+echo "GROQ_API_KEY=gsk_..." > .env
+
+# option 2: openrouter
+echo "OPENROUTER_API_KEY=sk-or-..." > .env
+
+# or both (openrouter used as fallback)
+```
+
+## quick start
+
+```bash
+librarian init                    # index your project
+librarian ask "what does this project do?"
+librarian do "add input validation to login()"
+librarian why                     # see decision history
+librarian undo                    # revert last action
+librarian status                  # project overview
+```
+
+## commands
+
+| command | what it does |
+|---------|-------------|
+| `librarian init` | indexes project files, generates LIBRARIAN.md conventions |
+| `librarian ask` | asks a question about your codebase, returns answer with sources |
+| `librarian do` | gives librarian a task, shows plan preview, executes with your approval |
+| `librarian why` | shows last decisions with reasoning |
+| `librarian undo` | reverts the last agent action |
+| `librarian status` | shows project info, memory stats, token usage |
+
+## how memory works
+
+Librarian uses a **capsule-based memory system**:
+
+- Every action creates a **capsule** with a confidence score (starts at 0.5)
+- When you approve an action: confidence × 1.15
+- When you undo an action: confidence × 0.6
+- Unused capsules decay: × 0.98 per day
+- Capsules below 0.4 confidence are archived
+
+This means Librarian learns from your feedback over time — actions you approve become more confident, actions you undo become less likely to be repeated.
+
+## skills
+
+Librarian auto-detects your project type and loads relevant conventions:
+
+- **python**: pyproject.toml, setup.py, requirements.txt
+- **react**: next.config.*, .tsx/.jsx files
+- **web-dev**: .html files, CSS/SCSS
+- **api-design**: routes.py, models.py, schemas.py
+
+Skills provide domain-specific best practices that are injected into the LLM context for more relevant suggestions.
+
+## architecture
+
+```
+librarian/
+├── adapter/          # LLM adapters (Groq primary, OpenRouter fallback)
+│   ├── base.py       # abstract adapter interface
+│   ├── groq_adapter.py
+│   └── openrouter_adapter.py
+├── orchestrator/     # routing and system prompt building
+│   ├── router.py     # Groq → OpenRouter fallback
+│   └── core.py       # prompt construction
+├── memory/           # persistent project memory
+│   ├── chunker.py    # AST-based code splitting
+│   ├── indexer.py    # ChromaDB + sentence-transformers
+│   ├── retriever.py  # semantic search (cached model)
+│   ├── capsule.py    # decision memory with confidence
+│   └── decision_log.py  # append-only action log
+├── skills/           # auto-detected project conventions
+│   ├── loader.py     # project type detection with caching
+│   └── bundled/      # skill convention files
+├── actions/          # file and shell operations
+│   ├── file_ops.py   # read, write, edit files
+│   ├── shell_ops.py  # git and shell commands (shell=False)
+│   └── safety.py     # risk classification
+├── commands/         # CLI commands
+│   ├── init.py
+│   ├── ask.py
+│   ├── do.py
+│   ├── why.py
+│   ├── undo.py
+│   └── status.py
+├── utils/            # shared utilities
+│   ├── config.py     # env var loading
+│   ├── ui.py         # Terminal Luxury output
+│   ├── logger.py     # structured logging
+│   └── token_tracker.py
+├── cli.py            # typer entry point
+└── exceptions.py     # custom exception types
+```
+
+## providers
+
+- **Groq** (primary): `llama-3.3-70b-versatile`, fast inference
+- **OpenRouter** (fallback): `qwen/qwen3-coder:free`, automatic on rate limit
+
+## security
+
+- Shell commands use `shell=False` with argument lists to prevent injection
+- File operations use proper context managers to prevent handle leaks
+- API responses validated before access
+- LLM-generated delete operations require confirmation
+
+## performance
+
+- SentenceTransformer model cached as singleton (~2-3s saved per invocation)
+- ChromaDB client reused across calls
+- Project type detection cached with `@lru_cache`
+- Heavy dependencies lazy-loaded at function call time
+
+## testing
+
+```bash
+python -m pytest tests/ -v
+```
+
+## license
+
+MIT

librarian_code-0.1.0/README.md

@@ -0,0 +1,150 @@
+# librarian
+
+> a CLI coding agent that remembers your project
+
+## what it does differently
+
+Librarian is a local-first CLI coding agent with persistent project memory. Unlike tools that call an LLM on every request regardless of confidence, Librarian builds a capsule-based memory of your project's decisions — remembering why edits were made, adjusting confidence over time, and routing between Groq and OpenRouter intelligently when rate limits hit.
+
+Built without LangChain — pure Python, owned stack. Every file operation, every LLM call, every decision is transparent and logged.
+
+## install
+
+```bash
+pip install -g librarian-code
+```
+
+## setup
+
+You need at least one free API key:
+
+| Provider | Get Key | Cost |
+|----------|---------|------|
+| **Groq** | https://console.groq.com | Free tier available |
+| **OpenRouter** | https://openrouter.ai | Free models available |
+
+Create `.env` in your project root:
+
+```bash
+# option 1: groq (fast)
+echo "GROQ_API_KEY=gsk_..." > .env
+
+# option 2: openrouter
+echo "OPENROUTER_API_KEY=sk-or-..." > .env
+
+# or both (openrouter used as fallback)
+```
+
+## quick start
+
+```bash
+librarian init                    # index your project
+librarian ask "what does this project do?"
+librarian do "add input validation to login()"
+librarian why                     # see decision history
+librarian undo                    # revert last action
+librarian status                  # project overview
+```
+
+## commands
+
+| command | what it does |
+|---------|-------------|
+| `librarian init` | indexes project files, generates LIBRARIAN.md conventions |
+| `librarian ask` | asks a question about your codebase, returns answer with sources |
+| `librarian do` | gives librarian a task, shows plan preview, executes with your approval |
+| `librarian why` | shows last decisions with reasoning |
+| `librarian undo` | reverts the last agent action |
+| `librarian status` | shows project info, memory stats, token usage |
+
+## how memory works
+
+Librarian uses a **capsule-based memory system**:
+
+- Every action creates a **capsule** with a confidence score (starts at 0.5)
+- When you approve an action: confidence × 1.15
+- When you undo an action: confidence × 0.6
+- Unused capsules decay: × 0.98 per day
+- Capsules below 0.4 confidence are archived
+
+This means Librarian learns from your feedback over time — actions you approve become more confident, actions you undo become less likely to be repeated.
+
+## skills
+
+Librarian auto-detects your project type and loads relevant conventions:
+
+- **python**: pyproject.toml, setup.py, requirements.txt
+- **react**: next.config.*, .tsx/.jsx files
+- **web-dev**: .html files, CSS/SCSS
+- **api-design**: routes.py, models.py, schemas.py
+
+Skills provide domain-specific best practices that are injected into the LLM context for more relevant suggestions.
+
+## architecture
+
+```
+librarian/
+├── adapter/          # LLM adapters (Groq primary, OpenRouter fallback)
+│   ├── base.py       # abstract adapter interface
+│   ├── groq_adapter.py
+│   └── openrouter_adapter.py
+├── orchestrator/     # routing and system prompt building
+│   ├── router.py     # Groq → OpenRouter fallback
+│   └── core.py       # prompt construction
+├── memory/           # persistent project memory
+│   ├── chunker.py    # AST-based code splitting
+│   ├── indexer.py    # ChromaDB + sentence-transformers
+│   ├── retriever.py  # semantic search (cached model)
+│   ├── capsule.py    # decision memory with confidence
+│   └── decision_log.py  # append-only action log
+├── skills/           # auto-detected project conventions
+│   ├── loader.py     # project type detection with caching
+│   └── bundled/      # skill convention files
+├── actions/          # file and shell operations
+│   ├── file_ops.py   # read, write, edit files
+│   ├── shell_ops.py  # git and shell commands (shell=False)
+│   └── safety.py     # risk classification
+├── commands/         # CLI commands
+│   ├── init.py
+│   ├── ask.py
+│   ├── do.py
+│   ├── why.py
+│   ├── undo.py
+│   └── status.py
+├── utils/            # shared utilities
+│   ├── config.py     # env var loading
+│   ├── ui.py         # Terminal Luxury output
+│   ├── logger.py     # structured logging
+│   └── token_tracker.py
+├── cli.py            # typer entry point
+└── exceptions.py     # custom exception types
+```
+
+## providers
+
+- **Groq** (primary): `llama-3.3-70b-versatile`, fast inference
+- **OpenRouter** (fallback): `qwen/qwen3-coder:free`, automatic on rate limit
+
+## security
+
+- Shell commands use `shell=False` with argument lists to prevent injection
+- File operations use proper context managers to prevent handle leaks
+- API responses validated before access
+- LLM-generated delete operations require confirmation
+
+## performance
+
+- SentenceTransformer model cached as singleton (~2-3s saved per invocation)
+- ChromaDB client reused across calls
+- Project type detection cached with `@lru_cache`
+- Heavy dependencies lazy-loaded at function call time
+
+## testing
+
+```bash
+python -m pytest tests/ -v
+```
+
+## license
+
+MIT

librarian_code-0.1.0/librarian/__init__.py

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

librarian_code-0.1.0/librarian/__main__.py

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

librarian_code-0.1.0/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_code-0.1.0/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_code-0.1.0/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_code-0.1.0/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_code-0.1.0/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