interactive-semantic-hunt 0.1.0__tar.gz

interactive_semantic_hunt-0.1.0/LICENSE

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

interactive_semantic_hunt-0.1.0/PKG-INFO

@@ -0,0 +1,316 @@
+Metadata-Version: 2.4
+Name: interactive-semantic-hunt
+Version: 0.1.0
+Summary: Interactive semantic search for code, inspired by fzf
+Author-email: David Kristiansen <david@kristiansen.tech>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/davetothek/interactive-semantic-hunt
+Project-URL: Repository, https://github.com/davetothek/interactive-semantic-hunt
+Project-URL: Issues, https://github.com/davetothek/interactive-semantic-hunt/issues
+Keywords: search,semantic,embeddings,code,fzf,tui,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.5.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: textual>=0.70.0
+Requires-Dist: tree-sitter>=0.26.0
+Requires-Dist: tree-sitter-c>=0.24.2
+Requires-Dist: tree-sitter-cpp>=0.23.4
+Provides-Extra: llama
+Requires-Dist: llama-cpp-python>=0.2.75; extra == "llama"
+Requires-Dist: huggingface-hub>=0.23.0; extra == "llama"
+Provides-Extra: st
+Requires-Dist: sentence-transformers; extra == "st"
+Dynamic: license-file
+
+# ish — Interactive Semantic Hunt
+
+Semantic search for code, inspired by `fzf`. Point `ish` at a directory. It parses
+each source file into named chunks, embeds them with a local model, and ranks them
+against your query. Everything runs on your machine.
+
+Languages: Python, C and C++, Markdown, and AsciiDoc. Documentation is indexed
+beside the code it describes, so one query searches both.
+
+## Install
+
+```sh
+pip install interactive-semantic-hunt
+```
+
+Nothing in that install compiles: the default backend reaches Ollama over
+HTTP with the standard library. A backend that runs the model in this
+process is an extra — `[llama]` for llama.cpp, `[st]` for
+sentence-transformers.
+
+To work on ish itself, clone it and run `uv sync`.
+
+The default embedding backend is Ollama, which keeps the model resident so no
+run pays a model load. Start it once and pull the embedding model:
+
+```sh
+ollama serve
+ollama pull nomic-embed-text
+```
+
+Set `OLLAMA_HOST` to reach a daemon elsewhere.
+
+Two other backends need no daemon:
+
+- `--embedder llama.cpp` downloads a GGUF model and loads it per run. Slower per
+  query, faster for a first index of a large tree. Needs the `[llama]` extra.
+- `--embedder st` uses sentence-transformers. Needs the `[st]` extra.
+
+## Use
+
+List every chunk under a path:
+
+```sh
+ish src/
+```
+
+```
+src/ish/domain/chunk.py:7-28  class  Chunk
+```
+
+Search for a query:
+
+```sh
+ish "parse a python file" src/
+```
+
+```
+[0.71] src/ish/adapters/parser/python.py:14-31  method  PythonParser.parse
+```
+
+Run the interactive picker and open the selection in your editor. Type to
+search, `up`/`down` or `ctrl+p`/`ctrl+n` to move, `enter` to choose, `escape`
+to quit. Narrow without leaving the query line:
+
+```text
+state machine transitions              every language
+lang:cpp state machine transitions     the implementation
+lang:yaml under:/10.System/ state      the tests that cover it
+type:doc how do I configure this       the prose, not the code
+type:test,doc retry backoff            the tests and what they document
+```
+
+Press Tab to finish a filter word. `ty` becomes `type:`, `lang:cp` becomes
+`lang:cpp`, and `under:/s` becomes `under:/src/`; a word with several answers
+grows as far as they agree and names the rest. `ish-complete` does the work, so
+any picker can call it.
+
+`lang:`, `under:`, and `type:` work in the query line of every interface —
+the command line, the picker, Neovim, and MCP. The words are taken out
+before the query is embedded, so the model sees the question rather than
+how it was narrowed.
+
+A language may be named however it comes to mind. `c`, `c++`, `cxx`, `h`, and
+`hpp` all mean `cpp`, because one parser reads them all; `adoc` means
+`asciidoc`, `md` means `markdown`, `py` means `python`, and `yml` means `yaml`.
+
+`type:` sorts every chunk into exactly one kind. A path decides before a
+language does, so a YAML fixture counts as a test rather than as config:
+
+| kind | what it holds |
+|---|---|
+| `code` | Python, C, C++, and anything a plugin parser adds |
+| `doc` | Markdown and AsciiDoc |
+| `test` | anything under `tests/`, `spec/`, `fixtures/`, plus `test_*` and `conftest.py` |
+| `config` | YAML, JSON, and TOML outside a test path |
+
+A repository that names its trees its own way can say so, in
+`.ish/config.toml`:
+
+```toml
+type_patterns = [
+  "test:/[0-9.]*(Tests|Verification)/",
+  "doc:/[0-9.]*Specification/",
+]
+```
+
+The first match wins; anything unmatched keeps the reading above.
+
+A config beside a subtree adds to the one above it, so a tree settles only
+what it names and inherits the rest. Searching inside an already-indexed tree
+reads that tree's index and narrows the answers to the path, rather than
+starting a second index of the same files.
+
+```sh
+nvim $(ish -i src/)
+```
+
+### Options
+
+| Flag | Purpose |
+|---|---|
+| `-i`, `--interactive` | Run the TUI picker |
+| `--embedder {llama.cpp,ollama,st}` | Select the embedding backend (default: ollama) |
+| `-v`, `-vv` | Increase log detail |
+| `--color {auto,always,never}` | Control log color |
+| `--limit N` | Maximum search results |
+| `--ignore DIR ...` | Directory names to skip (default `.git .venv venv __pycache__`) |
+| `--include REGEX ...` | Index only paths matching these patterns |
+| `--exclude REGEX ...` | Never index paths matching these patterns |
+| `--git`, `--no-git` | Skip files git ignores (default: on) |
+| `--lang LANG ...` | Show results only from these languages |
+| `--under REGEX` | Show results only from matching paths |
+| `--type TYPE ...` | Show results only of these kinds: `code`, `doc`, `test`, `config` |
+| `--type-patterns TYPE:REGEX ...` | Say what a path holds, overriding the built-in reading |
+| `--model NAME` | Override the backend model |
+| `--refresh` | Bring every stored index at or below the path up to date first |
+| `--reindex` | Discard the stored index and build it again |
+| `--no-cache` | Index in memory only, leaving nothing on disk |
+
+Logs go to stderr, so you can pipe stdout safely. A file that cannot be read
+or parsed is counted in one line; `-v` names them.
+
+## Use from Neovim
+
+`contrib/nvim/ish.lua` is an fzf-lua picker. Copy it to `lua/utils/ish.lua` and
+bind it:
+
+```lua
+map('n', '<leader>fi', function() require('utils.ish').search() end,
+    { desc = 'Semantic search (ish)' })
+```
+
+It reads `--format grep`, so the built-in previewer opens each result at its
+line, and prints the rank in the leftmost column. `search_lang({'cpp'})`,
+`search_type({'doc'})`, and `search_here()` narrow it, as does a `lang:`,
+`type:`, or `under:` word typed into the query.
+
+While the index refreshes, `require('utils.ish').statusline()` renders a bar
+for a statusline — `ish ███░░░░░ 38%` — and an empty string when idle. It reads `vim.g.ish_index_status`, which the picker keeps up to date, and
+shows `ish ✓` briefly when a refresh finishes. Nothing is reported through
+`vim.notify`: with `cmdheight = 0` there is no command line to put a message
+in, so nvim draws one over the last screen row — the statusline itself.
+
+The picker never blocks the editor: results are written as they arrive, so
+typing stays smooth however long a search takes.
+
+`contrib/nvim/ish_server.lua` keeps one `ish-mcp` process per session. It
+starts on the first search and is reused after that, which cuts a keystroke
+from about 500 ms to about 150 ms. Copy it beside the picker.
+
+## Use from Python
+
+```python
+from ish.interfaces.python.api import Ish
+
+with Ish("src/") as ish:
+    for chunk, score in ish.search("type:doc how to configure", limit=5):
+        print(score, chunk.path, chunk.symbol)
+    print(ish.status())
+```
+
+`Ish` holds the index open, so a second query costs a search rather than a
+process start. It offers `search()`, `chunks()`, `index()`, `refresh_all()`,
+and `status()`, and reads `lang:`, `type:`, and `under:` out of the query
+exactly as the other interfaces do.
+
+## Use from an agent
+
+`ish-mcp` serves the same search over the Model Context Protocol, so an agent
+can query the index directly. Add it to a project with `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ish": { "command": "uv", "args": ["run", "ish-mcp"] }
+  }
+}
+```
+
+It offers `search_code`, `list_chunks`, `index_status`, and `refresh_index`. The server stays
+resident, so a query costs about 58 ms rather than a process start.
+
+A call may narrow one search with `lang`, `under`, `type`, and `limit`, or
+write the same filters into the query text. It cannot change
+what is indexed — those settings come from `ish.toml` only, so no single call can
+shrink an index that another call depends on.
+
+## Index
+
+The index persists in SQLite under `$XDG_DATA_HOME/ish/`, one file per scanned
+tree. **A search of a parent reads the indexes below it and refreshes none** —
+choosing one of them to write to would be wrong — so it warns and offers
+`--refresh`, which visits each tree in turn. A repeated query reuses it, so only changed files are parsed and only new
+text is embedded. A renamed file re-embeds nothing.
+
+Each index records the tree it was built from, so searching a directory also
+searches every index below it. Index the parts of a large project separately and
+search the whole from its root:
+
+```sh
+ish "warm" project/docs        # index one part
+ish "warm" project/firmware    # and another
+ish "how is exposure set" project    # searches both
+```
+
+Searching a parent never rewrites an index below it. Pass `--no-federate` to use
+only the index of the exact path.
+
+The index records where each chunk is — its path, line range, kind, and name —
+together with the embedding vector. It does not store the source, so it is not a
+second readable copy of your code. Previews are read from the file, which also
+means they always show the current content.
+
+## Configure
+
+Every command-line option is also a key in `ish.toml`, under the same name.
+Put project settings in `ish.toml` at the root of your repository:
+
+```toml
+embedder = "ollama"
+model = "mxbai-embed-large"
+limit = 10
+ignore = [".git", ".venv", "build", "node_modules"]
+
+# Regular expressions, searched against the path.
+exclude = ["/vendor/", "_pb2\\.py$", "(_test|_spec)\\.py$"]
+```
+
+`include` and `exclude` take regular expressions rather than globs, so `/vendor/`
+matches at any depth and alternation works. `exclude` wins over `include`.
+
+`--git` is on by default, so anything a `.gitignore` covers stays out of the
+index. Pass `--no-git` to index it anyway.
+
+`--lang` and `--under` narrow what a search *returns*. They never change what is
+indexed, so a narrowed query cannot shrink the index:
+
+```sh
+ish "how is ranking done" --lang python
+ish "installation steps" --lang markdown asciidoc
+ish "parse a header" --under '/include/'
+```
+
+User-level defaults go in `~/.config/ish/ish.toml`. Later sources win:
+
+```
+defaults < ~/.config/ish/ish.toml < ./ish.toml < ISH_* environment < command line
+```
+
+Set any option from the environment with the `ISH_` prefix, for example
+`ISH_LIMIT=20` or `ISH_IGNORE=build,dist`.
+
+## Develop
+
+```sh
+uv run poe check   # lint, typecheck, test
+```
+
+The architecture is ports and adapters. `spec.md` holds the requirements, and
+`.claude/CLAUDE.md` describes the layers and the composition root.

interactive_semantic_hunt-0.1.0/README.md

@@ -0,0 +1,280 @@
+# ish — Interactive Semantic Hunt
+
+Semantic search for code, inspired by `fzf`. Point `ish` at a directory. It parses
+each source file into named chunks, embeds them with a local model, and ranks them
+against your query. Everything runs on your machine.
+
+Languages: Python, C and C++, Markdown, and AsciiDoc. Documentation is indexed
+beside the code it describes, so one query searches both.
+
+## Install
+
+```sh
+pip install interactive-semantic-hunt
+```
+
+Nothing in that install compiles: the default backend reaches Ollama over
+HTTP with the standard library. A backend that runs the model in this
+process is an extra — `[llama]` for llama.cpp, `[st]` for
+sentence-transformers.
+
+To work on ish itself, clone it and run `uv sync`.
+
+The default embedding backend is Ollama, which keeps the model resident so no
+run pays a model load. Start it once and pull the embedding model:
+
+```sh
+ollama serve
+ollama pull nomic-embed-text
+```
+
+Set `OLLAMA_HOST` to reach a daemon elsewhere.
+
+Two other backends need no daemon:
+
+- `--embedder llama.cpp` downloads a GGUF model and loads it per run. Slower per
+  query, faster for a first index of a large tree. Needs the `[llama]` extra.
+- `--embedder st` uses sentence-transformers. Needs the `[st]` extra.
+
+## Use
+
+List every chunk under a path:
+
+```sh
+ish src/
+```
+
+```
+src/ish/domain/chunk.py:7-28  class  Chunk
+```
+
+Search for a query:
+
+```sh
+ish "parse a python file" src/
+```
+
+```
+[0.71] src/ish/adapters/parser/python.py:14-31  method  PythonParser.parse
+```
+
+Run the interactive picker and open the selection in your editor. Type to
+search, `up`/`down` or `ctrl+p`/`ctrl+n` to move, `enter` to choose, `escape`
+to quit. Narrow without leaving the query line:
+
+```text
+state machine transitions              every language
+lang:cpp state machine transitions     the implementation
+lang:yaml under:/10.System/ state      the tests that cover it
+type:doc how do I configure this       the prose, not the code
+type:test,doc retry backoff            the tests and what they document
+```
+
+Press Tab to finish a filter word. `ty` becomes `type:`, `lang:cp` becomes
+`lang:cpp`, and `under:/s` becomes `under:/src/`; a word with several answers
+grows as far as they agree and names the rest. `ish-complete` does the work, so
+any picker can call it.
+
+`lang:`, `under:`, and `type:` work in the query line of every interface —
+the command line, the picker, Neovim, and MCP. The words are taken out
+before the query is embedded, so the model sees the question rather than
+how it was narrowed.
+
+A language may be named however it comes to mind. `c`, `c++`, `cxx`, `h`, and
+`hpp` all mean `cpp`, because one parser reads them all; `adoc` means
+`asciidoc`, `md` means `markdown`, `py` means `python`, and `yml` means `yaml`.
+
+`type:` sorts every chunk into exactly one kind. A path decides before a
+language does, so a YAML fixture counts as a test rather than as config:
+
+| kind | what it holds |
+|---|---|
+| `code` | Python, C, C++, and anything a plugin parser adds |
+| `doc` | Markdown and AsciiDoc |
+| `test` | anything under `tests/`, `spec/`, `fixtures/`, plus `test_*` and `conftest.py` |
+| `config` | YAML, JSON, and TOML outside a test path |
+
+A repository that names its trees its own way can say so, in
+`.ish/config.toml`:
+
+```toml
+type_patterns = [
+  "test:/[0-9.]*(Tests|Verification)/",
+  "doc:/[0-9.]*Specification/",
+]
+```
+
+The first match wins; anything unmatched keeps the reading above.
+
+A config beside a subtree adds to the one above it, so a tree settles only
+what it names and inherits the rest. Searching inside an already-indexed tree
+reads that tree's index and narrows the answers to the path, rather than
+starting a second index of the same files.
+
+```sh
+nvim $(ish -i src/)
+```
+
+### Options
+
+| Flag | Purpose |
+|---|---|
+| `-i`, `--interactive` | Run the TUI picker |
+| `--embedder {llama.cpp,ollama,st}` | Select the embedding backend (default: ollama) |
+| `-v`, `-vv` | Increase log detail |
+| `--color {auto,always,never}` | Control log color |
+| `--limit N` | Maximum search results |
+| `--ignore DIR ...` | Directory names to skip (default `.git .venv venv __pycache__`) |
+| `--include REGEX ...` | Index only paths matching these patterns |
+| `--exclude REGEX ...` | Never index paths matching these patterns |
+| `--git`, `--no-git` | Skip files git ignores (default: on) |
+| `--lang LANG ...` | Show results only from these languages |
+| `--under REGEX` | Show results only from matching paths |
+| `--type TYPE ...` | Show results only of these kinds: `code`, `doc`, `test`, `config` |
+| `--type-patterns TYPE:REGEX ...` | Say what a path holds, overriding the built-in reading |
+| `--model NAME` | Override the backend model |
+| `--refresh` | Bring every stored index at or below the path up to date first |
+| `--reindex` | Discard the stored index and build it again |
+| `--no-cache` | Index in memory only, leaving nothing on disk |
+
+Logs go to stderr, so you can pipe stdout safely. A file that cannot be read
+or parsed is counted in one line; `-v` names them.
+
+## Use from Neovim
+
+`contrib/nvim/ish.lua` is an fzf-lua picker. Copy it to `lua/utils/ish.lua` and
+bind it:
+
+```lua
+map('n', '<leader>fi', function() require('utils.ish').search() end,
+    { desc = 'Semantic search (ish)' })
+```
+
+It reads `--format grep`, so the built-in previewer opens each result at its
+line, and prints the rank in the leftmost column. `search_lang({'cpp'})`,
+`search_type({'doc'})`, and `search_here()` narrow it, as does a `lang:`,
+`type:`, or `under:` word typed into the query.
+
+While the index refreshes, `require('utils.ish').statusline()` renders a bar
+for a statusline — `ish ███░░░░░ 38%` — and an empty string when idle. It reads `vim.g.ish_index_status`, which the picker keeps up to date, and
+shows `ish ✓` briefly when a refresh finishes. Nothing is reported through
+`vim.notify`: with `cmdheight = 0` there is no command line to put a message
+in, so nvim draws one over the last screen row — the statusline itself.
+
+The picker never blocks the editor: results are written as they arrive, so
+typing stays smooth however long a search takes.
+
+`contrib/nvim/ish_server.lua` keeps one `ish-mcp` process per session. It
+starts on the first search and is reused after that, which cuts a keystroke
+from about 500 ms to about 150 ms. Copy it beside the picker.
+
+## Use from Python
+
+```python
+from ish.interfaces.python.api import Ish
+
+with Ish("src/") as ish:
+    for chunk, score in ish.search("type:doc how to configure", limit=5):
+        print(score, chunk.path, chunk.symbol)
+    print(ish.status())
+```
+
+`Ish` holds the index open, so a second query costs a search rather than a
+process start. It offers `search()`, `chunks()`, `index()`, `refresh_all()`,
+and `status()`, and reads `lang:`, `type:`, and `under:` out of the query
+exactly as the other interfaces do.
+
+## Use from an agent
+
+`ish-mcp` serves the same search over the Model Context Protocol, so an agent
+can query the index directly. Add it to a project with `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ish": { "command": "uv", "args": ["run", "ish-mcp"] }
+  }
+}
+```
+
+It offers `search_code`, `list_chunks`, `index_status`, and `refresh_index`. The server stays
+resident, so a query costs about 58 ms rather than a process start.
+
+A call may narrow one search with `lang`, `under`, `type`, and `limit`, or
+write the same filters into the query text. It cannot change
+what is indexed — those settings come from `ish.toml` only, so no single call can
+shrink an index that another call depends on.
+
+## Index
+
+The index persists in SQLite under `$XDG_DATA_HOME/ish/`, one file per scanned
+tree. **A search of a parent reads the indexes below it and refreshes none** —
+choosing one of them to write to would be wrong — so it warns and offers
+`--refresh`, which visits each tree in turn. A repeated query reuses it, so only changed files are parsed and only new
+text is embedded. A renamed file re-embeds nothing.
+
+Each index records the tree it was built from, so searching a directory also
+searches every index below it. Index the parts of a large project separately and
+search the whole from its root:
+
+```sh
+ish "warm" project/docs        # index one part
+ish "warm" project/firmware    # and another
+ish "how is exposure set" project    # searches both
+```
+
+Searching a parent never rewrites an index below it. Pass `--no-federate` to use
+only the index of the exact path.
+
+The index records where each chunk is — its path, line range, kind, and name —
+together with the embedding vector. It does not store the source, so it is not a
+second readable copy of your code. Previews are read from the file, which also
+means they always show the current content.
+
+## Configure
+
+Every command-line option is also a key in `ish.toml`, under the same name.
+Put project settings in `ish.toml` at the root of your repository:
+
+```toml
+embedder = "ollama"
+model = "mxbai-embed-large"
+limit = 10
+ignore = [".git", ".venv", "build", "node_modules"]
+
+# Regular expressions, searched against the path.
+exclude = ["/vendor/", "_pb2\\.py$", "(_test|_spec)\\.py$"]
+```
+
+`include` and `exclude` take regular expressions rather than globs, so `/vendor/`
+matches at any depth and alternation works. `exclude` wins over `include`.
+
+`--git` is on by default, so anything a `.gitignore` covers stays out of the
+index. Pass `--no-git` to index it anyway.
+
+`--lang` and `--under` narrow what a search *returns*. They never change what is
+indexed, so a narrowed query cannot shrink the index:
+
+```sh
+ish "how is ranking done" --lang python
+ish "installation steps" --lang markdown asciidoc
+ish "parse a header" --under '/include/'
+```
+
+User-level defaults go in `~/.config/ish/ish.toml`. Later sources win:
+
+```
+defaults < ~/.config/ish/ish.toml < ./ish.toml < ISH_* environment < command line
+```
+
+Set any option from the environment with the `ISH_` prefix, for example
+`ISH_LIMIT=20` or `ISH_IGNORE=build,dist`.
+
+## Develop
+
+```sh
+uv run poe check   # lint, typecheck, test
+```
+
+The architecture is ports and adapters. `spec.md` holds the requirements, and
+`.claude/CLAUDE.md` describes the layers and the composition root.