brainpick 0.1.0__tar.gz

brainpick-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: brainpick
+Version: 0.1.0
+Summary: A turn-key brain stack for agents: compile an OKF markdown bundle into a queryable, servable, visualizable brain.
+Author: Benquemax
+License: MIT
+Project-URL: Homepage, https://github.com/benquemax/brainpick
+Project-URL: Repository, https://github.com/benquemax/brainpick
+Project-URL: Issues, https://github.com/benquemax/brainpick/issues
+Keywords: knowledge-graph,okf,mcp,rag,agents,brainpick,llm
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6
+Requires-Dist: tomli>=2; python_version < "3.11"
+Requires-Dist: mcp<2,>=1.9
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: watchfiles>=0.24
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Provides-Extra: vectors
+Requires-Dist: lancedb>=0.25; extra == "vectors"
+Provides-Extra: vectors-local
+Requires-Dist: fastembed>=0.7; extra == "vectors-local"
+Provides-Extra: all
+Requires-Dist: brainpick[vectors,vectors-local]; extra == "all"
+
+# brainpick (Python engine)
+
+**A turn-key brain stack for agents.** Compile a folder of
+[OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+markdown into a queryable, servable, visualizable brain — then serve it to
+agents over MCP + CLI and to humans through a live holographic-brain web UI.
+
+This is the Python engine (the reference implementation). A byte-identical
+[native Node engine](https://www.npmjs.com/package/brainpick) ships on npm with
+no Python required — same artifacts, same UI, same MCP tools.
+
+```bash
+uvx brainpick init --root ./my-okf-bundle   # detect, configure, compile
+uvx brainpick serve --open                  # the living graph, zero API keys
+```
+
+## The tiers
+
+| Tier | What | Needs |
+|------|------|-------|
+| T0 | grep/glob over the files | nothing |
+| T1 | generated `index.md`, link graph, backlinks, tags | nothing (deterministic) |
+| T2 | vector search over chunks | an embedding model |
+| T3 | entity/relation graph (LightRAG behind an adapter) | a small LLM |
+
+Extras: `brainpick[vectors]` (LanceDB), `brainpick[vectors-local]`
+(fastembed, offline), `brainpick[graph]` (LightRAG extraction), `brainpick[all]`.
+
+The markdown is the only source of truth; everything under `.brainpick/` is a
+disposable build artifact. Small local models (qwen3.6-class) are first-class
+citizens. See the [full README, principles, and docs](https://github.com/benquemax/brainpick).
+
+MIT.

brainpick-0.1.0/README.md

@@ -0,0 +1,33 @@
+# brainpick (Python engine)
+
+**A turn-key brain stack for agents.** Compile a folder of
+[OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+markdown into a queryable, servable, visualizable brain — then serve it to
+agents over MCP + CLI and to humans through a live holographic-brain web UI.
+
+This is the Python engine (the reference implementation). A byte-identical
+[native Node engine](https://www.npmjs.com/package/brainpick) ships on npm with
+no Python required — same artifacts, same UI, same MCP tools.
+
+```bash
+uvx brainpick init --root ./my-okf-bundle   # detect, configure, compile
+uvx brainpick serve --open                  # the living graph, zero API keys
+```
+
+## The tiers
+
+| Tier | What | Needs |
+|------|------|-------|
+| T0 | grep/glob over the files | nothing |
+| T1 | generated `index.md`, link graph, backlinks, tags | nothing (deterministic) |
+| T2 | vector search over chunks | an embedding model |
+| T3 | entity/relation graph (LightRAG behind an adapter) | a small LLM |
+
+Extras: `brainpick[vectors]` (LanceDB), `brainpick[vectors-local]`
+(fastembed, offline), `brainpick[graph]` (LightRAG extraction), `brainpick[all]`.
+
+The markdown is the only source of truth; everything under `.brainpick/` is a
+disposable build artifact. Small local models (qwen3.6-class) are first-class
+citizens. See the [full README, principles, and docs](https://github.com/benquemax/brainpick).
+
+MIT.

brainpick-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "brainpick"
+version = "0.1.0"
+description = "A turn-key brain stack for agents: compile an OKF markdown bundle into a queryable, servable, visualizable brain."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Benquemax" }]
+keywords = ["knowledge-graph", "okf", "mcp", "rag", "agents", "brainpick", "llm"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "PyYAML>=6",
+    "tomli>=2; python_version<'3.11'",
+    "mcp>=1.9,<2",
+    "starlette>=0.40",
+    "uvicorn>=0.30",
+    "watchfiles>=0.24",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/benquemax/brainpick"
+Repository = "https://github.com/benquemax/brainpick"
+Issues = "https://github.com/benquemax/brainpick/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-timeout>=2.3",
+    "ruff>=0.6",
+]
+vectors = [
+    "lancedb>=0.25",
+]
+vectors-local = [
+    "fastembed>=0.7",
+]
+all = [
+    "brainpick[vectors,vectors-local]",
+]
+
+[project.scripts]
+brainpick = "brainpick.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+brainpick = ["_static/**/*", "_skill/SKILL.md"]
+
+[tool.ruff]
+line-length = 110
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# The fast suite (pre-commit gate, default run) excludes live-LLM integration
+# tests. Run them explicitly: `pytest -m integration` (needs stabilitee + [graph]).
+addopts = "-m 'not integration'"
+markers = ["integration: exercises a live model endpoint (slow, opt-in)"]

brainpick-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

brainpick-0.1.0/src/brainpick/__init__.py

@@ -0,0 +1,4 @@
+"""brainpick — a turn-key brain stack for agents."""
+
+__version__ = "0.1.0"
+SPEC_VERSION = "0.1"

brainpick-0.1.0/src/brainpick/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m brainpick` — the CLI without the console script."""
+import sys
+
+from brainpick.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

brainpick-0.1.0/src/brainpick/_skill/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: brainpick
+description: Consult the compiled knowledge brain (a graph of this repo's docs) BEFORE grepping or answering questions about the project. Use whenever a brainpick brain is available — the brain_* MCP tools or the `brainpick` CLI.
+---
+
+# brainpick — pick the brain before you grep
+
+This repo (or a folder in it) is compiled into a **brain**: a searchable graph of
+its docs. Reading the brain is faster and truer than grepping raw files — it knows
+titles, descriptions, links, and neighbors.
+
+## The rule
+
+**Before you grep, glob, or answer a "how does X work?" question, ask the brain.**
+Grep finds strings; the brain finds meaning and the docs around it. Grep only after
+the brain comes up short.
+
+Start every session with one call to get oriented, then search.
+
+## The five MCP tools
+
+Call these if a `brainpick` MCP server is connected (tools are named `brain_*`):
+
+- `brain_overview()` — one screen: counts, tiers, every doc grouped by folder. Call first.
+- `brain_search({query})` — find docs by meaning/keyword. Returns paths + descriptions, never full bodies. `mode` is `auto` (default), `keyword`, `semantic`, or `graph`.
+- `brain_read({doc})` — open one doc. `doc` is forgiving: a path (`kuu.md`), a bare stem (`kuu`), or an approximate title. Pass `sections:["Heading"]` to read just parts.
+- `brain_neighbors({doc})` — walk the links around a doc (`depth` 1–3). Find what connects to what.
+- `brain_write({doc, content})` — add a doc, guarded by the repo's contract. See "Writing" below.
+
+Every result carries a `hint` naming a sensible next call. Follow it.
+
+## The CLI equivalents
+
+No MCP server? The same four reads are CLI verbs. Pick the invocation that runs here:
+
+- Published (Python): `uvx brainpick search "vuorovesi"` · `read kuu` · `neighbors kuu` · `overview`
+- Dev checkout (Python): `uv run brainpick search "vuorovesi" --root <bundle>`
+- Node engine: `node /path/to/brainpick/dist/cli.js search "vuorovesi"` (or `npx brainpick search …` once published)
+
+Add `--json` for machine-readable output, `--root <dir>` to point at the bundle,
+`--mode`/`--limit` on search, `--depth` on neighbors. If the CLI says the brain
+is not compiled, run `brainpick compile --root <bundle>` first.
+
+Wire the MCP server into your host with `brainpick mcp` — e.g.
+`claude mcp add brainpick -- uvx brainpick mcp --root <bundle>`.
+
+## Writing knowledge back (brain_write)
+
+Only write when asked to record knowledge. Follow the wiki's conventions or the
+write is rejected by the contract:
+
+- **One concept per page**, filename **kebab-case** `.md` (`kuun-vaiheet.md`).
+- **Frontmatter**: `type` (Concept/Reference/Decision/Playbook), `title`,
+  `description`, `timestamp` — the brain bumps `timestamp` for you.
+- **Link generously**; the **link text is the target doc's title** (`[Kuu](kuu.md)`).
+  A doc with no links is an orphan.
+- **Optimistic concurrency**: pass `base_sha` = the sha256 of the content you last
+  read. On a mismatch nothing is written and you get the current content back —
+  re-read, reconcile, retry with the new `base_sha`.
+
+## Auth
+
+If the brain answers `401`, it wants a bearer token. Send
+`Authorization: Bearer <token>` (mint one with `brainpick token create`). Local
+stdio MCP is never gated.