secondbrain-py 0.2.1__tar.gz

secondbrain_py-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Sarkis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

secondbrain_py-0.2.1/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: secondbrain-py
+Version: 0.2.1
+Summary: Local personal knowledge base with hybrid search, queryable by Claude
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mshtawythug/second-brain
+Project-URL: Repository, https://github.com/mshtawythug/second-brain
+Project-URL: Issues, https://github.com/mshtawythug/second-brain/issues
+Keywords: second-brain,knowledge-base,rag,pgvector,hybrid-search,mcp,ollama,local-first
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psycopg[binary]>=3.2
+Requires-Dist: pgvector>=0.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: pypdf>=5.0
+Requires-Dist: pdfplumber>=0.11
+Requires-Dist: python-docx>=1.1
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: typer>=0.13
+Requires-Dist: rich>=13.9
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: tiktoken>=0.8
+Requires-Dist: mcp<2.0,>=1.0
+Requires-Dist: voyageai>=0.3
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: watchdog>=4.0
+Requires-Dist: networkx>=3.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: coverage<7.13; extra == "dev"
+Requires-Dist: pytest-mock>=3.14; extra == "dev"
+Requires-Dist: ruff>=0.7; extra == "dev"
+Requires-Dist: mypy>=1.13; extra == "dev"
+Requires-Dist: reportlab>=4.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Dynamic: license-file
+
+<!-- mcp-name: io.github.mshtawythug/second-brain -->
+
+# Second Brain
+
+Local, queryable knowledge base and note vault with hybrid search and an entity-graph layer — searchable by any AI coding agent or assistant from any conversation.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/mshtawythug/second-brain/actions/workflows/eval.yml/badge.svg)](https://github.com/mshtawythug/second-brain/actions/workflows/eval.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+
+Stores career docs, interview prep, Krisp transcripts, Slack threads, Gmail, and authored Markdown notes in Postgres + pgvector. Any agent reaches all of it through the `brain` CLI or the bundled `brain-mcp` MCP server — no re-pasting context into every chat.
+
+The everyday loop — capture a note, search it back, read the top hit, check the corpus:
+
+![brain daily workflow](docs/assets/usage.gif)
+
+## Token savings
+
+Querying `brain` returns a ranked snippet instead of dumping whole threads and files into an agent's context, so a lookup costs a fraction of the tokens a direct MCP or file read would:
+
+| Source | Direct read (MCP / `Read` tool) | Via `brain` (search + optional `show`) | Savings |
+|---|---|---|---|
+| **Gmail thread** | 15–50k (metadata + full threads with quoted replies / headers) | ~2–4k (snippets + one targeted `brain show`) | **~5–15×** |
+| **Krisp transcript** | 25–75k (search + full transcripts across candidates) | ~6–16k (search + one relevant transcript) | **~4–10×** |
+| **Long PDF / DOCX (30+ pages)** | 15–25k (read the whole file) | ~1–9k (one snippet + targeted `show`) | **~5–15×** |
+
+Brain stores pre-extracted, quote-stripped bodies and hybrid-ranks *before* fetching, so only the passage that matched enters context. See the [full per-source breakdown](docs/configuration.md#token-economics).
+
+## See it in 60 seconds
+
+Install the CLI, then run the offline demo — a throwaway Postgres seeded with a synthetic *Larkspur* compliance corpus. No Ollama, no personal data, no model downloads:
+
+```bash
+pipx install secondbrain-py
+# or, with uv:
+uv tool install secondbrain-py
+# or, pin the git tag (no PyPI needed):
+pipx install git+https://github.com/mshtawythug/second-brain.git@v0.2.1
+
+brain demo        # spins up a sandbox Postgres, seeds 22 docs, runs a hero query
+```
+
+![brain demo](docs/assets/demo.gif)
+
+_(IDs and scores are per-run; the seeded corpus and its ranking are deterministic — the top hit is always the "Compliance Horror Stories" note.)_
+
+Try these next:
+
+```bash
+brain demo query "SOC 2 evidence request"      # a targeted follow-up query
+brain demo query "vendor risk" --source gmail  # narrow by source
+brain show <id>                                # read the top hit in full (in your own brain)
+brain demo teardown                            # remove the sandbox when done
+```
+
+`brain demo` needs only Docker; `brain demo teardown` destroys the sandbox.
+
+Already ran the demo? You have `brain` installed — jump straight to `brain setup --profile …` below.
+
+## Quick start
+
+Full install — the `brain` CLI plus the runtime (Postgres, and optionally Ollama / graph / wiki):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mshtawythug/second-brain/v0.2.1/install.sh | bash
+```
+
+The installer pipx-installs `brain` from the `v0.2.1` tag, then runs `brain setup` to provision `$BRAIN_HOME`, start the Postgres container, and (optionally) install the wiki + Claude Code skill. Choose how much to stand up with `--profile`:
+
+| Profile | Search | Extra dependencies beyond the core |
+|---|---|---|
+| `minimal` | FTS-only (`BRAIN_EMBEDDER=none`) | None — core only (no Ollama, no models). |
+| `standard` *(default)* | Hybrid (FTS + vector) | + Ollama + one ~1 GB embedding model (`snowflake-arctic-embed2`). |
+| `full` | Hybrid + GraphRAG + wiki | + Apache AGE image, concept-extraction LLM, Quartz/Caddy wiki, and (opt-in) launchd daemons via `--daemons`. |
+
+```bash
+brain setup --profile minimal    # Docker-only, FTS search — fastest to stand up
+brain setup --profile standard   # default: local hybrid search
+brain setup --profile full --daemons
+```
+
+**Prerequisites (core):** Git, Python 3.11+, and a running Docker (Desktop or Engine) — the Postgres + pgvector database runs in a container on port 55432.
+
+**Optional extras** (only if you want more than FTS-only search):
+
+- **[Ollama](https://ollama.com/)** — local, free embeddings + LLM enrichment. To upgrade a `minimal` (FTS-only) brain to hybrid search: install Ollama, then `ollama pull snowflake-arctic-embed2`, set `BRAIN_EMBEDDER=arctic` in `.env`, and run `brain init && brain reembed`.
+- **Node.js 18+ and [Caddy](https://caddyserver.com/)** — only for the rendered [wiki](docs/vault-and-wiki.md).
+- **`gws` CLI** — only for Gmail ingest and Google-backed directory linking.
+
+Prefer to drive every step yourself, or hacking on the code? See [Installing from source](docs/configuration.md#installing-from-source-manual).
+
+## Core usage
+
+```bash
+brain ingest ~/Documents/resume.pdf --tag career          # ingest a file (TXT / MD / PDF / DOCX)
+brain ingest-dir ~/Documents/career                       # recursive, idempotent by content hash
+brain search "what did I tell my manager about the migration"   # hybrid FTS + vector search
+brain show <id-prefix>                                    # full document body (6+ hex prefix)
+brain list --source gmail --limit 20                      # browse by source
+brain tag <id-prefix> +interview +career -old-tag         # add (+name) / remove (-name) tags
+```
+
+Add `--json` to `search` / `show` / `list` for machine-readable output, and `--fts-only` to `search` to skip the embedding call. The full command surface — Gmail ingest, enrichment, tacit-knowledge elicitation, GraphRAG, the proactivity/synthesis commands, and vault authoring — lives in the [CLI reference](docs/cli-reference.md).
+
+## Claude integrations
+
+`brain` and the bundled `brain-mcp` server are harness-agnostic — any agent that runs a shell command or speaks MCP can query the corpus.
+
+Register the MCP server once, then just ask — the agent searches the brain and answers from it, no context pasted in:
+
+![Claude answering a question from the brain over the brain-mcp MCP server](docs/assets/mcp.gif)
+
+**Claude Code** — register the MCP server (or symlink the [skills](docs/configuration.md#claude-code-consult-brain-skill)):
+
+```bash
+claude mcp add brain -- brain-mcp
+```
+
+**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json` (replace `/Users/you` with your home directory):
+
+```json
+{
+  "mcpServers": {
+    "brain": {
+      "command": "/Users/you/workspace/second-brain/.venv/bin/brain-mcp",
+      "env": {
+        "DATABASE_URL": "postgresql://brain:brain@localhost:55432/second_brain",
+        "BRAIN_EMBEDDER": "arctic"
+      }
+    }
+  }
+}
+```
+
+`uvx secondbrain-py` also launches the MCP server. Full walkthrough (symlink, smoke-test, troubleshooting): [docs/guides/claude-desktop-setup.md](docs/guides/claude-desktop-setup.md).
+
+## How it works
+
+**Hybrid search.** Every document is chunked, embedded, and indexed for Postgres full-text search. A query runs both legs — lexical `tsvector` ranking and vector cosine similarity — and fuses them with [Reciprocal Rank Fusion](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf) (k=60), then applies a recency boost and metadata filters. Lexical alone misses paraphrases ("what did I say about X"); vector alone misses exact names (a coworker, a former employer); RRF gets both in one ranked list without tuning weights. Set `BRAIN_EMBEDDER=none` for an FTS-only brain with no embedding dependency at all.
+
+**GraphRAG.** Alongside search, brain builds an entity graph of the people and concepts that co-occur across the corpus ([Apache AGE](https://age.apache.org/) inside the same Postgres) and retrieves over that structure — answering "what themes come up in my conversations with X" or "which clusters of people and topics dominate my notes" by traversing relationships instead of matching text. It runs alongside plain search, not instead of it. See [docs/graphrag.md](docs/graphrag.md).
+
+## Documentation
+
+- [docs/](docs/README.md) — full documentation index
+- [CLI reference](docs/cli-reference.md) — every command beyond the core five
+- [GraphRAG](docs/graphrag.md) — entity-graph retrieval (themes, patterns, connections)
+- [Vault and Wiki](docs/vault-and-wiki.md) — the two-tier note vault + optional rendered wiki
+- [Configuration](docs/configuration.md) — tech stack, tuning knobs, integrations, embedder backends, uninstall
+- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, codebase layout, running the tests
+- [CHANGELOG.md](CHANGELOG.md) — release history
+- [LICENSE](LICENSE) — MIT

secondbrain_py-0.2.1/README.md

@@ -0,0 +1,152 @@
+<!-- mcp-name: io.github.mshtawythug/second-brain -->
+
+# Second Brain
+
+Local, queryable knowledge base and note vault with hybrid search and an entity-graph layer — searchable by any AI coding agent or assistant from any conversation.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/mshtawythug/second-brain/actions/workflows/eval.yml/badge.svg)](https://github.com/mshtawythug/second-brain/actions/workflows/eval.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+
+Stores career docs, interview prep, Krisp transcripts, Slack threads, Gmail, and authored Markdown notes in Postgres + pgvector. Any agent reaches all of it through the `brain` CLI or the bundled `brain-mcp` MCP server — no re-pasting context into every chat.
+
+The everyday loop — capture a note, search it back, read the top hit, check the corpus:
+
+![brain daily workflow](docs/assets/usage.gif)
+
+## Token savings
+
+Querying `brain` returns a ranked snippet instead of dumping whole threads and files into an agent's context, so a lookup costs a fraction of the tokens a direct MCP or file read would:
+
+| Source | Direct read (MCP / `Read` tool) | Via `brain` (search + optional `show`) | Savings |
+|---|---|---|---|
+| **Gmail thread** | 15–50k (metadata + full threads with quoted replies / headers) | ~2–4k (snippets + one targeted `brain show`) | **~5–15×** |
+| **Krisp transcript** | 25–75k (search + full transcripts across candidates) | ~6–16k (search + one relevant transcript) | **~4–10×** |
+| **Long PDF / DOCX (30+ pages)** | 15–25k (read the whole file) | ~1–9k (one snippet + targeted `show`) | **~5–15×** |
+
+Brain stores pre-extracted, quote-stripped bodies and hybrid-ranks *before* fetching, so only the passage that matched enters context. See the [full per-source breakdown](docs/configuration.md#token-economics).
+
+## See it in 60 seconds
+
+Install the CLI, then run the offline demo — a throwaway Postgres seeded with a synthetic *Larkspur* compliance corpus. No Ollama, no personal data, no model downloads:
+
+```bash
+pipx install secondbrain-py
+# or, with uv:
+uv tool install secondbrain-py
+# or, pin the git tag (no PyPI needed):
+pipx install git+https://github.com/mshtawythug/second-brain.git@v0.2.1
+
+brain demo        # spins up a sandbox Postgres, seeds 22 docs, runs a hero query
+```
+
+![brain demo](docs/assets/demo.gif)
+
+_(IDs and scores are per-run; the seeded corpus and its ranking are deterministic — the top hit is always the "Compliance Horror Stories" note.)_
+
+Try these next:
+
+```bash
+brain demo query "SOC 2 evidence request"      # a targeted follow-up query
+brain demo query "vendor risk" --source gmail  # narrow by source
+brain show <id>                                # read the top hit in full (in your own brain)
+brain demo teardown                            # remove the sandbox when done
+```
+
+`brain demo` needs only Docker; `brain demo teardown` destroys the sandbox.
+
+Already ran the demo? You have `brain` installed — jump straight to `brain setup --profile …` below.
+
+## Quick start
+
+Full install — the `brain` CLI plus the runtime (Postgres, and optionally Ollama / graph / wiki):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mshtawythug/second-brain/v0.2.1/install.sh | bash
+```
+
+The installer pipx-installs `brain` from the `v0.2.1` tag, then runs `brain setup` to provision `$BRAIN_HOME`, start the Postgres container, and (optionally) install the wiki + Claude Code skill. Choose how much to stand up with `--profile`:
+
+| Profile | Search | Extra dependencies beyond the core |
+|---|---|---|
+| `minimal` | FTS-only (`BRAIN_EMBEDDER=none`) | None — core only (no Ollama, no models). |
+| `standard` *(default)* | Hybrid (FTS + vector) | + Ollama + one ~1 GB embedding model (`snowflake-arctic-embed2`). |
+| `full` | Hybrid + GraphRAG + wiki | + Apache AGE image, concept-extraction LLM, Quartz/Caddy wiki, and (opt-in) launchd daemons via `--daemons`. |
+
+```bash
+brain setup --profile minimal    # Docker-only, FTS search — fastest to stand up
+brain setup --profile standard   # default: local hybrid search
+brain setup --profile full --daemons
+```
+
+**Prerequisites (core):** Git, Python 3.11+, and a running Docker (Desktop or Engine) — the Postgres + pgvector database runs in a container on port 55432.
+
+**Optional extras** (only if you want more than FTS-only search):
+
+- **[Ollama](https://ollama.com/)** — local, free embeddings + LLM enrichment. To upgrade a `minimal` (FTS-only) brain to hybrid search: install Ollama, then `ollama pull snowflake-arctic-embed2`, set `BRAIN_EMBEDDER=arctic` in `.env`, and run `brain init && brain reembed`.
+- **Node.js 18+ and [Caddy](https://caddyserver.com/)** — only for the rendered [wiki](docs/vault-and-wiki.md).
+- **`gws` CLI** — only for Gmail ingest and Google-backed directory linking.
+
+Prefer to drive every step yourself, or hacking on the code? See [Installing from source](docs/configuration.md#installing-from-source-manual).
+
+## Core usage
+
+```bash
+brain ingest ~/Documents/resume.pdf --tag career          # ingest a file (TXT / MD / PDF / DOCX)
+brain ingest-dir ~/Documents/career                       # recursive, idempotent by content hash
+brain search "what did I tell my manager about the migration"   # hybrid FTS + vector search
+brain show <id-prefix>                                    # full document body (6+ hex prefix)
+brain list --source gmail --limit 20                      # browse by source
+brain tag <id-prefix> +interview +career -old-tag         # add (+name) / remove (-name) tags
+```
+
+Add `--json` to `search` / `show` / `list` for machine-readable output, and `--fts-only` to `search` to skip the embedding call. The full command surface — Gmail ingest, enrichment, tacit-knowledge elicitation, GraphRAG, the proactivity/synthesis commands, and vault authoring — lives in the [CLI reference](docs/cli-reference.md).
+
+## Claude integrations
+
+`brain` and the bundled `brain-mcp` server are harness-agnostic — any agent that runs a shell command or speaks MCP can query the corpus.
+
+Register the MCP server once, then just ask — the agent searches the brain and answers from it, no context pasted in:
+
+![Claude answering a question from the brain over the brain-mcp MCP server](docs/assets/mcp.gif)
+
+**Claude Code** — register the MCP server (or symlink the [skills](docs/configuration.md#claude-code-consult-brain-skill)):
+
+```bash
+claude mcp add brain -- brain-mcp
+```
+
+**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json` (replace `/Users/you` with your home directory):
+
+```json
+{
+  "mcpServers": {
+    "brain": {
+      "command": "/Users/you/workspace/second-brain/.venv/bin/brain-mcp",
+      "env": {
+        "DATABASE_URL": "postgresql://brain:brain@localhost:55432/second_brain",
+        "BRAIN_EMBEDDER": "arctic"
+      }
+    }
+  }
+}
+```
+
+`uvx secondbrain-py` also launches the MCP server. Full walkthrough (symlink, smoke-test, troubleshooting): [docs/guides/claude-desktop-setup.md](docs/guides/claude-desktop-setup.md).
+
+## How it works
+
+**Hybrid search.** Every document is chunked, embedded, and indexed for Postgres full-text search. A query runs both legs — lexical `tsvector` ranking and vector cosine similarity — and fuses them with [Reciprocal Rank Fusion](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf) (k=60), then applies a recency boost and metadata filters. Lexical alone misses paraphrases ("what did I say about X"); vector alone misses exact names (a coworker, a former employer); RRF gets both in one ranked list without tuning weights. Set `BRAIN_EMBEDDER=none` for an FTS-only brain with no embedding dependency at all.
+
+**GraphRAG.** Alongside search, brain builds an entity graph of the people and concepts that co-occur across the corpus ([Apache AGE](https://age.apache.org/) inside the same Postgres) and retrieves over that structure — answering "what themes come up in my conversations with X" or "which clusters of people and topics dominate my notes" by traversing relationships instead of matching text. It runs alongside plain search, not instead of it. See [docs/graphrag.md](docs/graphrag.md).
+
+## Documentation
+
+- [docs/](docs/README.md) — full documentation index
+- [CLI reference](docs/cli-reference.md) — every command beyond the core five
+- [GraphRAG](docs/graphrag.md) — entity-graph retrieval (themes, patterns, connections)
+- [Vault and Wiki](docs/vault-and-wiki.md) — the two-tier note vault + optional rendered wiki
+- [Configuration](docs/configuration.md) — tech stack, tuning knobs, integrations, embedder backends, uninstall
+- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, codebase layout, running the tests
+- [CHANGELOG.md](CHANGELOG.md) — release history
+- [LICENSE](LICENSE) — MIT

secondbrain_py-0.2.1/pyproject.toml

@@ -0,0 +1,219 @@
+[project]
+name = "secondbrain-py"
+version = "0.2.1"
+description = "Local personal knowledge base with hybrid search, queryable by Claude"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+  "second-brain",
+  "knowledge-base",
+  "rag",
+  "pgvector",
+  "hybrid-search",
+  "mcp",
+  "ollama",
+  "local-first",
+]
+# NOTE: no `License ::` trove classifier here — the license is declared via the
+# PEP 639 SPDX expression (`license = "MIT"` + `license-files`) above. setuptools
+# >= 77 rejects a `License ::` classifier alongside an SPDX license expression
+# ("License classifiers have been superseded by license expressions"), so the
+# classifier would break the build. PyPI derives the license from the expression.
+classifiers = [
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Environment :: Console",
+  "Topic :: Text Processing :: Indexing",
+]
+dependencies = [
+  "psycopg[binary]>=3.2",
+  "pgvector>=0.3",
+  "httpx>=0.27",
+  "pypdf>=5.0",
+  "pdfplumber>=0.11",
+  "python-docx>=1.1",
+  "markdown-it-py>=3.0",
+  "typer>=0.13",
+  "rich>=13.9",
+  "python-dotenv>=1.0",
+  "tiktoken>=0.8",
+  "mcp>=1.0,<2.0",
+  "voyageai>=0.3",
+  "pyyaml>=6.0",
+  "watchdog>=4.0",
+  "networkx>=3.2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.3", "pytest-cov>=5.0", "coverage<7.13", "pytest-mock>=3.14", "ruff>=0.7", "mypy>=1.13", "reportlab>=4.0", "types-PyYAML>=6.0"]
+
+[project.scripts]
+brain = "brain.cli:app"
+brain-mcp = "brain.mcp_server:main"
+# Alias so `uvx secondbrain-py` launches the MCP server (uvx matches the console
+# script to the normalized distribution name; matches server.json's uvx
+# runtimeHint for the MCP registry; the human CLI remains `brain`).
+secondbrain-py = "brain.mcp_server:main"
+brain-up = "brain.bin.up:main"
+brain-down = "brain.bin.down:main"
+brain-status = "brain.bin.status:main"
+brain-rebuild = "brain.bin.rebuild:main"
+brain-install-launchd = "brain.bin.launchd:install_main"
+brain-uninstall-launchd = "brain.bin.launchd:uninstall_main"
+brain-monitor = "brain.bin.monitor:cli_main"
+
+[project.urls]
+Homepage = "https://github.com/mshtawythug/second-brain"
+Repository = "https://github.com/mshtawythug/second-brain"
+Issues = "https://github.com/mshtawythug/second-brain/issues"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# Include only the specific asset extensions used by the Quartz overlay tree.
+# Explicit patterns rather than "**/*" so .pyc bytecode and __pycache__ dirs
+# are never shipped into the wheel.
+# Root-level files: quartz.config.ts, quartz.layout.ts  (*.ts covers them)
+# Nested files under quartz/: TS/TSX components, JS/MJS CLI scripts, SCSS
+# stylesheets, and PNG/ICO branding assets.
+"brain.quartz_overrides" = [
+    "*.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.scss",
+    "**/*.png",
+    "**/*.ico",
+]
+# Templates shipped with the brain package for use by the installer.
+# Explicit extension patterns (not "**/*") to avoid shipping bytecode.
+# brain.templates root: docker-compose.yml.j2, Caddyfile.j2, env.example
+# brain.templates.docker.age: pinned Dockerfile (PG16 + pgvector + AGE), a plain
+#   data subdir (no __init__.py) materialized into $BRAIN_HOME by `brain setup`
+# brain.templates.bin: shell launcher/helper scripts
+# brain.templates.launchd: launchd plist Jinja2 templates
+# brain.templates.skill: SKILL.md prose for Claude Code skill setup
+"brain.templates" = ["*.j2", "env.example", "docker/age/Dockerfile"]
+"brain.templates.bin" = ["*.sh"]
+"brain.templates.launchd" = ["*.j2"]
+"brain.templates.skill" = ["*.md"]
+# brain.demo: the synthetic `brain demo` corpus manifest (a plain data subdir
+# under corpus/, no __init__.py) shipped so the zero-Ollama taste test works on
+# pipx/wheel installs. Explicit "corpus/*.json" (not "**/*") avoids bytecode.
+"brain.demo" = ["corpus/*.json"]
+# brain/migrations: the numbered SQL schema migrations `brain init` applies in
+# name order (discovered by db.migrations_dir()). They live INSIDE the package —
+# migrations/ under src/brain/, NOT the repo root — so wheel / pip installs
+# bundle them; without this `brain init` globs an empty dir and never creates the
+# schema. Explicit "migrations/*.sql" (not "**/*") ships only the SQL.
+"brain" = ["migrations/*.sql"]
+
+[tool.setuptools.exclude-package-data]
+# Strip bytecode caches that Python creates on-disk when the package is imported
+# during a dev install — they are local artefacts and must not appear in wheels.
+"brain.quartz_overrides" = ["__pycache__/*", "*.pyc"]
+"brain.templates" = ["__pycache__/*", "*.pyc"]
+"brain.templates.bin" = ["__pycache__/*", "*.pyc"]
+"brain.templates.launchd" = ["__pycache__/*", "*.pyc"]
+"brain.templates.skill" = ["__pycache__/*", "*.pyc"]
+"brain.demo" = ["__pycache__/*", "*.pyc"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers --cov=brain --cov-report=term-missing --cov-fail-under=85 -m 'not eval and not benchmark and not e2e and not phase3'"
+markers = [
+  # P3.5 — frontend integration harness. Tests under this marker shell
+  # out to `npx quartz build` and serve the artifact over HTTP (or rsync the
+  # live vault for the FastPath T0 perf benchmarks), so they require a Node
+  # toolchain + the live brain Quartz workspace at `~/brain-vault/.quartz/`.
+  # EXCLUDED from the default suite (see the ``addopts`` -m filter, alongside
+  # ``eval`` / ``benchmark``): they are non-hermetic (need a live vault, and
+  # the FastPath benchmarks rsync it — racing the live build daemon) and far
+  # too slow for every local run. Opt IN with `-m e2e`; CI runs them in a
+  # dedicated workflow.
+  "e2e: end-to-end Quartz build + serve test (requires npx + live workspace)",
+  # Phase D — search-ranking-fix. Tests under this marker connect to the
+  # live local Postgres (`second_brain` database) and to a real Ollama
+  # instance to embed a known-bad query and measure cosine similarity to
+  # a known-bad doc. Used to tune ``DEFAULT_VECTOR_SIM_FLOOR`` and to
+  # canary-check the post-fix corpus. Skipped on hosts without those
+  # services; opt out via `-m "not live_db"`.
+  "live_db: requires live local Postgres + Ollama (Phase D verification)",
+  # Wave Q1-B — Eval harness. Tests under this marker run the 20-query
+  # golden corpus against the live local Postgres + Ollama, scoring
+  # nDCG@5 / MRR / Recall@20.  Excluded from the default suite; opt-IN
+  # via `-m eval`.  Skips cleanly when Postgres or Ollama is unreachable.
+  "eval: live golden-corpus run; gated, requires explicit -m eval invocation",
+  # Wave G1-d / G2 — GraphRAG benchmark perf gate. Tests under this marker
+  # load the full-scale synthetic graph (50k entities / 500k CO_OCCURS / 1M
+  # mentions / 10 tenants — tests/graphrag/benchmark_fixture.py) and measure
+  # P95 traversal/themes latency. EXCLUDED from the default suite (see
+  # ``addopts`` -m filter) because the load is far too slow for every run;
+  # G2's perf gate opts IN via ``pytest -m benchmark``. The default suite
+  # exercises the SAME generator via the tiny ≈50-entity smoke instead.
+  "benchmark: GraphRAG full-scale perf gate; requires explicit -m benchmark invocation",
+  # brain-rebuild advisory-lock + real-DB tests. These need the test Postgres
+  # container (port 5434) to be up but do NOT require Ollama. Included in the
+  # default suite (not excluded by the addopts -m filter) because the test DB
+  # is required for most other tests anyway; marked for easy targeted runs via
+  # ``pytest -m integration``.
+  "integration: requires the test Postgres container (port 5434, db second_brain_test)",
+  # Plan 05 — `brain timeline` migration-021 roundtrip. The only test that
+  # requires the optional generated ``documents.doc_date`` column (Phase 3).
+  # EXCLUDED from the default suite (see the ``addopts`` -m filter, alongside
+  # ``eval`` / ``benchmark``) so v1/v2 CI passes without migration 021 applied;
+  # opt IN with `-m phase3`.
+  "phase3: requires the optional migration-021 doc_date column (brain timeline Phase 3)",
+  # Wave 6.1 — test-DB reset strategy opt-out. The per-test ``test_db`` fixture
+  # normally does a cheap ``TRUNCATE`` reset on top of a schema migrated ONCE per
+  # session (conftest ``_truncate_reset``). Tests that mutate the *schema* itself
+  # (DROP/ALTER/CREATE on tables, indexes, extensions; ``ensure_embedding_column``
+  # resizes; ``finalize_embedding_index`` NOT NULL/index; re-running migrations;
+  # own-connection ``DROP SCHEMA``) must carry this marker: the fixture then falls
+  # back to the full ``DROP SCHEMA`` + migrate reset for that test AND an autouse
+  # teardown re-establishes the migrated-once baseline afterwards, so the next
+  # (TRUNCATE-only) test is not poisoned by the leaked schema mutation. INCLUDED
+  # in the default suite — it is a routing hint, not an exclusion filter.
+  "fresh_schema: needs a full drop+migrate reset (mutates schema, not just data)",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.flake8-bugbear]
+# Typer uses typer.Argument/Option/Typer as defaults — the standard idiom.
+extend-immutable-calls = ["typer.Argument", "typer.Option", "typer.Typer"]
+
+[tool.mypy]
+python_version = "3.11"
+mypy_path = "src"
+explicit_package_bases = true
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["pgvector.*", "pdfplumber.*", "pypdf.*", "markdown_it.*", "docx.*", "tiktoken.*", "reportlab.*", "voyageai.*", "watchdog.*", "networkx.*"]
+ignore_missing_imports = true
+
+# numpy (transitive via networkx) ships PEP 695 `type X = ...` aliases in its
+# bundled stubs, which are 3.12+ syntax. With our `python_version = "3.11"`
+# target, mypy rejects that syntax in `numpy/__init__.pyi` and halts before it
+# ever reaches brain code ("errors prevented further checking"). We never import
+# numpy directly, so skip following into it entirely — keeps the 3.11 target for
+# our own code while unblocking the gate. `follow_imports_for_stubs` makes the
+# skip apply to the `.pyi` too (not just runtime modules).
+[[tool.mypy.overrides]]
+module = ["numpy", "numpy.*"]
+follow_imports = "skip"
+follow_imports_for_stubs = true

secondbrain_py-0.2.1/setup.cfg

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

secondbrain_py-0.2.1/src/brain/__main__.py

@@ -0,0 +1,18 @@
+"""Enable ``python -m brain [command]`` invocation of the brain CLI.
+
+This module is the standard entry-point for Python's ``-m`` flag:
+
+    python -m brain init
+    python -m brain doctor
+    python -m brain search "..."
+
+It delegates directly to the Typer app in :mod:`brain.cli`, which
+processes ``sys.argv`` and dispatches to the appropriate subcommand.
+``brain setup`` uses this path (via ``sys.executable``) to invoke ``brain
+init`` and ``brain doctor`` inside the same virtualenv that is running the
+installer, without relying on the ``brain`` console-script being on ``PATH``.
+"""
+
+from brain.cli import app
+
+app()