metis-brain 0.1.0__tar.gz

metis_brain-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.metis/
+local_docs
+.DS_Store

metis_brain-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 itsautomata
+
+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.

metis_brain-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: metis-brain
+Version: 0.1.0
+Summary: CLI second brain for your markdown notes
+Project-URL: Homepage, https://github.com/itsautomata/metis
+Project-URL: Repository, https://github.com/itsautomata/metis
+Project-URL: Issues, https://github.com/itsautomata/metis/issues
+Author: itsautomata
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,embeddings,knowledge-base,markdown,note-taking,obsidian,rag,second-brain,semantic-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: chromadb>=0.6.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: lxml-html-clean>=0.4.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pymupdf>=1.24.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: scikit-learn>=1.5.0
+Requires-Dist: trafilatura>=1.12.0
+Requires-Dist: typer>=0.15.0
+Requires-Dist: youtube-transcript-api>=1.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/itsautomata/metis/main/assets/metis_draft.gif" alt="metis" width="330">
+</p>
+
+## metis
+a cli second brain for your markdown notes: [obsidian](https://obsidian.md/download) (recommended), an alternative, or just a normal folder.
+
+ingest anything. search by meaning. chat with your knowledge. discover connections.
+
+---
+
+## setup
+
+### install
+
+**pip.** requires python 3.10+
+
+```bash
+pip install metis-brain
+```
+
+**uv**
+
+```bash
+uv tool install metis-brain   # if you don't have uv installed run: curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+**git (for development):**
+
+```bash
+git clone https://github.com/itsautomata/metis
+cd metis
+uv tool install -e .             # global, editable
+uv tool install -e . --force     # update the global install
+# or in a virtualenv:
+uv venv && source .venv/bin/activate && uv pip install -e "."
+```
+### upgrade
+
+```bash
+uv tool upgrade metis-brain               # installed with uv
+pip install --upgrade metis-brain         # installed with pip
+git pull && uv tool install -e . --force  # dev / editable clone
+```
+
+
+then set up, whichever way you installed:
+
+```bash
+metis init
+metis --install-completion  # enable tab completion for commands
+exec $SHELL                 # restart shell to apply
+```
+
+store your api keys securely:
+
+```bash
+metis secret set provider-key  # your one key (works for any provider via base_url)
+metis secret set x-token       # optional, for full x/twitter extraction
+metis secret set               # interactive, you pick which key you want to set
+metis secret list              # show which keys are set (no values)
+metis doctor                   # verify the whole setup: key, provider, models, index
+metis models                   # show the chat + embedding models (and provider) in use
+```
+
+quick changes via `metis config vault <path>`. for everything else, edit `~/.metis/config.yaml`.
+
+---
+
+## commands
+
+run `metis --help` or `metis <command> --help` for all options.
+
+### ingest
+
+save anything to your vault: summarized, tagged, embedded, and linked back to the source.
+
+```bash
+metis ingest https://en.wikipedia.org/wiki/Metis_(mythology)
+metis ingest ~/books/project-hail-mary.pdf
+metis ingest lecture-notes.md
+metis ingest paper.pdf --folder research/ai
+metis ingest https://www.youtube.com/watch?v=abc123 --lang fr
+metis ingest https://arxiv.org/abs/2401.12345
+metis ingest paper1.pdf paper2.pdf https://arxiv.org/abs/2402.00001
+```
+
+accepts one source or many at once. supports pdfs, urls, markdown, arxiv papers, youtube videos, and x/twitter posts. `--folder` organizes into vault subfolders.
+
+> interactive: `--pick-folder` (vault folders) / `--pick-lang` (transcript languages)
+
+---
+
+### search
+
+```bash
+metis search "what role did titans play in greek mythos"
+```
+
+semantic search. finds by meaning, not keywords. pick a result to chat about it.
+
+---
+
+### chat
+
+```bash
+metis chat "how does project hail mary handle the fermi paradox?"
+metis chat "what does he say about nash equilibrium?" --note game_theory/intro
+metis chat "question" --note game_theory/intro --save
+metis chat "question" --expand
+```
+
+answers grounded in your vault with sources cited. `--note` scopes to a specific note and offers to save the Q&A. `--save` saves without prompting. `--expand` searches wikipedia when your vault doesn't have enough.
+
+> interactive: `--pick` (choose vault note to ask about)
+
+---
+
+### link
+
+```bash
+metis link
+metis link --write
+metis link --verbose
+```
+
+discovers connections between notes. `--write` adds links in your vault's style, auto-detected: `[[wikilinks]]` for obsidian and similar apps, `[markdown](links)` for a plain folder (override with `metis config link-style`). `--verbose` explains why notes are connected.
+
+> interactive: `--pick` (choose vault note to find connections for)
+
+---
+
+### sync
+
+```bash
+metis sync
+```
+
+re-indexes the vault after you edit notes.
+
+---
+
+### reindex
+
+```bash
+metis reindex
+```
+
+rebuilds the whole vector index from scratch. run it after changing your
+`embedding_model`: the old vectors live in a different space, so metis refuses
+search/link/health until you reindex.
+
+---
+
+## classification & clustering
+
+metis learns from your vault to help you organize.
+
+**auto-categorization:** when you ingest without `--folder`, metis suggests a folder based on your vault's content. accept, override, or pick from menu. every choice improves future suggestions.
+
+**vault health:**
+
+```bash
+metis health
+metis health --misplaced
+metis health --split hermes_folder
+metis health --unique
+```
+
+checkup on your vault structure. shows folder alignment, suggests which notes might belong in a different folder, and proposes subfolder splits for large folders.
+
+**folder descriptions:**
+
+```bash
+metis folders
+metis folders --edit
+```
+
+list folders with their ML descriptions. `--edit` opens in your editor to refine how the classifier understands each folder.
+
+---
+
+## config
+
+```bash
+metis config                       # show current settings
+metis config vault ~/obsidian/my-vault
+metis config folder metis-ingested
+metis config link-style wikilink   # or markdown, or auto (default: detect from the vault)
+```
+
+for anything not covered above, edit `~/.metis/config.yaml`:
+
+```yaml
+# ~/.metis/config.yaml
+
+vault_path: ~/obsidian/my-vault
+output_folder: metis-ingested
+
+openai:
+  # base_url points at any OpenAI-compatible provider.
+  # leave empty for OpenAI; set it for OpenRouter, Ollama, a local server, etc.
+  base_url: ""              # e.g. https://openrouter.ai/api/v1
+  chat_model: gpt-4o
+  embedding_model: text-embedding-3-small
+```
+
+api keys live in your os keychain via `metis secret set`, or a `METIS_*` env var for automation (`METIS_PROVIDER_KEY`, `METIS_EMBEDDING_KEY`, `METIS_X_BEARER`). keys never go in the config file. one key covers both chat and embeddings; set an `embedding-key` only if you split embeddings to a different provider. run `metis doctor` to check your setup: it verifies the key, the provider, the models, and the index in one pass.
+
+> changing `embedding_model` re-spaces the whole index. metis will refuse until you run `metis reindex`.
+>
+> on a gateway like OpenRouter, embedding ids are vendor-prefixed; metis auto-adapts the default `text-embedding-3-small` to `openai/text-embedding-3-small`.

metis_brain-0.1.0/README.md

@@ -0,0 +1,212 @@
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/itsautomata/metis/main/assets/metis_draft.gif" alt="metis" width="330">
+</p>
+
+## metis
+a cli second brain for your markdown notes: [obsidian](https://obsidian.md/download) (recommended), an alternative, or just a normal folder.
+
+ingest anything. search by meaning. chat with your knowledge. discover connections.
+
+---
+
+## setup
+
+### install
+
+**pip.** requires python 3.10+
+
+```bash
+pip install metis-brain
+```
+
+**uv**
+
+```bash
+uv tool install metis-brain   # if you don't have uv installed run: curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+**git (for development):**
+
+```bash
+git clone https://github.com/itsautomata/metis
+cd metis
+uv tool install -e .             # global, editable
+uv tool install -e . --force     # update the global install
+# or in a virtualenv:
+uv venv && source .venv/bin/activate && uv pip install -e "."
+```
+### upgrade
+
+```bash
+uv tool upgrade metis-brain               # installed with uv
+pip install --upgrade metis-brain         # installed with pip
+git pull && uv tool install -e . --force  # dev / editable clone
+```
+
+
+then set up, whichever way you installed:
+
+```bash
+metis init
+metis --install-completion  # enable tab completion for commands
+exec $SHELL                 # restart shell to apply
+```
+
+store your api keys securely:
+
+```bash
+metis secret set provider-key  # your one key (works for any provider via base_url)
+metis secret set x-token       # optional, for full x/twitter extraction
+metis secret set               # interactive, you pick which key you want to set
+metis secret list              # show which keys are set (no values)
+metis doctor                   # verify the whole setup: key, provider, models, index
+metis models                   # show the chat + embedding models (and provider) in use
+```
+
+quick changes via `metis config vault <path>`. for everything else, edit `~/.metis/config.yaml`.
+
+---
+
+## commands
+
+run `metis --help` or `metis <command> --help` for all options.
+
+### ingest
+
+save anything to your vault: summarized, tagged, embedded, and linked back to the source.
+
+```bash
+metis ingest https://en.wikipedia.org/wiki/Metis_(mythology)
+metis ingest ~/books/project-hail-mary.pdf
+metis ingest lecture-notes.md
+metis ingest paper.pdf --folder research/ai
+metis ingest https://www.youtube.com/watch?v=abc123 --lang fr
+metis ingest https://arxiv.org/abs/2401.12345
+metis ingest paper1.pdf paper2.pdf https://arxiv.org/abs/2402.00001
+```
+
+accepts one source or many at once. supports pdfs, urls, markdown, arxiv papers, youtube videos, and x/twitter posts. `--folder` organizes into vault subfolders.
+
+> interactive: `--pick-folder` (vault folders) / `--pick-lang` (transcript languages)
+
+---
+
+### search
+
+```bash
+metis search "what role did titans play in greek mythos"
+```
+
+semantic search. finds by meaning, not keywords. pick a result to chat about it.
+
+---
+
+### chat
+
+```bash
+metis chat "how does project hail mary handle the fermi paradox?"
+metis chat "what does he say about nash equilibrium?" --note game_theory/intro
+metis chat "question" --note game_theory/intro --save
+metis chat "question" --expand
+```
+
+answers grounded in your vault with sources cited. `--note` scopes to a specific note and offers to save the Q&A. `--save` saves without prompting. `--expand` searches wikipedia when your vault doesn't have enough.
+
+> interactive: `--pick` (choose vault note to ask about)
+
+---
+
+### link
+
+```bash
+metis link
+metis link --write
+metis link --verbose
+```
+
+discovers connections between notes. `--write` adds links in your vault's style, auto-detected: `[[wikilinks]]` for obsidian and similar apps, `[markdown](links)` for a plain folder (override with `metis config link-style`). `--verbose` explains why notes are connected.
+
+> interactive: `--pick` (choose vault note to find connections for)
+
+---
+
+### sync
+
+```bash
+metis sync
+```
+
+re-indexes the vault after you edit notes.
+
+---
+
+### reindex
+
+```bash
+metis reindex
+```
+
+rebuilds the whole vector index from scratch. run it after changing your
+`embedding_model`: the old vectors live in a different space, so metis refuses
+search/link/health until you reindex.
+
+---
+
+## classification & clustering
+
+metis learns from your vault to help you organize.
+
+**auto-categorization:** when you ingest without `--folder`, metis suggests a folder based on your vault's content. accept, override, or pick from menu. every choice improves future suggestions.
+
+**vault health:**
+
+```bash
+metis health
+metis health --misplaced
+metis health --split hermes_folder
+metis health --unique
+```
+
+checkup on your vault structure. shows folder alignment, suggests which notes might belong in a different folder, and proposes subfolder splits for large folders.
+
+**folder descriptions:**
+
+```bash
+metis folders
+metis folders --edit
+```
+
+list folders with their ML descriptions. `--edit` opens in your editor to refine how the classifier understands each folder.
+
+---
+
+## config
+
+```bash
+metis config                       # show current settings
+metis config vault ~/obsidian/my-vault
+metis config folder metis-ingested
+metis config link-style wikilink   # or markdown, or auto (default: detect from the vault)
+```
+
+for anything not covered above, edit `~/.metis/config.yaml`:
+
+```yaml
+# ~/.metis/config.yaml
+
+vault_path: ~/obsidian/my-vault
+output_folder: metis-ingested
+
+openai:
+  # base_url points at any OpenAI-compatible provider.
+  # leave empty for OpenAI; set it for OpenRouter, Ollama, a local server, etc.
+  base_url: ""              # e.g. https://openrouter.ai/api/v1
+  chat_model: gpt-4o
+  embedding_model: text-embedding-3-small
+```
+
+api keys live in your os keychain via `metis secret set`, or a `METIS_*` env var for automation (`METIS_PROVIDER_KEY`, `METIS_EMBEDDING_KEY`, `METIS_X_BEARER`). keys never go in the config file. one key covers both chat and embeddings; set an `embedding-key` only if you split embeddings to a different provider. run `metis doctor` to check your setup: it verifies the key, the provider, the models, and the index in one pass.
+
+> changing `embedding_model` re-spaces the whole index. metis will refuse until you run `metis reindex`.
+>
+> on a gateway like OpenRouter, embedding ids are vendor-prefixed; metis auto-adapts the default `text-embedding-3-small` to `openai/text-embedding-3-small`.

metis_brain-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "metis-brain"
+description = "CLI second brain for your markdown notes"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "itsautomata" }]
+requires-python = ">=3.10"
+dynamic = ["version"]
+keywords = ["second-brain", "obsidian", "markdown", "cli", "rag", "embeddings", "knowledge-base", "semantic-search", "note-taking"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
+    "Topic :: Text Processing :: Indexing",
+]
+dependencies = [
+    "typer>=0.15.0",
+    "rich>=13.0.0",
+    "pyyaml>=6.0",
+    "openai>=1.0.0",
+    "chromadb>=0.6.0",
+    "pymupdf>=1.24.0",
+    "httpx>=0.27.0",
+    "trafilatura>=1.12.0",
+    "lxml-html-clean>=0.4.0",
+    "youtube-transcript-api>=1.0.0",
+    "keyring>=25.0.0",
+    "questionary>=2.0.0",
+    "scikit-learn>=1.5.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0.0",
+]
+
+[project.scripts]
+metis = "metis.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/itsautomata/metis"
+Repository = "https://github.com/itsautomata/metis"
+Issues = "https://github.com/itsautomata/metis/issues"
+
+# suppress chromadb's SWIG deprecation warnings in test output
+[tool.pytest.ini_options]
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.hatch.version]
+path = "src/metis/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/metis"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+]

metis_brain-0.1.0/src/metis/.trace

@@ -0,0 +1 @@
+architecture with love. automata.

metis_brain-0.1.0/src/metis/__init__.py

@@ -0,0 +1,3 @@
+"""metis: CLI second brain for your markdown notes."""
+
+__version__ = "0.1.0"