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