Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,549 @@
+---
+title: BrainAPI
+emoji: 🧠
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+<p align="center">
+  <a href="https://discord.gg/VTngQTaeDf"><img src="https://img.shields.io/badge/Discord-Join%20Lumen%20Brain-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"/></a>
+  <img src="https://img.shields.io/badge/version-2.19.0--dev-blue?style=for-the-badge" alt="Version"/>
+  <img src="https://img.shields.io/badge/python-3.11+-green?style=for-the-badge&logo=python&logoColor=white" alt="Python"/>
+  <img src="https://img.shields.io/badge/license-BUSL--1.1-blue?style=for-the-badge" alt="License"/>
+</p>
+
+<h1 align="center">🧠 BrainAPI</h1>
+
+<p align="center">
+  <strong>Turn raw text into a living knowledge graph — automatically.</strong>
+  <br/><br/>
+  <em>You send text. A swarm of agents reads it, takes notes, and draws the graph for you.<br/>
+  Then you ask questions and get answers backed by a traceable path — not a similarity guess.</em>
+</p>
+
+<p align="center">
+  <a href="https://brainapi.lumen-labs.ai/">BrainAPI Cloud</a> •
+  <a href="#-quickstart-fastest-way-to-run-it">Quickstart</a> •
+  <a href="#-what-is-brainapi">What it is</a> •
+  <a href="#️-how-it-works-the-agent-swarm">How it works</a> •
+  <a href="#-where-you-can-use-it">Use cases</a> •
+  <a href="https://brainapi.lumen-labs.ai/docs/v2">Docs ↗</a>
+</p>
+
+<a href="https://youtu.be/ECOleTRjl64?si=fBUALoYvsiUl-BPC">
+  <img src=".github/assets/screen-video.png" width="100%" alt="Watch the demo" />
+</a>
+
+<p align="center">
+  <img src="https://pbs.twimg.com/media/G6jXa2HXsAAJhDO?format=jpg&name=4096x4096" alt="BrainAPI Concept Art" width="1000" style="border-radius:4px;box-shadow:0 2px 12px rgba(0,0,0,0.09);margin-bottom:16px;"/>
+</p>
+
+---
+
+## 📖 What is BrainAPI?
+
+**BrainAPI reads your text and builds a knowledge graph out of it — by itself.**
+
+You feed it documents, notes, messages or events. Behind the scenes a group of AI agents reads everything, understands what happened, writes down the facts, and connects them into a queryable graph. You then ask questions in plain language and get answers grounded in the actual connections it found.
+
+The trick is that BrainAPI is **event-centric**. Instead of just storing "A is related to B," it captures _who did what, to whom, when, and in what context_. That's what lets it answer multi-step questions and always show you the path it used to get there.
+
+Feed it one sentence:
+
+```
+"Emily organized the AI Ethics Meetup in London on March 8, 2024."
+```
+
+Ask something it was never explicitly told:
+
+```python
+result = client.retrieveContext("Who organized AI events in London in Q1 2024?")
+# → "Emily organized the AI Ethics Meetup in London on 2024-03-08."
+# → result.triples shows the full graph path used to derive this
+```
+
+That trace is the difference. Not a nearest-neighbour guess — a **reasoned, walkable path through a graph it built for you.**
+
+> **[▶ Watch the full demo →](https://youtu.be/ECOleTRjl64?si=fBUALoYvsiUl-BPC)**
+
+---
+
+## 🏃 Quickstart (fastest way to run it)
+
+The quickest way to get BrainAPI running is the **`brainapi` TUI** — a CLI that clones the project, sets up a Python environment, configures services, starts backing services, and launches everything for you. Run the interactive wizard, or pass flags to skip prompts (hybrid / non-interactive).
+
+```sh
+npm install -g brainapi-tui
+brainapi init     # clone, install deps, setup wizard (or pass flags to skip prompts)
+brainapi start    # backing services + API + MCP + worker + console
+```
+
+When it's up:
+
+- **API** → `http://localhost:8000`
+- **Console (web UI)** → `http://localhost:8000/console`
+- **MCP server** → `http://localhost:8001/mcp`
+
+Set `PUBLIC_BASE_URL` to the externally visible, scheme-qualified deployment URL
+(without a trailing slash) when BrainAPI is served behind a proxy. BrainAPI uses it
+to publish stable workspace API and Console URLs such as
+`$PUBLIC_BASE_URL/brains/company/api` and
+`$PUBLIC_BASE_URL/console/w/company/`. If it is unset, discovery responses use the
+request base URL.
+
+### Workspace API base
+
+Every active workspace publishes a stable API base on the same BrainAPI
+deployment:
+
+```text
+https://HOST/brains/aux-research/api
+```
+
+Authenticate with either `Authorization: Bearer $BRAIN_PAT` or the `BrainPAT`
+header. The workspace path selects the brain, so `X-Brain-ID` is not required.
+If a caller supplies `X-Brain-ID` or a query/body `brain_id` that conflicts with
+the workspace path, BrainAPI returns `409 BRAIN_SCOPE_CONFLICT`. Existing clients
+using legacy endpoints plus `X-Brain-ID` remain supported.
+
+The system PAT may access every active workspace. A per-brain PAT may access only
+the workspace backed by that brain; using it with another workspace returns
+`403`. Unknown credentials return `401`, unknown workspace slugs return `404`,
+and archived workspaces return `410`. These rules apply consistently to the
+native API, Agent API, and workspace MCP endpoint.
+
+Useful discovery URLs are:
+
+```text
+GET /brains/aux-research/api
+GET /brains/aux-research/api/openapi.json
+```
+
+The workspace facade includes ingest, retrieval/data, graph model, task, and
+brain-specific metadata routes. System management routes are never mirrored.
+
+| Hosted route family | Methods | Scope/behavior |
+| --- | --- | --- |
+| `/ingest/`, `/ingest/structured`, `/ingest/file` | `POST` | Queues the existing ingestion workers with the resolved workspace `brain_id`. |
+| `/retrieve/*` | `GET`, `POST` | Reuses the existing context, search, graph, observation, data, recommendation, and vector handlers. |
+| `/model/entity`, `/model/relationship` | `POST`, `PUT` | Reuses the existing graph mutation handlers. |
+| `/tasks/`, `/tasks/{task_id}` | `GET` | Reads only the task namespace for the resolved workspace; foreign task IDs return `404`. |
+| `/meta/relationships-properties`, `/meta/entity-labels`, `/meta/entity-properties` | `GET` | Exposes brain-specific metadata only. `/meta/login-info` is intentionally excluded. |
+
+All paths in this table are relative to
+`/brains/{workspace_slug}/api`. Management (`/system/*`), health, demo, and
+plugin routes are not implicitly exposed. The discovery endpoint describes the
+active workspace, while its OpenAPI document contains only this allowlisted
+facade.
+
+### Using a Brain Workspace from an Agent
+
+An external agent only needs a deployment URL, workspace slug, and existing
+BrainPAT:
+
+```ini
+BRAINAPI_BASE_URL=https://HOST
+BRAINAPI_WORKSPACE=aux-research
+BRAINAPI_PAT=...
+```
+
+These values derive three stable surfaces:
+
+```text
+Native API: https://HOST/brains/aux-research/api
+Agent API:  https://HOST/brains/aux-research/agent
+MCP:        https://HOST/brains/aux-research/mcp
+```
+
+Retrieve compact agent context without knowing BrainAPI's internal route tree:
+
+```bash
+curl \
+  -H "Authorization: Bearer $BRAINAPI_PAT" \
+  -H "Content-Type: application/json" \
+  https://HOST/brains/aux-research/agent/context \
+  -d '{"query":"What do we know about X?"}'
+```
+
+Queue a memory write through the existing asynchronous ingestion pipeline:
+
+```bash
+curl \
+  -H "Authorization: Bearer $BRAINAPI_PAT" \
+  -H "Content-Type: application/json" \
+  -H "Idempotency-Key: hermes-session-42-message-7" \
+  https://HOST/brains/aux-research/agent/memory \
+  -d '{"text":"The customer prefers annual billing.","metadata":{"source":"hermes","session_id":"42"}}'
+```
+
+Agent memory metadata is forwarded through the ingestion model's existing
+`meta_keys` support. Arbitrary metadata is retained as source metadata where the
+configured ingestion backend already supports it; no separate metadata store is
+created. Specifically, standard text ingestion persists it on the source
+`TextChunk`, copies it into the data-vector metadata, and attaches it to generated
+observations. Stored chunks can be filtered through the existing
+`/retrieve/text-chunks?metadata_eq=...` API. `Idempotency-Key` stabilizes the
+returned task identifier, but it is not a distributed duplicate-content
+guarantee—retries after a successfully queued request may still process the
+content again.
+
+Agent memory writes are asynchronous: a successful request returns `202`,
+`status: "queued"`, and the actual ingestion `task_id`. `Task-Identifier` and
+`Idempotency-Key` use their value as that task identifier, so repeated requests
+with the same key return the same identifier; they do not provide an exactly-once
+persistence guarantee.
+
+The agent schema is available at
+`/brains/aux-research/agent/openapi.json`, and machine-readable capabilities at
+`/brains/aux-research/agent/capabilities`.
+
+BrainAPI's existing stateless Streamable HTTP MCP server remains one process on
+the MCP port. The bundled reverse proxy maps the workspace-aware transport at
+`https://HOST/brains/aux-research/mcp` to that server. The tools are
+`memory_search`, `memory_context`, `memory_store`, `memory_observe`,
+`memory_neighbors`, `memory_entity`, and `memory_task_status`; workspace scope is
+derived from the URL and is not a tool argument. Direct development connections
+without the reverse proxy use the MCP server port with the same path, for example
+`http://localhost:8001/brains/aux-research/mcp`.
+
+The workspace endpoint uses a semantic-only MCP registry. Legacy raw MCP tools
+remain available at `/mcp` for backward compatibility, but they are not listed
+or callable through `/brains/{workspace_slug}/mcp`. Plugins likewise appear in
+the workspace registry only when they explicitly use the workspace-safe MCP
+registration contract.
+
+Log in to the console with the `BRAINPAT_TOKEN` generated during setup. That's it — you have a working brain.
+
+### TUI commands
+
+| Command           | What it does                                                                                |
+| ----------------- | ------------------------------------------------------------------------------------------- |
+| `brainapi init`   | Clone into `~/.brainapi/source/`, create a venv, run setup (flags skip individual prompts)  |
+| `brainapi start`  | Bring up backing services and run the API, MCP server, and Celery worker (Ctrl-C stops all) |
+| `brainapi config` | Re-open the setup wizard to change one area (databases, models, pipeline, plugins, …)       |
+| `brainapi doctor` | Check Python, Docker, Ollama, cloud credentials, and configured services                    |
+| `brainapi update` | `git pull` the install and reinstall Python dependencies                                    |
+
+Running any command (except `help`) before `init` will run `init` first automatically.
+
+**Useful `brainapi init` flags:** `--defaults`, `--vector-db`, `--models-mode`, provider keys/models, `--brainpat-token`, `--no-plugins`, `--no-start-services` (any passed value skips that wizard prompt). **`brainapi start` flags:** `--pipeline accurate|lightweight`, `--no-services`, `--no-api` / `--no-mcp` / `--no-worker`, `--only api,mcp,worker`. Full reference → [`tui/README.md`](tui/README.md).
+
+> The TUI installs into `~/.brainapi/` (source, venv, `.env`, and `state.json`) — separate from any git clone. Override with `BRAINAPI_HOME`, `BRAINAPI_REPO_URL`, or `BRAINAPI_BRANCH`.
+
+---
+
+## 🛠️ Run it locally (dev mode)
+
+If you're contributing or hacking on BrainAPI, run it straight from the repo with `make`:
+
+```sh
+git clone https://github.com/lumen-labs/brainapi2.git && cd brainapi2
+poetry install
+make start-all      # backing services + API (:8000) + MCP (:8001) + Celery worker
+```
+
+`make start-all` runs everything from source with hot reload enabled, so code changes are picked up live.
+
+**Console in dev mode:**
+
+```sh
+make build-console && make start-api   # serve console at http://localhost:8000/console
+# — or hot-reload the console UI separately —
+make start-api          # terminal 1
+make start-console-dev  # terminal 2 → http://localhost:5173/console/
+```
+
+**Other handy targets:** `make start-api`, `make start-mcp`, `make stop-all`, and `make install-extras` (auto-installs heavy ML extras like local OCR based on your `.env`).
+
+**Docker only** (pick a [deploy profile](deploy/README.md)):
+
+```sh
+# light — Postgres + DeepSeek + OpenAI embeddings
+cp deploy/env.light.example .env   # fill in secrets, then:
+docker compose -f deploy/docker-compose.light.yaml up -d
+
+# heavy — Neo4j + Milvus + Mongo + GCP/Azure (full resources)
+cp deploy/env.heavy.example .env
+docker compose -f deploy/docker-compose.heavy.yaml up -d
+```
+
+Then ingest your first data point:
+
+```sh
+curl -X POST http://localhost:8000/ingest/ \
+  -H "Authorization: Bearer $BRAINPAT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"data": {"data_type": "text", "text_data": "Emily organized the AI Ethics Meetup in London on 2024-03-08."}, "brain_id": "default"}'
+```
+
+---
+
+## 🖥️ The Console
+
+The Console is a web UI for exploring everything inside your brain: the **graph**, **text chunks**, **vectors**, **observations**, **tasks**, and an **ingest** page to push new data. It's served on the same port as the API at `http://localhost:8000/console` and you log in with your `BRAINPAT_TOKEN`.
+
+<p align="center">
+  <img src=".github/assets/console-sh.png" width="100%" alt="BrainAPI Console (screenshot coming soon)" />
+</p>
+
+> Set `CONSOLE_ENABLED=false` to disable static serving in environments where you don't want the UI exposed.
+
+---
+
+## ⚙️ How It Works: The Agent Swarm
+
+Every piece of text you send is read and discussed by a **swarm of specialized agents**. After they understand it, they write down notes and draw the graph. Each agent has one narrow job, which keeps the pipeline reliable and auditable end to end.
+
+```mermaid
+flowchart TD
+    Text["Raw text"] --> Scout["🔍 Scout<br/>extract ALL entities"]
+    Text --> Observer["📝 Observations Agent<br/>write notes about facts<br/>using prior context"]
+    Scout -->|entities| Architect["🏛️ Architect<br/>build event-centric<br/>relationships"]
+    Architect -->|relationships + entities| Janitor["🧹 Janitor<br/>verify correctness<br/>+ check for duplicates"]
+    Janitor -->|"errors + instructions"| Architect
+    Janitor -->|"OK"| Graph["📊 Knowledge Graph<br/>(append-only)"]
+    Observer --> Graph
+```
+
+1. **🔍 Scout** reads the text and extracts **all** the entities it contains — people, things, events, quantities.
+2. **📝 Observations Agent** runs alongside and writes down notes about the facts in the text, taking the previously known context into account.
+3. **🏛️ Architect** takes the Scout's entities, re-reads the text, and creates the connections between them as **event-centric relationships** — `subject —rel→ event —rel→ object`. Actions become first-class event hubs rather than flat edges.
+4. **🧹 Janitor** checks the Architect's work: are the relationships correct, and do similar nodes (the same entity) or triplets (the same fact) already exist in the graph? If something is wrong, the Janitor tells the Architect exactly what to fix and expects a corrected output, then checks again — looping until it's clean.
+
+### The Triangle of Attribution
+
+Every action is modeled as a central **Event Hub** connecting three points, which is what makes multi-hop, traceable answers possible:
+
+```
+                    ┌─────────────────┐
+                    │   EVENT HUB     │
+                    │  (Action Node)  │
+                    └────────┬────────┘
+                             │
+           ┌─────────────────┼─────────────────┐
+           ▼                 ▼                 ▼
+    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
+    │    ACTOR     │  │    TARGET    │  │   CONTEXT    │
+    │   (Source)   │  │ (Recipient)  │  │  (Anchor)    │
+    └──────────────┘  └──────────────┘  └──────────────┘
+         :MADE            :TARGETED       :OCCURRED_WITHIN
+```
+
+So `"Emily organized the AI Ethics Meetup in London"` becomes:
+
+```
+(Emily)-[:MADE]->(Organizing Event)-[:TARGETED]->(AI Ethics Meetup)
+                                     \-[:OCCURRED_WITHIN]->(London)
+```
+
+### Append-only by design
+
+BrainAPI follows an **append-only philosophy**: nothing is deleted from the graph. Every new action is appended as its own event node rather than overwriting what was already there. This keeps the full history intact and lets you **reconstruct how facts evolved over time** — events are never merged away, so the provenance trail always survives.
+
+### Two pipeline modes
+
+- **`accurate`** (default) — the full swarm runs: Scout extracts every entity, the Observations agent writes notes, and the Janitor validates and deduplicates the Architect's relationships.
+- **`lightweight`** — a faster, cheaper path that extracts only the most important entities and skips the heavier validation steps. Switch with `--pipeline lightweight` or `PIPELINE_MODE` in `.env`.
+
+Search (`GET|POST /retrieve/search`) is **off by default**. Set `SEARCH_ENABLED=true` to register the hit-list API. BM25 requires `DATA_DB=postgresql`; dense-only search (`SEARCH_USE_BM25=false`) is supported by either production profile. PostgreSQL writes BM25 `tsvector` indexes and uses halfvec HNSW when embeddings are >2000-d. Default light-profile retrieval is both channels fused (`SEARCH_FUSION=rrf`). The search p50 SLO is **< 200 ms excluding `embed.query`** — ask for `profile_stages` to split embed RTT from retrieve. `/retrieve/context` stays dense ∪ ILIKE unless search is on and `CONTEXT_PASSAGE_MODE` is `hybrid` / `bm25` / `dense`.
+
+---
+
+## 🔎 Retrieving Knowledge
+
+Once your data is in, BrainAPI exposes purpose-built retrieval endpoints (REST, on port `8000`):
+
+| Endpoint                     | Method | What you get                                                                                                     |
+| ---------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
+| `/retrieve/context`          | `POST` | **Relevant information for a piece of text** — one-shot graph triples, passages, historical context, and optional provenance; p50 target < 1000 ms |
+| `/retrieve/search`           | `GET`/`POST` | **Ranked search hits** (opt-in: `SEARCH_ENABLED=true`) — passages (BM25 ∪ dense) by default; optional `entities` / `events` / `communities` channels and `expand=neighbors`; p50 < 200 ms excluding embed |
+| `/retrieve/entity/status`    | `GET`  | **Existence check** for a specific entity — returns whether it exists, its node, relationships, and observations |
+| `/retrieve/entity/synergies` | `GET`  | **Sibling entities (Preview)** — shared event hubs + embedding similarity (`top_k`, `labels`, `polarity`); quality thresholds are not yet release-stable |
+| `/retrieve/recommend`        | `GET`/`POST` | **Train-free recommendations (Preview)** — synergies plus asymmetric walks, multi-interest, and optional attribute preferences; endpoint compatibility is retained while the quality gate is defined |
+
+**Get context for a question:**
+
+```sh
+curl -X POST http://localhost:8000/retrieve/context \
+  -H "Authorization: Bearer $BRAINPAT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Who organized AI events in London in March 2024?", "brain_id": "default"}'
+# → text_context + triples + historical_context + source_passages
+#    (optional: graph_session_ids, topics, paths; tune with max_facts / max_passages)
+```
+
+**Check if an entity exists:**
+
+```sh
+curl "http://localhost:8000/retrieve/entity/status?target=Emily" \
+  -H "Authorization: Bearer $BRAINPAT_TOKEN"
+# → { "exists": true, "node": {...}, "relationships": [...], "observations": [...] }
+```
+
+**Find synergies (same-type siblings, Preview):**
+
+```sh
+curl "http://localhost:8000/retrieve/entity/synergies?target=Neural%20Networks%20101&top_k=20" \
+  -H "Authorization: Bearer $BRAINPAT_TOKEN"
+# → similar entities ranked by association_score
+```
+
+**Rank recommendations (product / next-item style):**
+
+```sh
+curl "http://localhost:8000/retrieve/recommend?target=u01&top_k=20&labels=PRODUCT&exclude_seen=true" \
+  -H "Authorization: Bearer $BRAINPAT_TOKEN"
+# → ranked recommendations with channel provenance (synergy / asymmetric / multi_interest / …)
+```
+
+
+These endpoints cover the most common needs, but there are more (`/retrieve/hops`, `/retrieve/entities/neighbors`, `/retrieve/text-chunks`, …). Start with [Context retrieval](https://brainapi.lumen-labs.ai/docs/v2/retrieval/context) and the [docs hub](https://brainapi.lumen-labs.ai/docs/v2).
+
+---
+
+## 🧩 Plugins: Make BrainAPI Fit Your Use Case
+
+Out of the box BrainAPI is a general-purpose understanding engine. **Plugins** let you reshape it into something far more specific — without forking the core. Because plugins can add routes, swap agent prompts, and register MCP tools, the same engine can become:
+
+- **A cheap semantic search engine** — extract entities once, then serve fast graph-backed search instead of paying for vector queries every time.
+- **A recommendation system** — use `/retrieve/recommend` (and `/retrieve/entity/synergies` for same-type siblings) or plugins like `features-rec` / `recsys-gnn`.
+- **A domain-specific extractor** — override the Scout/Architect prompts so the swarm understands your ontology (CRM, legal, medical, …).
+- **An agent toolset** — register custom MCP tools so any LLM runtime can read and write your brain.
+
+A plugin can:
+
+- Add custom REST routes to the BrainAPI server
+- Override or extend the agents' prompts for domain-specific extraction
+- Register new MCP tools for agent runtimes
+- Ship its own background (Celery) tasks
+
+### Install & publish
+
+```sh
+poetry run brainapi plugins install @community/crm-entities
+poetry run brainapi plugins list --remote
+
+poetry run brainapi plugins register         # become a publisher
+poetry run brainapi plugins publish ./my-plugin.tar.gz
+```
+
+Browse and publish at the [Plugin Registry →](https://registry.brain-api.dev/app)
+
+---
+
+## 🚀 Where You Can Use It
+
+BrainAPI shines wherever messy, ever-changing text needs to become structured, queryable understanding:
+
+- **AI memory for agents** — persistent, structured memory across sessions and documents, with provenance.
+- **Recommendation systems** — grounded in real behavioural paths, not click co-occurrence.
+- **Semantic search** — retrieve by meaning and multi-hop reasoning across docs, tickets and chat.
+- **Expert & community mapping** — "Who in our org has worked on Kubernetes and ML pipelines together?"
+- **Business intelligence from qualitative data** — turn feedback and support conversations into queryable signals.
+- **Investigation & compliance** — connect people, events, documents and timestamps into a coherent, traceable graph.
+
+✅ **Reach for BrainAPI when** you need structured knowledge from messy sources, long-term explainable memory, or multi-hop queries with a traceable answer.
+
+⚠️ **Skip it when** your data already fits a fixed schema you control, or a single SQL query solves the problem.
+
+---
+
+## 🔌 Connecting Claude Desktop via MCP
+
+The MCP server runs as a separate process on port **8001** (`http://localhost:8001/mcp`).
+
+1. Start it: `make start-mcp` (or it's already running via `brainapi start`).
+2. In Claude Desktop → **Settings → Developer → Edit Config**, add:
+
+```json
+"brainapi-local": {
+  "command": "/path/to/node/bin/npx",
+  "args": ["-y", "@pyroprompts/mcp-stdio-to-streamable-http-adapter"],
+  "env": {
+    "URI": "http://localhost:8001/mcp",
+    "MCP_NAME": "brainapi-local",
+    "PATH": "/path/to/node/bin:/usr/local/bin:/usr/bin:/bin",
+    "BEARER_TOKEN": "your-pat-here"
+  }
+}
+```
+
+3. Make sure URL-based MCP servers are enabled in Claude Desktop settings.
+
+---
+
+## 📦 SDKs
+
+| Platform    | Package                                                               | Status                                                                                    |
+| ----------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| **Python**  | [`lumen_brain`](https://pypi.org/project/lumen_brain/)                | ![PyPI](https://img.shields.io/pypi/v/lumen_brain?label=v0.x&color=orange) ⚠️ Pre-release |
+| **Node.js** | [`lumen-brain`](https://www.npmjs.com/package/@lumenlabs/lumen-brain) | ![npm](https://img.shields.io/npm/v/lumen-brain?label=v0.x&color=orange) ⚠️ Pre-release   |
+
+```python
+from lumen_brain import BrainAPI
+
+client = BrainAPI(api_key="your-key")
+client.ingest.text("Emily organized the AI Ethics Meetup in London on 2024-03-08.")
+
+result = client.retrieveContext("Who organized AI events in London in March 2024?")
+print(result.text_context)   # the answer
+print(result.triples)        # the graph path used to derive it
+```
+
+> Both SDKs are pre-1.0 and under active development. For production, use the [REST API](https://brainapi.lumen-labs.ai/docs/v2) directly until v1.0 ships. You can mix modes freely — ingest over REST, retrieve via MCP inside an agent runtime, or use the SDKs for everything.
+
+---
+
+<p align="center">
+  <a href="https://www.youtube.com/watch?v=wWwTFU5-qeA">
+    <img src="https://img.youtube.com/vi/wWwTFU5-qeA/0.jpg" alt="BrainAPI Overview Video" width="100%" style="aspect-ratio: 16/9;object-fit: cover;border-radius:4px;box-shadow:0 2px 12px rgba(0,0,0,0.09);margin-bottom:16px;"/>
+    <br/>
+    <strong>▶ Watch: BrainAPI (non-technical) Overview Video</strong>
+  </a>
+</p>
+
+---
+
+## 📚 Resources
+
+| Resource               | Link                                                                                             |
+| ---------------------- | ------------------------------------------------------------------------------------------------ |
+| 🖥️ Local CLI (TUI)     | [`tui/README.md`](tui/README.md) — `npm install -g brainapi-tui`                                 |
+| 📖 Documentation       | [brainapi.lumen-labs.ai/docs/v2](https://brainapi.lumen-labs.ai/docs/v2)                         |
+| ⚡ Quick Start Guide   | [brainapi.lumen-labs.ai/docs/v2](https://brainapi.lumen-labs.ai/docs/v2)                         |
+| 🔌 Plugin Registry     | [registry.brain-api.dev/app](https://registry.brain-api.dev/app)                                 |
+| 🛠️ Context API         | [brainapi.lumen-labs.ai/docs/v2/retrieval/context](https://brainapi.lumen-labs.ai/docs/v2/retrieval/context) |
+| 🐍 Python SDK (PyPI)   | [pypi.org/project/lumen_brain](https://pypi.org/project/lumen_brain/)                            |
+| 📦 Node.js SDK (npm)   | [npmjs.com/package/@lumenlabs/lumen-brain](https://www.npmjs.com/package/@lumenlabs/lumen-brain) |
+| 💬 Community & Support | [Discord](https://discord.gg/VTngQTaeDf)                                                         |
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## 📄 License
+
+This project is licensed under the **[Business Source License 1.1](LICENSE)**.
+
+- **Free for non-production use** — copy, modify, redistribute, and run BrainAPI for development, evaluation, and other non-production purposes.
+- **Production use requires a commercial license** — including self-host, sidecar, and running BrainAPI on your own cloud as part of a live product or service.
+- **This version becomes Apache 2.0 on 13 August 2030.** After that date, this release is under the [Apache License, Version 2.0](licenses/Apache-2.0.txt) and production use of *this* version is free. Later releases keep their own BSL terms until their Change Date.
+
+Contact [hello@lumen-labs.ai](mailto:hello@lumen-labs.ai) for a commercial license.
+
+---
+
+<p align="center">
+  <sub>Built with ❤️ by <a href="https://github.com/lumen-labs">Lumen Labs</a></sub>
+</p>