Metadata-Version: 2.4
Name: brainmarks-agent
Version: 0.2.2
Summary: Agentic RAG for your browser bookmarks — local-first, BYOM, privacy-focused.
License-Expression: MIT
Project-URL: Homepage, https://github.com/Akshxdev/BrainMarks
Project-URL: Repository, https://github.com/Akshxdev/BrainMarks
Project-URL: Documentation, https://github.com/Akshxdev/BrainMarks/blob/main/docs/api.md
Project-URL: Issues, https://github.com/Akshxdev/BrainMarks/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.28.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: chromadb>=0.4.24
Requires-Dist: readability-lxml>=0.8.1
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: sentence-transformers>=2.5.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: llama-index-core>=0.10.0
Requires-Dist: llama-index-vector-stores-chroma>=0.1.0
Requires-Dist: llama-index-retrievers-bm25>=0.1.0
Requires-Dist: langgraph>=0.2.0
Requires-Dist: langchain-core>=0.2.0
Requires-Dist: langchain-community>=0.2.0
Requires-Dist: langchain-openai>=0.1.0
Requires-Dist: litellm>=1.30.0
Requires-Dist: ddgs>=9.0.0
Requires-Dist: pymupdf>=1.28.0
Requires-Dist: python-docx>=1.2.0
Requires-Dist: python-multipart>=0.0.32
Requires-Dist: mcp[cli,fastmcp]>=1.0
Requires-Dist: fastmcp>=3.4.5
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pyright>=1.1.350; extra == "dev"
Provides-Extra: mem0
Requires-Dist: mem0ai>=2.0.0; extra == "mem0"
Provides-Extra: langfuse
Requires-Dist: langfuse>=2.0.0; extra == "langfuse"
Provides-Extra: deepeval
Requires-Dist: deepeval>=1.0.0; extra == "deepeval"
Dynamic: license-file

# BrainMarks

**Agentic RAG for your browser bookmarks — local-first, BYOM, privacy-focused.** Turn your browser bookmarks into a private, queryable knowledge base — ask a natural-language question and get a cited, synthesized answer from your own saved pages.

![PyPI - Version](https://img.shields.io/pypi/v/brainmarks-agent)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/brainmarks-agent)
![PyPI - License](https://img.shields.io/pypi/l/brainmarks-agent)
![PyPI - Downloads](https://img.shields.io/pypi/dm/brainmarks-agent)

```
❯ what was that article about local-first architecture?

  Three bookmarks in your index cover local-first architecture:
  - The Local-First Software Manifesto argues apps work offline first... [1]
  - Embedded RAG comparison shows local vector stores remove servers... [2]

  [tool] search_bookmarks · [tool] fetch_page
```

## Install

**Prerequisite:** install `uv` (the Python package/venv manager) once:

```bash
# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**Install BrainMarks (any platform — Linux / macOS / Windows):**

```bash
uv tool install brainmarks-agent
brainmarks          # starts server on :8008 + opens the webapp
```

The wheel bundles the webapp UI and the CLI — one artifact, no build step. `brainmarks` runs the guided setup (provider, model, autostart) and prints your webapp URL, extension store links, and access token.

## Quick Start

1. Install (above), run `brainmarks`
2. Install the browser extension (below), toggle sync ON, import your bookmarks (full or pick folders)
3. Configure your model: Admin → provider (e.g. OpenRouter) + model + API key, or leave the local default
4. Ask in Chat or the side panel: *"what was that article about local-first architecture?"*

> **Desktop captures, everywhere reads:** the extension (bookmark capture) is desktop-only — mobile browsers have no extension API. The webapp is the read/search surface, reachable remotely via token auth.

## Command Line

The `brainmarks` CLI is bundled with the wheel. Lightweight commands run instantly (no model load); only `start` / `mcp` / `eval` build the backend stack.

```bash
brainmarks                          # shortcut for: brainmarks start
brainmarks --help                   # top-level help
brainmarks -v / --version           # print version
```

| Command | Description |
|---|---|
| `brainmarks start [--port P] [--host H] [--config FILE] [--no-open]` | Start the backend server + webapp |
| `brainmarks setup [--provider X] [--model M] [--api-key K] [-y]` | Guided (or non-interactive `-y`) configuration wizard |
| `brainmarks autostart on\|off\|enable\|disable` | Configure background autostart service |
| `brainmarks doctor` | System diagnostics: data dir, config, static assets |
| `brainmarks token show` | Show the access token |
| `brainmarks mcp [--transport stdio\|http]` | Run the MCP server for external AI clients |
| `brainmarks config set KEY VALUE` | Set a config value (validated; `.env` written) |
| `brainmarks config get KEY` | Read a config value (secrets masked) |
| `brainmarks list [--limit N] [--category C]` | List bookmarks (needs running server) |
| `brainmarks search QUERY [--top-k N]` | Search saved content (needs running server) |
| `brainmarks status` | Server health + config status |
| `brainmarks stop [--port P] [--force]` | Stop the running server (graceful SIGTERM by default) |
| `brainmarks eval [--golden FILE] [--quiet]` | Run the golden-set evaluation harness |

Common keys for `config set/get`: `PROVIDER`, `LLM_MODEL`, `LLM_BASE_URL`, `LLM_API_KEY`,
`EMBEDDING_MODEL`, `EMBEDDING_PROVIDER`, `PRIVACY_MODE`, `MEMORY_BACKEND`, `PORT`, `HOST`.

## Browser Extension

The extension imports/syncs your browser bookmarks into BrainMarks and adds a side-panel chat you can use while browsing.

**Chrome Web Store (Chrome / Edge / Brave / Opera):** install *BrainMarks* from the Chrome Web Store, then open the popup and toggle **Auto-sync ON** to import your bookmarks.

**Manual load (development / self-hosted):**

1. Build or download the packaged zip: `./scripts/package_extension.sh` → `dist/brainmarks-extension-<version>.zip`
2. Open `chrome://extensions` → enable **Developer mode**
3. Click **Load unpacked** → select the `extension/` folder (or drag in the zip)
4. Open the popup → toggle **Auto-sync ON** → import bookmarks (one-click or selective tree)

The extension connects to the local backend at `127.0.0.1:8008` (host permission). If the backend isn't running, the popup shows the install command for your OS.

## Features

- **Agentic chat** — a LangGraph agent with tool calling (search bookmarks, fetch pages, web search, memory), SSE streaming, session memory, and named sessions.
- **Hybrid retrieval** — LlamaIndex `QueryFusionRetriever`: vector (ChromaDB + sentence-transformers) fused with BM25 (Reciprocal Rank Fusion), deduplicated by source.
- **RAG over everything you save** — bookmarks, **web sources**, and **uploaded documents** (PDF, Markdown, TXT, DOCX, HTML with OCR-aware scanning) all become queryable knowledge.
- **Browser extension** (Chrome / Brave / Edge / Opera) — one-click full import, selective tree picker, save current page, opt-in background sync, side-panel chat with markdown, citations, and inline approval prompts.
- **Webapp** — chat, library (bookmarks + web sources + documents), knowledge-graph view, a full Admin panel, and a rich dashboard.
- **BYOM** — bring your own model: Ollama, OpenAI, Groq, Anthropic, OpenRouter, or any OpenAI-compatible endpoint. Provider presets in Admin, no raw URLs.
- **Observability** — every agent run is traced locally: what it did, tool calls, tokens, cost, latency; raw per-run traceability is one click away.
- **Evaluation** — a golden-set harness plus optional DeepEval metrics and LLM-as-judge, with sampled live auto-eval of real chat responses.
- **Guardrails** — prompt-injection defense (retrieved content is structurally delimited as untrusted data), tool-permission interrupts for mutating actions, and a privacy-mode gate. A Guardrails dashboard shows what's active and what's been approved.
- **Memory** — the agent remembers conversational facts (never bookmark content) and recalls them across sessions.
- **Agent-side caching** — embedding, retrieval, and exact-answer caches (incl. live-tool answers with a short TTL) keep repeated questions fast and cheap; a Cache dashboard shows hits.
- **MCP dual-role** — expose BrainMarks tools to other AI apps (stdio / Streamable HTTP), or add external MCP tools to the agent loop.
- **Dead-link detection, duplicates, and recommendations** — probe stored sources, merge near-dup groups, and surface "you might also like" suggestions.
- **Scheduled digests** — periodic local summaries of your saved topics, viewable in the dashboard.
- **Privacy-first** — no telemetry, local SQLite + ChromaDB, air-gapped capable (Ollama + local embeddings). `PRIVACY_MODE=strict` blocks non-localhost models by default.

## Configuration

Config precedence: `environment vars > YAML (--config) > CWD .env > ~/.brainmarks/.env > defaults`.

| Key | Default | Purpose |
|-----|---------|---------|
| `PROVIDER` | `ollama` | `ollama` \| `openai` \| `groq` \| `anthropic` \| `openrouter` \| `custom` |
| `LLM_MODEL` | `gemma4:e2b` | Model name (provider-prefixed for cloud, e.g. `openrouter/google/gemma-2-9b-it`) |
| `LLM_API_KEY` | `ollama` | Provider key (leave blank in Admin to keep current) |
| `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Runs locally via sentence-transformers (downloads once; no key) |
| `PRIVACY_MODE` | `strict` | `strict` blocks non-localhost LLM endpoints; `disabled` allows cloud providers |
| `TAGGING_ENABLED` | `true` | LLM tagging at ingestion |

Set them in the Admin panel (persists across restarts) or `.env`.

## Architecture

**API:** the stable, third-party-consumable REST surface (auth, curl quickstart,
endpoint reference) is documented in [docs/api.md](https://github.com/Akshxdev/BrainMarks/blob/main/docs/api.md).
Interactive docs at
`/docs` (Swagger) and `/openapi.json`.

```
Browser Extension (vanilla MV3)  ─┐
Webapp (React + Vite + shadcn + motion) ─┤── HTTP :8008
                                         ▼
                    FastAPI backend
                      LangGraph agent (LiteLLM router, MemorySaver checkpointer)
                        Tools: search_bookmarks · fetch_page · web_search · remember · MCP
                      LlamaIndex QueryFusionRetriever (vector + BM25, RRF)
                      Ingestion: fetch → extract → chunk → embed → tag
                      Stores: SQLite (metadata) · ChromaDB (vectors) · ~/.brainmarks
```

## Development

```bash
git clone https://github.com/Akshxdev/BrainMarks.git && cd BrainMarks
uv sync                          # backend deps + dev group
uv run brainmarks                # backend on :8008
cd webapp && npm install && npm run dev   # webapp on :5173 (CORS configured)

uv run pytest                    # backend test suite
cd webapp && npm run build       # type-check + bundle
python scripts/generate_openapi.py  # regenerate frontend API types from the contract
```

Extension: `chrome://extensions` → Developer mode → Load unpacked → `extension/`.

## License

MIT. Dependencies MIT / Apache-2.0 compatible.
