Metadata-Version: 2.4
Name: brainmarks-agent
Version: 0.1.0
Summary: Local-first agentic bookmark RAG and knowledge base
Requires-Python: >=3.11
Description-Content-Type: text/markdown
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: duckduckgo-search>=5.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: langfuse
Requires-Dist: langfuse>=2.0.0; extra == "langfuse"
Provides-Extra: deepeval
Requires-Dist: deepeval>=1.0.0; extra == "deepeval"

# BrainMarks

**Local-first, agentic bookmark RAG.** Turn your browser bookmarks into a queryable knowledge base — ask a natural-language question and get a cited, synthesized answer from your own saved pages. Nothing leaves your machine.

```
❯ 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
```

## Features (Phase 1 — shipped)

- **Agentic chat** — LangGraph agent with tool calling (search bookmarks, fetch pages, web search). SSE streaming, live RAG pipeline visualization, session memory.
- **Hybrid retrieval** — LlamaIndex `QueryFusionRetriever`: vector (ChromaDB + sentence-transformers) fused with BM25 (Reciprocal Rank Fusion), deduplicated by source.
- **Browser extension** (Chrome / Brave / Edge / Firefox) — one-click full import, selective tree picker, save current page, opt-in background sync, side-panel chat.
- **Webapp** — chat, library (bookmarks + web sources), dashboard, admin. Hacker-terminal design.
- **BYOM** — bring your own model: Ollama, OpenAI, Groq, Anthropic, OpenRouter, or any OpenAI-compatible endpoint. Provider presets in Admin, no raw URLs.
- **Privacy-first** — zero telemetry, local SQLite + ChromaDB, air-gapped capable (Ollama + local embeddings). `PRIVACY_MODE=strict` blocks non-localhost models by default.
- **Prompt-injection guardrail** — retrieved content is structurally delimited as untrusted data; the agent can't be redirected by page contents.

## 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. `brainmarks` sets up autostart and prints your webapp URL, extension store links, and access token.

Then install the extension (Chrome Web Store / Firefox Add-ons) — enable sync in the popup and import your bookmarks.

## Quick Start

1. Install (above), run `brainmarks`
2. Install the extension, toggle sync ON, import bookmarks (full or pick folders)
3. Configure your model: Admin → provider (e.g. OpenRouter) + model + API key, or leave default Ollama
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 a read/search surface; remote mode (Phase 2) makes your index reachable from anywhere.

## 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` | `llama3.2:3b` | 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 (Phase 2 wiring; dedicated tagger model optional) |

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](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
                      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                    # 56 tests
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/`.

Full project docs live in the Obsidian vault (see `AGENTS.md` for the path).

## Roadmap

- **Phase 1 ✅** — core RAG, agent, extension, webapp, shipping
- **Phase 2 (next)** — LLM categorization (real topic tags), web sources lifecycle, MCP server/client, Mem0 memory, document upload, remote mode + token auth
- **Phase 3** — dead-link detection, duplicates, recommendations, graph memory (Cognee opt-in)
- **Phase 4** — web archiving, history indexing, knowledge graph viz, scheduled digests, multi-user
- **Phase 5** — REST API, collaborative annotations, mobile companion

## License

MIT. Dependencies MIT / Apache-2.0 compatible.
