librarian-code 0.1.0__py3-none-any.whl

librarian/commands/status.py

@@ -0,0 +1,71 @@
+import os
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from librarian.utils.ui import print_header, print_panel, print_muted, INDIGO, SUCCESS
+from librarian.utils.token_tracker import tracker
+
+
+def run():
+    project_name = os.path.basename(os.getcwd())
+    librarian_dir = Path(".librarian")
+    meta_file = librarian_dir / "index_meta.json"
+    decisions_file = librarian_dir / "decisions.jsonl"
+    capsules_file = librarian_dir / "capsules.json"
+
+    if not librarian_dir.exists():
+        print_header("librarian status")
+        print_muted(f"  project      {project_name}")
+        print_muted("  indexed      not yet (run librarian init)")
+        print_muted("  memory       0 capsules")
+        print_muted("  last action  —")
+        print_muted("  tokens       0")
+        print_muted("  providers    groq (primary) · openrouter (fallback)")
+        return
+
+    indexed = "not yet"
+    if meta_file.exists():
+        meta = json.loads(meta_file.read_text())
+        indexed = f"{meta.get('file_count', '?')} files · {meta.get('chunk_count', '?')} chunks"
+
+    capsule_count = 0
+    avg_confidence = 0
+    if capsules_file.exists():
+        capsules = json.loads(capsules_file.read_text())
+        capsule_count = len(capsules)
+        if capsules:
+            avg_confidence = sum(c.get("confidence", 0) for c in capsules) / len(capsules)
+
+    decision_count = 0
+    last_action = "—"
+    if decisions_file.exists():
+        lines = decisions_file.read_text().strip().splitlines()
+        decision_count = len(lines)
+        if lines:
+            last = json.loads(lines[-1])
+            task = last.get("task", "—")
+            ts = last.get("timestamp", "")
+            try:
+                dt = datetime.fromisoformat(ts)
+                diff = datetime.now(timezone.utc) - dt
+                hours = int(diff.total_seconds() // 3600)
+                if hours < 1:
+                    last_action = f"{task} (just now)"
+                elif hours < 24:
+                    last_action = f"{task} ({hours}h ago)"
+                else:
+                    last_action = f"{task} ({hours // 24}d ago)"
+            except Exception:
+                last_action = task
+
+    print_header("librarian status")
+    content = (
+        f"  project      {project_name}\n"
+        f"  indexed      {indexed}\n"
+        f"  memory       {capsule_count} capsules · avg confidence {avg_confidence:.2f}\n"
+        f"  last action  {last_action}\n"
+        f"  tokens       {tracker.total()} this session\n"
+        f"  providers    groq (primary) · openrouter (fallback)\n"
+        f"  log entries  {decision_count}"
+    )
+    print_panel(content, title="project")

librarian/commands/undo.py

@@ -0,0 +1,85 @@
+import json
+from pathlib import Path
+from librarian.utils.ui import (
+    print_header, print_warning, print_success, print_muted, confirm_action,
+)
+from librarian.memory.decision_log import get_last, mark_undone
+from librarian.memory import capsule
+from librarian.actions.file_ops import read_file, write_file
+
+
+def _undo_edit_file(action: dict):
+    path = action.get("file")
+    new_code = action.get("new_code", "")
+    old_code = action.get("old_code", "")
+    if not path or not old_code:
+        return False
+    try:
+        content = read_file(path)
+        if new_code in content:
+            content = content.replace(new_code, old_code, 1)
+            write_file(path, content)
+            return True
+    except Exception:
+        pass
+    return False
+
+
+def _undo_create_file(action: dict):
+    path = action.get("file")
+    if not path:
+        return False
+    p = Path(path)
+    if p.exists():
+        if confirm_action(f"delete {path}?"):
+            p.unlink()
+            return True
+    return False
+
+
+def run():
+    if not Path(".librarian").exists():
+        print_header("librarian undo")
+        print_warning("project not initialised — run 'librarian init' first")
+        return
+
+    print_header("librarian undo")
+
+    entries = get_last(10)
+    undone = [e for e in entries if e.get("outcome") != "undone"]
+    if not undone:
+        print_muted("  nothing to undo")
+        return
+
+    last = undone[-1]
+    task = last.get("task", "—")
+    print_muted(f"  last action: {task}")
+
+    if not confirm_action(f"undo '{task}'?"):
+        print_muted("  cancelled")
+        return
+
+    reverted = 0
+    for action in last.get("actions_taken", []):
+        action_type = action.get("type")
+        if action_type == "edit_file":
+            if _undo_edit_file(action):
+                reverted += 1
+                print_success(f"reverted: {action.get('file', '?')}")
+        elif action_type == "create_file":
+            if _undo_create_file(action):
+                reverted += 1
+                print_success(f"deleted: {action.get('file', '?')}")
+        elif action_type == "shell_command":
+            print_warning(f"cannot auto-undo shell command: {action.get('command', '?')}")
+
+    mark_undone(last["id"])
+
+    capsules = capsule.get_all()
+    for c in capsules:
+        if c.get("decision") == task:
+            capsule.undo(c["id"])
+            print_muted(f"  capsule confidence updated: {c['confidence']:.2f} → {c['confidence'] * 0.6:.2f}")
+            break
+
+    print_success(f"undo complete — {reverted} actions reverted")

librarian/commands/why.py

@@ -0,0 +1,47 @@
+from pathlib import Path
+from datetime import datetime, timezone
+from librarian.utils.ui import print_header, print_warning, print_muted, console, INDIGO
+from librarian.memory.decision_log import get_last
+
+
+def _time_ago(timestamp: str) -> str:
+    try:
+        ts = datetime.fromisoformat(timestamp)
+        now = datetime.now(timezone.utc)
+        diff = now - ts
+        seconds = int(diff.total_seconds())
+        if seconds < 60:
+            return "just now"
+        if seconds < 3600:
+            return f"{seconds // 60} min ago"
+        if seconds < 86400:
+            return f"{seconds // 3600} hours ago"
+        return f"{seconds // 86400} days ago"
+    except Exception:
+        return "—"
+
+
+def run():
+    if not Path(".librarian").exists():
+        print_header("librarian why")
+        print_warning("project not initialised — run 'librarian init' first")
+        return
+
+    print_header("decision history")
+
+    entries = get_last(10)
+    if not entries:
+        print_muted("  no decisions logged yet")
+        return
+
+    for i, entry in enumerate(reversed(entries), 1):
+        time_str = _time_ago(entry.get("timestamp", ""))
+        task = entry.get("task", "—")
+        reasoning = entry.get("reasoning", "—")
+        provider = entry.get("llm_provider", "—")
+        outcome = entry.get("outcome", "approved")
+        tokens = entry.get("tokens_used", 0)
+
+        console.print(f"\n  [bold {INDIGO}]{i}[/bold {INDIGO}]  [{time_str}]  {task}")
+        console.print(f"      reasoning: {reasoning[:80]}{'...' if len(reasoning) > 80 else ''}")
+        console.print(f"      provider: {provider}  tokens: {tokens}  outcome: {outcome}")

librarian/exceptions.py

@@ -0,0 +1,22 @@
+class LibrarianError(Exception):
+    pass
+
+
+class RateLimitError(LibrarianError):
+    pass
+
+
+class ProviderUnavailableError(LibrarianError):
+    pass
+
+
+class ProjectNotInitialisedError(LibrarianError):
+    pass
+
+
+class SafetyBoundaryError(LibrarianError):
+    pass
+
+
+class ChunkNotFoundError(LibrarianError):
+    pass

librarian/memory/capsule.py

@@ -0,0 +1,94 @@
+import json
+import uuid
+import hashlib
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+CAPSULE_FILE = ".librarian/capsules.json"
+ARCHIVE_FILE = ".librarian/archive/archived_capsules.json"
+
+
+def _load() -> list[dict]:
+    path = Path(CAPSULE_FILE)
+    if not path.exists():
+        return []
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _save(capsules: list[dict]):
+    Path(CAPSULE_FILE).write_text(json.dumps(capsules, indent=2), encoding="utf-8")
+
+
+def create(task: str, reasoning: str, files_changed: list[str] = None):
+    capsules = _load()
+    capsule = {
+        "id": str(uuid.uuid4()),
+        "project_id": hashlib.sha256(os.getcwd().encode()).hexdigest()[:16],
+        "file": (files_changed or [""])[0],
+        "decision": task,
+        "reason": reasoning,
+        "confidence": 0.5,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "embed_text": f"{task} because {reasoning}",
+        "outcome": "approved",
+    }
+    capsules.append(capsule)
+    _save(capsules)
+    return capsule
+
+
+def approve(capsule_id: str):
+    capsules = _load()
+    for c in capsules:
+        if c["id"] == capsule_id:
+            c["outcome"] = "approved"
+            c["confidence"] = min(c["confidence"] * 1.15, 1.0)
+            break
+    _save(capsules)
+
+
+def undo(capsule_id: str):
+    capsules = _load()
+    for c in capsules:
+        if c["id"] == capsule_id:
+            c["outcome"] = "undone"
+            c["confidence"] *= 0.6
+            break
+    _save(capsules)
+    _archive_low_confidence()
+
+
+def decay():
+    capsules = _load()
+    now = datetime.now(timezone.utc)
+    for c in capsules:
+        if c["outcome"] == "ignored":
+            ts = datetime.fromisoformat(c["timestamp"])
+            days = (now - ts).days
+            c["confidence"] *= 0.98 ** days
+    _save(capsules)
+    _archive_low_confidence()
+
+
+def _archive_low_confidence():
+    capsules = _load()
+    keep = []
+    archive = []
+    for c in capsules:
+        if c["confidence"] < 0.4:
+            archive.append(c)
+        else:
+            keep.append(c)
+    if archive:
+        _save(keep)
+        Path(".librarian/archive").mkdir(parents=True, exist_ok=True)
+        existing = []
+        if Path(ARCHIVE_FILE).exists():
+            existing = json.loads(Path(ARCHIVE_FILE).read_text(encoding="utf-8"))
+        existing.extend(archive)
+        Path(ARCHIVE_FILE).write_text(json.dumps(existing, indent=2), encoding="utf-8")
+
+
+def get_all() -> list[dict]:
+    return _load()

librarian/memory/chunker.py

@@ -0,0 +1,183 @@
+import ast
+import os
+import re
+from datetime import datetime, timezone
+
+
+def chunk_file(path: str) -> list[dict]:
+    ext = os.path.splitext(path)[1].lower()
+    try:
+        with open(path, encoding="utf-8") as f:
+            content = f.read()
+    except UnicodeDecodeError:
+        with open(path, encoding="latin-1") as f:
+            content = f.read()
+
+    if ext == ".py":
+        return _chunk_python(path, content)
+    elif ext in (".js", ".ts", ".jsx", ".tsx"):
+        return _chunk_js(path, content)
+    elif ext in (".md", ".txt"):
+        return _chunk_text(path, content)
+    else:
+        return _chunk_generic(path, content)
+
+
+def _chunk_python(path: str, content: str) -> list[dict]:
+    chunks = []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return _chunk_generic(path, content)
+
+    lines = content.splitlines()
+    mtime = datetime.fromtimestamp(os.path.getmtime(path), tz=timezone.utc).isoformat()
+
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            start = node.lineno - 1
+            end = node.end_lineno or start + 1
+            chunk_text = "\n".join(lines[start:end])
+            chunks.append({
+                "content": chunk_text,
+                "metadata": {
+                    "file_path": path,
+                    "chunk_type": "function",
+                    "name": node.name,
+                    "language": "python",
+                    "start_line": start + 1,
+                    "end_line": end,
+                    "last_modified": mtime,
+                },
+            })
+        elif isinstance(node, ast.ClassDef):
+            start = node.lineno - 1
+            end = node.end_lineno or start + 1
+            chunk_text = "\n".join(lines[start:end])
+            chunks.append({
+                "content": chunk_text,
+                "metadata": {
+                    "file_path": path,
+                    "chunk_type": "class",
+                    "name": node.name,
+                    "language": "python",
+                    "start_line": start + 1,
+                    "end_line": end,
+                    "last_modified": mtime,
+                },
+            })
+
+    if not chunks:
+        chunks.append({
+            "content": content,
+            "metadata": {
+                "file_path": path,
+                "chunk_type": "module",
+                "name": os.path.basename(path),
+                "language": "python",
+                "start_line": 1,
+                "end_line": len(lines),
+                "last_modified": mtime,
+            },
+        })
+    return chunks
+
+
+def _chunk_js(path: str, content: str) -> list[dict]:
+    pattern = r"^(?:export\s+)?(?:async\s+)?(?:function\s+\w+|const\s+\w+\s*=\s*(?:async\s+)?(?:\([^)]*\)\s*=>|function)|class\s+\w+)"
+    lines = content.splitlines()
+    mtime = datetime.fromtimestamp(os.path.getmtime(path), tz=timezone.utc).isoformat()
+    lang = "javascript" if os.path.splitext(path)[1] in (".js", ".jsx") else "typescript"
+
+    chunks = []
+    for i, line in enumerate(lines):
+        if re.match(pattern, line.strip()):
+            end = min(i + 50, len(lines))
+            chunk_text = "\n".join(lines[i:end])
+            name_match = re.search(r"(?:function|class|const)\s+(\w+)", line)
+            chunks.append({
+                "content": chunk_text,
+                "metadata": {
+                    "file_path": path,
+                    "chunk_type": "function",
+                    "name": name_match.group(1) if name_match else "unknown",
+                    "language": lang,
+                    "start_line": i + 1,
+                    "end_line": end,
+                    "last_modified": mtime,
+                },
+            })
+
+    if not chunks:
+        chunks.append({
+            "content": content,
+            "metadata": {
+                "file_path": path,
+                "chunk_type": "module",
+                "name": os.path.basename(path),
+                "language": lang,
+                "start_line": 1,
+                "end_line": len(lines),
+                "last_modified": mtime,
+            },
+        })
+    return chunks
+
+
+def _chunk_text(path: str, content: str) -> list[dict]:
+    mtime = datetime.fromtimestamp(os.path.getmtime(path), tz=timezone.utc).isoformat()
+    chunks = []
+    sections = re.split(r"\n(?=#{1,3}\s)", content)
+    for section in sections:
+        section = section.strip()
+        if not section:
+            continue
+        heading_match = re.match(r"^#{1,3}\s+(.*)", section)
+        chunks.append({
+            "content": section,
+            "metadata": {
+                "file_path": path,
+                "chunk_type": "text",
+                "name": heading_match.group(1) if heading_match else os.path.basename(path),
+                "language": "markdown",
+                "start_line": 1,
+                "end_line": content[:content.find(section)].count("\n") + section.count("\n") + 1,
+                "last_modified": mtime,
+            },
+        })
+    if not chunks:
+        chunks.append({
+            "content": content,
+            "metadata": {
+                "file_path": path,
+                "chunk_type": "text",
+                "name": os.path.basename(path),
+                "language": "text",
+                "start_line": 1,
+                "end_line": content.count("\n") + 1,
+                "last_modified": mtime,
+            },
+        })
+    return chunks
+
+
+def _chunk_generic(path: str, content: str) -> list[dict]:
+    mtime = datetime.fromtimestamp(os.path.getmtime(path), tz=timezone.utc).isoformat()
+    chunk_size = 500
+    overlap = 50
+    chunks = []
+    for i in range(0, len(content), chunk_size - overlap):
+        chunk_text = content[i:i + chunk_size]
+        chunks.append({
+            "content": chunk_text,
+            "metadata": {
+                "file_path": path,
+                "chunk_type": "module",
+                "name": os.path.basename(path),
+                "language": os.path.splitext(path)[1].lstrip("."),
+                "start_line": content[:i].count("\n") + 1,
+                "end_line": content[:i + len(chunk_text)].count("\n") + 1,
+                "last_modified": mtime,
+            },
+        })
+    return chunks

librarian/memory/decision_log.py

@@ -0,0 +1,36 @@
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+LOG_FILE = ".librarian/decisions.jsonl"
+
+
+def append(entry: dict):
+    entry["id"] = str(uuid.uuid4())
+    entry["timestamp"] = datetime.now(timezone.utc).isoformat()
+    with open(LOG_FILE, "a", encoding="utf-8") as f:
+        f.write(json.dumps(entry) + "\n")
+
+
+def get_last(n: int = 5) -> list[dict]:
+    path = Path(LOG_FILE)
+    if not path.exists():
+        return []
+    lines = path.read_text(encoding="utf-8").strip().splitlines()
+    entries = [json.loads(line) for line in lines if line.strip()]
+    return entries[-n:]
+
+
+def mark_undone(entry_id: str):
+    path = Path(LOG_FILE)
+    if not path.exists():
+        return
+    lines = path.read_text(encoding="utf-8").strip().splitlines()
+    updated = []
+    for line in lines:
+        entry = json.loads(line)
+        if entry.get("id") == entry_id:
+            entry["outcome"] = "undone"
+        updated.append(json.dumps(entry))
+    path.write_text("\n".join(updated) + "\n", encoding="utf-8")

librarian/memory/indexer.py

@@ -0,0 +1,96 @@
+import json
+import os
+import re
+from pathlib import Path
+from librarian.actions.file_ops import list_files
+from librarian.memory.chunker import chunk_file
+from librarian.utils.config import CHROMA_PERSIST_DIR, EMBED_MODEL
+from librarian.utils.ui import spinner, print_success, print_muted
+
+CHUNK_EXTENSIONS = [
+    ".py", ".js", ".ts", ".jsx", ".tsx",
+    ".md", ".txt", ".yaml", ".yml", ".toml",
+    ".json", ".html", ".css", ".sh", ".sql",
+]
+
+META_FILE = ".librarian/index_meta.json"
+
+_model = None
+_client = None
+
+
+def _get_model():
+    global _model
+    if _model is None:
+        from sentence_transformers import SentenceTransformer
+        _model = SentenceTransformer(EMBED_MODEL)
+    return _model
+
+
+def _get_client():
+    global _client
+    if _client is None:
+        import chromadb
+        _client = chromadb.PersistentClient(path=CHROMA_PERSIST_DIR)
+    return _client
+
+
+def _sanitize_collection_name(name: str) -> str:
+    name = re.sub(r"[^a-zA-Z0-9_\-\.\s]", "", name)
+    name = re.sub(r"\s+", "_", name).strip("_")
+    if len(name) < 3:
+        name = f"project_{name}" if name else "project"
+    return name[:512]
+
+
+def index_project():
+    model = _get_model()
+    client = _get_client()
+    project_name = _sanitize_collection_name(os.path.basename(os.getcwd()))
+    collection = client.get_or_create_collection(name=project_name)
+
+    files = list_files(".", CHUNK_EXTENSIONS)
+    all_chunks = []
+    for f in files:
+        all_chunks.extend(chunk_file(f))
+
+    existing = collection.get()
+    existing_ids = set(existing["ids"]) if existing["ids"] else set()
+
+    to_add = []
+    seen_ids = set()
+    for idx, chunk in enumerate(all_chunks):
+        chunk_id = f"{chunk['metadata']['file_path']}:{chunk['metadata']['start_line']}:{idx}"
+        if chunk_id in existing_ids or chunk_id in seen_ids:
+            continue
+        seen_ids.add(chunk_id)
+        to_add.append((chunk_id, chunk))
+
+    with spinner("indexing files...") as prog:
+        task = prog.add_task("indexing", total=len(to_add))
+        batch_size = 100
+        for i in range(0, len(to_add), batch_size):
+            batch = to_add[i:i + batch_size]
+            ids = [c[0] for c in batch]
+            documents = [c[1]["content"] for c in batch]
+            metadatas = [c[1]["metadata"] for c in batch]
+            embeddings = model.encode(documents).tolist()
+            collection.add(
+                ids=ids,
+                documents=documents,
+                metadatas=metadatas,
+                embeddings=embeddings,
+            )
+            prog.update(task, advance=len(batch))
+
+    meta = {
+        "project": project_name,
+        "file_count": len(files),
+        "chunk_count": collection.count(),
+        "indexed_at": __import__("datetime").datetime.now(__import__("datetime").timezone.utc).isoformat(),
+    }
+    Path(".librarian").mkdir(exist_ok=True)
+    Path(META_FILE).write_text(json.dumps(meta, indent=2), encoding="utf-8")
+
+    print_success(f"{len(files)} files, {collection.count()} chunks indexed")
+    return meta