librarian-code 0.1.0__py3-none-any.whl

librarian/utils/ui.py

@@ -0,0 +1,97 @@
+import sys
+import io
+import pyfiglet
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.prompt import Confirm
+from rich.columns import Columns
+from rich.text import Text
+
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")
+console = Console(force_terminal=True)
+
+INDIGO = "#6366F1"
+VIOLET = "#8B5CF6"
+MUTED = "#6B7280"
+SUCCESS = "#10B981"
+WARNING = "#F59E0B"
+ERROR = "#EF4444"
+CYAN = "#06B6D4"
+PINK = "#EC4899"
+
+
+def print_banner():
+    ascii_art = pyfiglet.figlet_format("librarian", font="larry3d")
+    styled_art = Text(ascii_art, style="bold white")
+    tagline = Text("\n  a CLI coding agent with persistent project memory", style=f"italic {MUTED}")
+
+    commands = Table(show_header=False, box=None, padding=(0, 2))
+    commands.add_column(style=f"bold {CYAN}")
+    commands.add_column(style=MUTED)
+    commands.add_row("init", "index your project")
+    commands.add_row("ask", "question your codebase")
+    commands.add_row("do", "execute a task")
+    commands.add_row("why", "see decision history")
+    commands.add_row("undo", "revert last action")
+    commands.add_row("status", "project overview")
+
+    banner_content = Text()
+    banner_content.append_text(styled_art)
+    banner_content.append_text(tagline)
+
+    panel = Panel(
+        banner_content,
+        border_style=INDIGO,
+        padding=(1, 3),
+    )
+    console.print()
+    console.print(panel)
+
+    cmd_panel = Panel(
+        commands,
+        title=f"[bold {VIOLET}]commands[/bold {VIOLET}]",
+        border_style=VIOLET,
+        padding=(0, 1),
+    )
+    console.print(cmd_panel)
+    console.print()
+
+
+def print_header(title: str):
+    console.print(f"\n[bold {INDIGO}]>[/bold {INDIGO}] [bold]{title}[/bold]")
+    console.rule(style=INDIGO)
+
+
+def print_success(msg: str):
+    console.print(f"[bold {SUCCESS}]checkmark[/bold {SUCCESS}] {msg}")
+
+
+def print_warning(msg: str):
+    console.print(f"[bold {WARNING}]![/bold {WARNING}] {msg}")
+
+
+def print_error(msg: str):
+    console.print(f"[bold {ERROR}]x[/bold {ERROR}] {msg}")
+
+
+def print_muted(msg: str):
+    console.print(f"[{MUTED}]{msg}[/{MUTED}]")
+
+
+def print_panel(content: str, title: str = "", style: str = INDIGO):
+    console.print(Panel(content, title=title, border_style=style, padding=(1, 2)))
+
+
+def confirm_action(description: str) -> bool:
+    console.print(f"\n[bold {WARNING}]safety check[/bold {WARNING}]")
+    return Confirm.ask(f"  [{WARNING}]{description}[/{WARNING}]")
+
+
+def spinner(description: str):
+    return Progress(
+        SpinnerColumn(style=INDIGO),
+        TextColumn(f"[{MUTED}]{description}[/{MUTED}]"),
+        transient=True,
+    )

librarian_code-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,45 @@
+librarian/__init__.py,sha256=ZGVQ7mPZNTCf6su8JgJUBC0H_fG-3WehU8TkW-PXPT4,94
+librarian/__main__.py,sha256=FzsJRHMKtP-Ufam5f9WmwuLgLEjT9EGS8E_wpXg1DrE,37
+librarian/cli.py,sha256=w1tCtBw6OkhsBG0ifwyQFRBfEm5RXvISqUfCPq6FDFI,665
+librarian/exceptions.py,sha256=6vvJHuZqhrZrgYZGUo8Y2jQ_4O2QeMK279jG5NDyHbc,318
+librarian/actions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+librarian/actions/file_ops.py,sha256=RtdNERT4x0l7IY_Hml6F_0RnxRjByzNke3hiFFxxQ78,1417
+librarian/actions/safety.py,sha256=MXtdmXE632A2vWzCEETcrTcxoEA8RXBd31CqKprZEOg,584
+librarian/actions/shell_ops.py,sha256=P6TL6tBoPX70p7G4yOPIS2N6QfK2BFXvSwq_PXxlDAI,1302
+librarian/adapter/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+librarian/adapter/base.py,sha256=KJCnHZEdKu6S3wW4oxHgdABlPRiuGwQNUFokvWat0tU,221
+librarian/adapter/groq_adapter.py,sha256=xT_GZdJfxXTyTk2HQ5rnzg_VxvQ1L9QbTpbwBgL8pcI,1489
+librarian/adapter/openrouter_adapter.py,sha256=0iz1ZhzGpZqdtbi5bsl_Tf-Y3Ljp6EriqXzumjm-_Zg,2307
+librarian/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+librarian/commands/ask.py,sha256=2PaRre15bMPIEavw37LvBaM8SPzxE5U6nlCoUdmlMmQ,1633
+librarian/commands/do.py,sha256=tt117T4CSMz7XAB9oRx_etaDuh1zTRmYJRTbYnmwjsQ,8743
+librarian/commands/init.py,sha256=9bN6X_I8K0gG80hTKEHtLKrWZ0t7LGyxJxzHdHeC2dE,2894
+librarian/commands/status.py,sha256=-_SG7ftxdrSDEt1N6TFDAtz3Tt2t0YWTccDQYPJU-Yk,2706
+librarian/commands/undo.py,sha256=M_4NjfVB5TebpBG77r3VNdSpW6YFyuvZAfcKtYo95BI,2574
+librarian/commands/why.py,sha256=pgLM2cYnUxV4DaQTmOoGlXuv97c5oQtMt2nXZfWr_p8,1667
+librarian/memory/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+librarian/memory/capsule.py,sha256=KcnZI0zKcMnpMPEhLv7dh0-EqR00_PTFSPwgIWAkqWk,2518
+librarian/memory/chunker.py,sha256=uBZyWRv75AAVaAM_FWiP0BUmGQXYaG_0pnkizWRwEUQ,6285
+librarian/memory/decision_log.py,sha256=TmakVFnx_ifQp7IuMUxhbh5UsOV5AkxvuIeH78VPX0w,1048
+librarian/memory/indexer.py,sha256=FoONgVMN5qax_VKg9_qrtOZ2qfIcEp9qVMyXToITRyc,3043
+librarian/memory/retriever.py,sha256=gFbM8fjER4-QJrAnWR6swjXOTlnPTPIVwyseUdw6jzM,1564
+librarian/orchestrator/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+librarian/orchestrator/core.py,sha256=RLWL5MEi09ztxVuqi3PLzr8oF9L5G0kz49LxGzrWe_E,1730
+librarian/orchestrator/router.py,sha256=sSLCiXh3g0j_vnbr6gHgayQHHmnUmoVqsmSZ1--_6Gg,720
+librarian/skills/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+librarian/skills/loader.py,sha256=rv8bMVL9I0HC1Pxzq5ypmIol9GGfiycJv16f90M5s0k,3729
+librarian/skills/bundled/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+librarian/skills/bundled/api-design/conventions.md,sha256=DWK6lumDKGTjBwC0ZyJLDUd87ZVfRzduZmC2TaG50tY,3209
+librarian/skills/bundled/python/conventions.md,sha256=4bcZOVVzk5zDToYGEsh2HVVdibrxCk2TiqE-WvGk-vM,2316
+librarian/skills/bundled/react/conventions.md,sha256=52YgVygWmPJLZOecBDpwzrHFfqV1LGSNm9XfEowb_Kc,3062
+librarian/skills/bundled/web-dev/conventions.md,sha256=PY4Tll-4APkmAPMB7p1-gtCOb1rBssB4xlSDsWKeC3c,2253
+librarian/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+librarian/utils/config.py,sha256=bHzj3qFDJY7BZc37vKgpQe3LRPi36-QQCfcBXhVAFfI,546
+librarian/utils/logger.py,sha256=n1COiHWzXLWm0J6I5PuBKkMhXbb6nRPBFU8S3FNf6SM,605
+librarian/utils/token_tracker.py,sha256=5xch5JWNWnM5Z-3XkC-uf8a_HatlFIkkZAwoaXyLOP4,487
+librarian/utils/ui.py,sha256=oGDS7pAtf8PMoN5vHdtAHUC2O92fp42em3SCkJaLYxg,2721
+librarian_code-0.1.0.dist-info/METADATA,sha256=7yPmU4GRYR-gPB0dMrZnl3WOT-572qfj5i_jlt7Ft1U,6472
+librarian_code-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+librarian_code-0.1.0.dist-info/entry_points.txt,sha256=oE3mm9INPgmDXlTLTKPfdd10ocDwa2xIb0o3gzgw5Q8,48
+librarian_code-0.1.0.dist-info/licenses/LICENSE.md,sha256=SE4TZDsWWMYoMePRurMmCCqsRGahPc5uzghX8s8EqJY,1071
+librarian_code-0.1.0.dist-info/RECORD,,

librarian_code-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

librarian_code-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+librarian = librarian.cli:app

librarian_code-0.1.0.dist-info/licenses/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.