async def _add(a, b): return a + b
assert arun(_add(1, 2)) == L(3)
print('arun: sync context ok')arun: sync context okcore
Kosha is a tool for building a context for code generation based on your repo and environment.
Utils
Utility functions for finding the repo root, copying the SKILL.md file, running async code from sync contexts, and getting installed package versions.
parse
def parse(
code:NoneType=None, p:NoneType=None
):Parse source, tag parents, return (tree, imp, top_fns, all_fns, imp2mod). Cached — called freely.
mv_skill_md
def mv_skill_md(
dry_run:bool=True, dir:NoneType=None
)->None:Copy bundled SKILL.md to skill directories.
repo_root
def repo_root()->Path:Find the root of the current git repository, or None if not in a repo.
arun
def arun(
coro
)->any:Run an async coroutine from sync code, even if already inside an event loop
async def _test_nested():
result = arun(_add(10, 20))
assert first(result) == 30, f'got {result}'
arun(_test_nested())
print('arun: nested-loop context ok')arun: nested-loop context okmv_skill_md()mv_skill_md(dir='.')pkg_trans_deps
def pkg_trans_deps(
seeds:list, depth:int=2
)->L:BFS over importlib.metadata requires: return seeds + all transitive deps up to depth levels (installed only, no optional extras).
env_pkg_versions
def env_pkg_versions(
pyproject:bool=True, depth:int=1, xtras:NoneType=None
)->dict:Get a dict of installed package versions using importlib.metadata. passing depth traverse multiple layers of dependencies
installed_packages(pyproject=True)pkg_trans_deps(['litesearch'], depth=1)['notebook', 'usearch', 'codesigs', 'model2vec', 'tokenizers', 'flashrank', 'onnxruntime', 'pdf-oxide', 'chonkie', 'litesearch', 'pillow', 'liteparse', 'spacy', 'fastlite', 'pandas', 'onnx', 'yake']# httpx depends on httpcore; depth=1 should include both httpx + httpcore
d1 = pkg_trans_deps(['httpx'], depth=1)
assert 'httpx' in d1, "seeds must be in result"
assert 'httpcore' in d1, f"depth=1 should include httpcore (direct dep of httpx): {d1}"
# depth=0 returns only seeds
assert list(pkg_trans_deps(['httpx'], depth=0)) == ['httpx'], "depth=0 should return only seeds"
# pyproject seeds → depth=2 expansion
pyp = installed_packages(pyproject=True)
if pyp:
deep = pkg_trans_deps(list(pyp), depth=2)
assert set(pyp).issubset(set(deep)), "seeds must be a subset of result"
assert len(deep) >= len(pyp), "depth=2 should expand beyond pyproject direct deps"
print(f"pkg_trans_deps ok: {len(pyp)} pyproject seeds → {len(deep)} packages at depth=2")
else:
print("pkg_trans_deps ok (no pyproject deps to test)")pkg_trans_deps ok: 5 pyproject seeds → 80 packages at depth=2d=env_pkg_versions(xtras=None); {k:d[k] for k in list(d.keys())[-5:]}{'fastlite': '0.2.4',
'pyskills': '0.0.27',
'pandas': '3.0.5',
'onnx': '1.22.0',
'yake': '0.7.3'}d=env_pkg_versions(); {k:d[k] for k in list(d.keys())[-5:]}{'fastaudit': '0.2.7',
'liteparse': '2.11.0',
'asttokens': '3.0.2',
'curl_cffi': '0.16.0',
'watchdog': '6.0.0'}Kosha
The main class for managing the code and environment databases, updating package metadata, embedding code snippets, and performing context-aware searches.
Kosha
def Kosha(
dir:Path=None, install_skill:bool=False, xdg_dir:Path=None,
efn:bind=<fastcore.basics.bind object at 0x7f36882e95b0>,
busy_timeout:int=None, # ms to wait on a locked db; set this for parallel ingestion, else apsw's default
):Kosha allows you to build a context for code generation based on your repo and environment.
cast_emb
def cast_emb(
f, dtype:type=float16
):Wrap an encoder so its vectors carry the dtype the store is read back with.
k=Kosha()/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
from .autonotebook import tqdm as notebook_tqdmk.emb_doc('def add(a, b): return a + b')[:5]array([[ 1.0394e-01, 4.9438e-03, -1.2079e-01, 6.4026e-02, 6.0699e-02,
-1.9971e-01, 7.8125e-02, -2.9053e-02, 1.3100e-02, 3.9398e-02,
1.1307e-02, -8.7830e-02, 1.8845e-02, 4.8309e-02, -8.6670e-02,
8.5083e-02, -1.0788e-02, 4.5197e-02, -1.8661e-02, 4.2084e-02,
2.5284e-02, -1.0582e-02, -2.4757e-03, -2.8519e-02, 3.7109e-02,
-2.4109e-02, -5.1514e-02, -3.3875e-02, -3.2867e-02, 1.3110e-01,
-7.6342e-04, -5.1331e-02, -2.2522e-02, -8.9233e-02, -1.1131e-02,
-1.0872e-02, -5.7861e-02, -8.6975e-02, -3.4790e-02, -1.3191e-02,
7.6965e-02, -3.4210e-02, -3.2532e-02, 3.8605e-02, 4.3304e-02,
-9.4360e-02, -4.0497e-02, -5.2490e-02, 2.0142e-02, -1.2463e-01,
-1.7975e-02, 4.4464e-02, 5.1788e-02, 1.8530e-01, 9.9976e-02,
7.2571e-02, 7.6233e-02, 1.0156e-01, 6.5727e-03, 1.8646e-02,
3.8109e-03, 6.3232e-02, 4.9774e-02, 4.4373e-02, 8.8196e-03,
1.0364e-01, 2.7695e-02, -1.1450e-01, 4.9866e-02, -4.1779e-02,
-6.3904e-02, 1.0948e-02, -1.0107e-01, 2.2339e-02, 1.6312e-02,
2.0538e-02, 3.3691e-02, 4.0192e-02, 4.7882e-02, 9.2590e-02,
2.7359e-02, 2.4353e-02, 8.8196e-02, -5.7312e-02, 1.2067e-01,
-1.1833e-02, -7.1533e-02, -1.3000e-01, -2.2934e-02, 2.9678e-02,
1.0124e-02, -5.9174e-02, -8.7891e-02, -1.3328e-04, 7.9468e-02,
7.2815e-02, 8.6853e-02, -2.7161e-02, 4.9713e-02, 6.1798e-02,
7.4829e-02, -2.1210e-02, -6.4087e-02, 3.5706e-02, -1.1444e-01,
-1.5778e-02, -7.2021e-02, -5.9937e-02, -4.8523e-02, -1.0864e-01,
9.4238e-02, 9.2239e-03, -7.1533e-02, -4.8828e-02, -5.2216e-02,
-8.4717e-02, -8.4290e-02, 2.0569e-02, -5.8502e-02, 2.7908e-02,
1.5350e-02, 7.9529e-02, -8.6594e-03, -2.2354e-02, 2.4918e-02,
3.7323e-02, 1.5961e-02, -6.4453e-02, 9.7168e-02, 6.5552e-02,
-1.1163e-01, -1.6711e-01, 1.5190e-02, -3.5400e-02, 1.2323e-01,
7.2693e-02, -3.7964e-02, -3.4821e-02, 1.9360e-01, -4.2725e-02,
-8.1848e-02, 4.2145e-02, -3.4302e-02, 8.3466e-03, 1.8509e-02,
-1.5808e-02, 5.4970e-03, 6.9885e-02, 5.5817e-02, 6.7749e-02,
-2.2705e-02, -3.4332e-02, -6.4758e-02, -1.4481e-02, 8.5327e-02,
8.7738e-04, -4.2328e-02, 7.2327e-02, 4.8309e-02, 9.3018e-02,
-2.1210e-02, -5.6763e-02, 8.1726e-02, 3.0060e-02, 5.3070e-02,
-1.6449e-02, -1.5579e-02, -7.2327e-03, 5.1636e-02, 1.1925e-02,
-8.4167e-02, -3.1921e-02, -7.5745e-02, 1.5356e-01, 1.4246e-01,
-9.9792e-03, 2.1652e-02, 1.0718e-01, 6.3416e-02, 6.4850e-03,
-1.2825e-02, -5.4077e-02, 7.2708e-03, -2.0111e-02, 9.6558e-02,
-4.5868e-02, 9.1187e-02, 4.5441e-02, 2.5040e-02, -1.2030e-01,
-1.0168e-01, -3.1281e-02, -2.1194e-02, -1.2444e-02, -1.3023e-02,
-1.5839e-02, 2.8793e-02, 7.4463e-03, -5.8502e-02, 5.7030e-03,
-1.7670e-02, 6.3171e-02, -6.8787e-02, 2.2537e-02, -7.9727e-03,
-7.9224e-02, 3.8269e-02, -4.7638e-02, -4.1168e-02, -3.0106e-02,
-2.2339e-02, 2.7359e-02, -1.0269e-02, -2.3163e-02, 1.7654e-02,
5.1147e-02, -5.9998e-02, 5.3497e-02, 1.8448e-02, -7.0923e-02,
2.4246e-02, 4.7760e-02, -5.9509e-02, 1.4519e-02, -3.8422e-02,
-9.5139e-03, -5.0201e-03, 8.6899e-03, -7.0801e-02, 3.2135e-02,
-1.4062e-01, -1.4954e-01, 1.9623e-02, -9.6130e-02, -1.3374e-02,
5.7922e-02, 5.0171e-02, 3.8940e-02, 5.6488e-02, 9.1629e-03,
1.3130e-02, -5.2246e-02, -6.3416e-02, 3.0396e-02, 1.9089e-02,
8.6487e-02, -3.2715e-02, -5.2734e-02, 5.3802e-02, 9.0408e-03,
-1.0633e-03, 4.0405e-02, -1.7990e-02, 5.1056e-02, 4.7089e-02,
-8.9905e-02]], dtype=float16)pkg_url
def pkg_url(
pkg:str
)->str | None:Return best web URL for pkg from importlib.metadata: Source Code > Repository > Home-page > first Project-URL.
pkg_doc
def pkg_doc(
pkg
)->dict:Build pkg_store content dict: content=summary+readme, metadata=json.
pkg_doc('httpx'){'content': 'The next generation HTTP client.\n<p align="center">\n <a href="https://www.python-httpx.org/"><img width="350" height="208" src="https://raw.githubusercontent.com/encode/httpx/master/docs/img/butterfly.png" alt=\'HTTPX\'></a>\n</p>\n\n<p align="center"><strong>HTTPX</strong> <em>- A next-generation HTTP client for Python.</em></p>\n\n<p align="center">\n<a href="https://github.com/encode/httpx/actions">\n <img src="https://github.com/encode/httpx/workflows/Test%20Suite/badge.svg" alt="Test Suite">\n</a>\n<a href="https://pypi.org/project/httpx/">\n <img src="https://badge.fury.io/py/httpx.svg" alt="Package version">\n</a>\n</p>\n\nHTTPX is a fully featured HTTP client library for Python 3. It includes **an integrated command line client**, has support for both **HTTP/1.1 and HTTP/2**, and provides both **sync and async APIs**.\n\n---\n\nInstall HTTPX using pip:\n\n```shell\n$ pip install httpx\n```\n\nNow, let\'s get started:\n\n```pycon\n>>> import httpx\n>>> r = httpx.get(\'https://www.example.org/\')\n>>> r\n<Response [200 OK]>\n>>> r.status_code\n200\n>>> r.headers[\'content-type\']\n\'text/html; charset=UTF-8\'\n>>> r.text\n\'<!doctype html>\\n<html>\\n<head>\\n<title>Example Domain</title>...\'\n```\n\nOr, using the command-line client.\n\n```shell\n$ pip install \'httpx[cli]\' # The command line client is an optional dependency.\n```\n\nWhich now allows us to use HTTPX directly from the command-line...\n\n<p align="center">\n <img width="700" src="https://raw.githubusercontent.com/encode/httpx/master/docs/img/httpx-help.png" alt=\'httpx --help\'>\n</p>\n\nSending a request...\n\n<p align="center">\n <img width="700" src="https://raw.githubusercontent.com/encode/httpx/master/docs/img/httpx-request.png" alt=\'httpx http://httpbin.org/json\'>\n</p>\n\n## Features\n\nHTTPX builds on the well-established usability of `requests`, and gives you:\n\n* A broadly [requests-compatible API](https://www.python-httpx.org/compatibility/).\n* An integrated command-line client.\n* HTTP/1.1 [and HTTP/2 support](https://www.python-httpx.org/http2/).\n* Standard synchronous interface,',
'metadata': {'name': 'httpx',
'version': '0.28.1',
'keywords': '',
'requires': 'certifi anyio pygments idna brotlicffi h2 httpcore socksio rich click brotli zstandard',
'summary': 'The next generation HTTP client.',
'url': 'https://github.com/encode/httpx'}}u = pkg_url('httpx')
assert u and u.startswith('http'), f'expected a URL, got {u!r}'
print('pkg_url httpx:', u)
assert pkg_url('fastcore') is not None, 'fastcore should have a URL'
print('pkg_url fastcore:', pkg_url('fastcore'))pkg_url httpx: https://github.com/encode/httpx
pkg_url fastcore: https://github.com/AnswerDotAI/fastcore/imp_root
def imp_root(
p:Path
)->Path:Import root of p: the nearest ancestor directory without init.py.
has_init
def has_init(
d:Path
)->bool:True if dir is a Python package root: has init.py or a C-extension init.so.*
enrich_chunks
def enrich_chunks(
content:L
)->L:Set public_api+docstring flags on non-assign chunks and explode ClassDefs into method sub-chunks.
count_imp
def count_imp(
files, own:str=''
)->Counter:*External top-level imports from a source-string iterable. Reuses cached _parse.*
Kosha.process_env
def process_env(
content:NoneType=None, reembed:bool=False, embed:bool=True, emb_fn:NoneType=None,
hash_id_columns:tuple=('content',), parallel:bool=False, chunk:int=5000
):Embed all documents in the env store, or only those without embeddings if reembed=False.
Kosha.nuke
def nuke(
env:bool=False
):Reset the databases by dropping all tables.
Kosha.update_pkgs
def update_pkgs(
pkgs:str | list=None, # packages to sync; None syncs all installed env packages
embed:bool=True, # embed chunks after indexing
exts:str='.py,.js,.ts,.jsx,.tsx,.java,.go,.cs,.ruby,.php,.swift,.kt,.kts,.rs,.scala,.lua', # file extensions to include
verbose:bool=True, # print progress
force:bool=False, # reindex even if package version already loaded
parallel:bool=False, # ingest packages concurrently; requires Kosha(busy_timeout=...)
n_workers:NoneType=None, # threads when parallel=True; fastcore's default if None
chunk:int=5000, # rows per write transaction when parallel=True
**kwargs
):Sync installed packages into the env store; if pkgs is None, syncs all env packages.
Kosha.rm_pkg
def rm_pkg(
pkg:str, ver:str=None
):Remove a package and its code snippets from the database.
Kosha.update_pkg
def update_pkg(
pkg:str, embed:bool=True,
exts:str='.py,.js,.ts,.jsx,.tsx,.java,.go,.cs,.ruby,.php,.swift,.kt,.kts,.rs,.scala,.lua', verbose:bool=True,
force:bool=False, imports:bool=False, parallel:bool=False, chunk:int=5000, n_workers:int=None,
threadpool:bool=False
):Update package metadata in the packages table.
# update_pkgs(parallel=True) refuses without a busy timeout. Concurrent database() opens would hit
# apsw's 100ms default and raise SQLITE_BUSY inside the open hook, dropping whole packages with no
# exception reaching the caller -- a silently incomplete index is worse than a loud failure.
import tempfile
from pathlib import Path
_gt = tempfile.mkdtemp(); _gk = Kosha(dir=_gt, xdg_dir=Path(_gt))
assert _gk.busy_timeout is None
try:
_gk.update_pkgs(['certifi'], parallel=True, embed=False, verbose=False)
assert False, 'parallel=True without busy_timeout must raise'
except ValueError as e: assert 'busy timeout' in str(e)
_gk.update_pkgs(['certifi'], parallel=False, embed=False, verbose=False) # serial path is unguarded
assert len(_gk.env_st()) > 0
# with a timeout set, threaded ingestion must land exactly what the serial path does
_pk = ['certifi', 'idna', 'fastlite']
_ta, _tb = tempfile.mkdtemp(), tempfile.mkdtemp()
_ka = Kosha(dir=_ta, xdg_dir=Path(_ta), busy_timeout=30_000)
_kb = Kosha(dir=_tb, xdg_dir=Path(_tb), busy_timeout=30_000)
_ka.update_pkgs(_pk, parallel=True, embed=False, verbose=False)
_kb.update_pkgs(_pk, parallel=False, embed=False, verbose=False)
assert {r['name'] for r in _ka.pkgs(select='name')} == set(_pk), 'parallel lost a package'
assert len(_ka.env_st()) == len(_kb.env_st()), 'parallel dropped rows vs serial'█
|----------------------------------------| 0.00% [0/3 00:00<?]
|█████████████---------------------------| 33.33% [1/3 00:00<00:00]
|██████████████████████████--------------| 66.67% [2/3 00:00<00:00]
|████████████████████████████████████████| 100.00% [3/3 00:00<00:00]
Fetching 6 files: 0%| | 0/6 [00:00<?, ?it/s]Warning: You are sending unauthenticated requests to the HF Hub. Please set a HF_TOKEN to enable higher rate limits and faster downloads.
Fetching 6 files: 17%|#6 | 1/6 [00:00<00:00, 8.99it/s]
Fetching 6 files: 100%|##########| 6/6 [00:01<00:00, 3.39it/s]
Fetching 6 files: 100%|##########| 6/6 [00:01<00:00, 3.50it/s]
Updating packages: 0%| | 0/1 [00:00<?, ?pkg/s]
parse files from certifi: 0%| | 0/3 [00:00<?, ?it/s]
parse files from certifi: 100%|##########| 3/3 [00:00<00:00, 2609.48it/s]
Updating packages: 100%|##########| 1/1 [00:00<00:00, 14.28pkg/s]
parse files from fastlite: 0%| | 0/4 [00:00<?, ?it/s]
parse files from fastlite: 100%|##########| 4/4 [00:00<00:00, 383.51it/s]
parse files from idna: 0%| | 0/10 [00:00<?, ?it/s]
parse files from certifi: 0%| | 0/3 [00:00<?, ?it/s]
parse files from certifi: 100%|##########| 3/3 [00:00<00:00, 262.99it/s]
parse files from idna: 100%|##########| 10/10 [00:00<00:00, 112.87it/s]
Updating packages: 0%| | 0/3 [00:00<?, ?pkg/s]
parse files from certifi: 0%| | 0/3 [00:00<?, ?it/s]
parse files from certifi: 100%|##########| 3/3 [00:00<00:00, 2766.69it/s]
parse files from idna: 0%| | 0/10 [00:00<?, ?it/s]
parse files from idna: 100%|##########| 10/10 [00:00<00:00, 147.40it/s]
Updating packages: 67%|######6 | 2/3 [00:00<00:00, 13.66pkg/s]
parse files from fastlite: 0%| | 0/4 [00:00<?, ?it/s]
parse files from fastlite: 100%|##########| 4/4 [00:00<00:00, 297.56it/s]
Updating packages: 100%|##########| 3/3 [00:00<00:00, 12.30pkg/s]Kosha.update_repo
def update_repo(
dir:Path=None, # directory to index; defaults to repo root
embed:bool=True, # embed chunks after parsing
exts:str='.py,.js,.ts,.jsx,.tsx,.java,.go,.cs,.ruby,.php,.swift,.kt,.kts,.rs,.scala,.lua',
verbose:bool=True, # verbose
force:bool=False, # reindex all files regardless of mtime
skip_file_re:str='^[.]|^(?:setup\\.py|conftest\\.py)$',
skip_folder_re:str='^[.]|^(?:tests?|examples?|docs?|build|dist|_proc|_docs|_site|_site_libs|node_modules|__pycache__)$',
func:type=Path, path:pathlib.Path | str='.', recursive:bool=True, maxdepth:int=None, symlinks:bool=True,
file_glob:str=None, file_re:str=None, folder_re:str=None, skip_file_glob:str=None, ret_folders:bool=False,
sort:bool=True, types:str | list=None
):Index or update repo code chunks. Pass files= for incremental update (e.g. from watcher).
Kosha.process_repo
def process_repo(
content:NoneType=None, reembed:bool=False, embed:bool=True, emb_fn:NoneType=None,
hash_id_columns:tuple=('content',), parallel:bool=False, chunk:int=5000
):Embed all documents in the code store, or only those without embeddings if reembed=False.
Kosha.pkgs_in_env
def pkgs_in_env(
pyproject:bool=False, depth:int=1
)->list:Intersection of the packages table with packages installed in the environment.
Kosha.prune_old_pkgs
def prune_old_pkgs():Keep only the latest version of each package in the database.
Kosha.prune_old_versions
def prune_old_versions(
pkg:str
):Keep only the latest version of a package in the database.
import kosha.core as _kc, inspect_f = Path(inspect.getfile(_kc))
_anchor = _f.parent
while has_init(_anchor): _anchor = _anchor.parent
_mod = '.'.join(_f.relative_to(_anchor).with_suffix('').parts)
assert _mod == 'kosha.core', f'expected kosha.core, got {_mod}'
print('mod_name anchor fix: ok —', _mod)mod_name anchor fix: ok — kosha.coredir2files(repo_root(), None, skip_folder_re,exts=code_exts)[Path('/Users/71293/code/personal/orgs/kosha/kosha/__init__.py'), Path('/Users/71293/code/personal/orgs/kosha/kosha/_modidx.py'), Path('/Users/71293/code/personal/orgs/kosha/kosha/cli.py'), Path('/Users/71293/code/personal/orgs/kosha/kosha/core.py'), Path('/Users/71293/code/personal/orgs/kosha/kosha/graph.py'), Path('/Users/71293/code/personal/orgs/kosha/kosha/mcp.py')]dir2files(repo_root(), strict_skip_file_re, skip_folder_re,exts=code_exts)[Path('/Users/71293/code/personal/orgs/kosha/kosha/cli.py'), Path('/Users/71293/code/personal/orgs/kosha/kosha/core.py'), Path('/Users/71293/code/personal/orgs/kosha/kosha/graph.py'), Path('/Users/71293/code/personal/orgs/kosha/kosha/mcp.py')]pkg='fastcore'
k._is_pkg_ingested(pkg){'name': 'fastcore', 'version': '2.1.17'}k.env_st(select='content, embedding, json_extract(metadata, "$.mod_name","$.docstring", "$.public_api") as pa',
where='package="httpx" and json_extract(metadata, "$.public_api")=1', limit=1)[{'content': 'def close(self) -> None:\n pass',
'embedding': b'\xd90\xd0%c\xac\xd8-\x91(\xac\x17\xee\x1f \xa9\x87\xa6N\x1a\xc5,\x11(\xec)o)-$k*\xf1\xa8^\xa6p\xa9\xa1\xa1\x0e\xa5\xe5\xa0\xa4+\'*\xe9(h\xa2\x90,\xe8\x9d\x80\xa3\x16\x91X\'5/\x82\x1bC&\x99\xa5\xf7\xa6\xc5\x17\xa9"="\xf2\xaa~(\n\xa4\xf8%\x9e\xa8\xa5\xa8\xd8/\xb9\xa9\xd7+@\xb1\xf2\xa7\xfe-\xa9\xa9g#\x85\xae\x91\xad\xb3\x1c\xf9\xb1\x18.\x06 9\xaa\x10/l%F\x1d\x9c*\xac\xac\x98)\xaf+\x00\xa6G,\x80\xac\xe7/\xfb\x1cI\xa7\xf4\xacu+\xd9\xac\xfc\xa1\xd3\xa8\xf4(U\x94\xd0,\x88\xac0\xac\xdd\xb0y-\xf7*N\xa6\xb6\x116,(&\xfa+u\xa4Y\xadY&\x14+&\xa8\x8e.B0Q)\x9f*B(\x95\xac\xfa(>%\xf7\xa40\xa4\xae$\x99.G\xab\x1f+\xba\xabE*\x18\xa7\xd9\xa8\x10)}\xadS\xa4J\x1f@/\xfb\xae\xd2\xae\xe5&\xd9*\x831y\'\xea\xa1\xb3\xa7E\xae\x9f\xa6\xcb,\xde\xa7Y%=\xa4\xbc\xaa\xb0\x99\xb6\xab\xc4-O&J\xa8\xe5.O.\xd1)\xcb\xa0\x83,\x04\x9a\x87\xad\xf1\'m)\xb7-,\xaaE)\x9d$\xf3)\xed\xa3\x9a)\x7f&\x1e-Q)\x97#\x88+x\xaa\xe3\xa2\xd7"n\'.0\xeb\x18\x10\xabN+\x9d+\x03!\x82\xaa\xc6\x94\xb4&/\xa9\xd7\x9b\x81\xac\xb0%_\'H\xa5\x85\'\x92-\xfc)\\\xb3\xb0(4\xad\xbb\xaa\xf9\x99/\xa9\xdd \xbc\xa0\xa8(\x17\xa4H\xaa\x8b\xadv(\x8f\xaft%3\xaf\xe3\x99-\'Z\xac],\xa6\xa4\xc0\x9d\xad.\xda\xa8 $\xfe(#.G+\x1d\xac\xf7\xaa\xa4-\xf314\xa8w\xaeJ\xad\xb2&\x0c-`\xaa\xc5\x9d\xda\x1e\xd7\x1f\x17\xa0\xb8,|-\xbc\xaa\xc0%M\x9f\x97/\xaf\xadb(\x19,\xc3.+.r,9.p(\x0e&\x0c,\x06)!\xa8B _\xab\xe6\xa8K*\x1a\x18\x89(\x0c#[&\xc5\xafJ,\x13\xa4h&\xc6*\x85\xaa',
'pa': '["httpx._transports.base.BaseTransport.close",null,true]'}]k.pkgs(order_by='name', limit=1)[{'name': 'FlashRank',
'version': '0.2.10',
'summary': 'Ultra lite & Super fast SoTA cross-encoder based re-ranking for your search & retrieval pipelines.',
'uploaded_at': '2026-08-03 02:24:34'}]k.update_pkg('protobuf')updating pkg: protobuf ...
package {'name': 'protobuf', 'version': '7.35.1'} already loaded.k.update_pkg('fastlite', force=True)updating pkg: fastlite ...
package {'name': 'fastlite', 'version': '0.2.4'} already loaded.
forcing an update to pkg {'name': 'fastlite', 'version': '0.2.4'}
parse files from fastlite: 0%| | 0/4 [00:00<?, ?it/s]
parse files from fastlite: 100%|██████████████████████████████████████████████████████████████████████████████████████████| 4/4 [00:00<00:00, 261.68it/s]{'changed': 64, 'same': 0, 'removed': 0}{}k.update_repo(skip_file_glob='*.ipynb', force=True)syncing files [Path('/Users/71293/code/personal/orgs/kosha/kosha/cli.py'), Path('/Users/71293/code/personal/orgs/kosha/kosha/core.py'), Path('/Users/71293/code/personal/orgs/kosha/kosha/graph.py'), Path('/Users/71293/code/personal/orgs/kosha/kosha/mcp.py')] .....
parse files from /Users/71293/code/personal/orgs/kosha: 0%| | 0/4 [00:00<?, ?it/s]
parse files from /Users/71293/code/personal/orgs/kosha: 75%|██████████████████████████████████████████████▌ | 3/4 [00:00<00:00, 28.69it/s]
parse files from /Users/71293/code/personal/orgs/kosha: 100%|██████████████████████████████████████████████████████████████| 4/4 [00:00<00:00, 36.64it/s]{'changed': 163, 'same': 0, 'removed': 0}
synced repok.code_st(select='json_extract(metadata, "$.mod_name","$.docstring", "$.public_api") as pa',
where='json_extract(metadata, "$.public_api")=1')k.code_st(select='content',where='json_extract(metadata, "$.mod_name")="kosha.core.Kosha.__init__"')[{'content': "def __init__(self, dir: Path = None, install_skill: bool = False, xdg_dir: Path = None, efn=static_code_embedder):\n\t\tself.root, self.xdg, self.efn = Path(dir or repo_root() or '.'), xdg_dir or xdg_data_home(), efn()\n\t\tself.emb_doc, self.emb_query = doc_encoder(self.efn), query_encoder(self.efn)\n\t\tif install_skill: mv_skill_md(dir=self.root, dry_run=False)\n\t\tself.cp, self.ce = self.root.joinpath('.kosha','code.db'), self.xdg.joinpath('kosha','env.db')\n\t\tfor p in (self.cp, self.ce): p.parent.mkdir(parents=True, exist_ok=True)\n\t\tself.codedb, self.envdb, kw = database(self.cp), database(self.ce), dict(hash=True,ann=True)\n\t\tself.code_st,self.env_st = self.codedb.get_store(path=str,**kw),self.envdb.get_store(package=str,**kw)\n\t\tself.pkg_st, self.pkgs = self.envdb.get_store('pkg_store', **kw), self.envdb.t.packages\n\t\tself.env_pd, self.code_rd = self.envdb.t.pkg_deps, self.codedb.t.repo_deps\n\t\tself.pkgs.create(name=str, version=str, summary=str, uploaded_at=float, pk=['name','version'],\n\t\t\t defaults=dict(uploaded_at='CURRENT_TIMESTAMP'), if_not_exists=True)\n\t\tself.env_pd.create(from_pkg=str, to_pkg=str, n_modules=int, if_not_exists=True, pk=['from_pkg','to_pkg'])\n\t\tself.code_rd.create(from_module=str, to_pkg=str, n_files=int, if_not_exists=True, pk=['from_module','to_pkg'])"}]k.update_pkgs(set(env_pkg_versions()))loading pkgs {'notebook', 'usearch', 'codesigs', 'model2vec', 'anyio', 'ddgs', 'scrapling', 'execnb', 'Jinja2', 'nbdev', 'watchfiles', 'onnxruntime', 'setuptools', 'mcp', 'FlashRank', 'ghapi', 'pdf_oxide', 'tornado', 'litesearch', 'jupyter_builder', 'fossick', 'pillow', 'html2text', 'spacy', 'fastlite', 'jupyterlab', 'pyskills', 'pandas', 'diskcache', 'onnx', 'PyYAML', 'yake', 'yt-dlp', 'tokenizers', 'notebook_shim', 'fastprogress', 'curl_cffi', 'fastgit', 'fastcdp', 'jupyter_server', 'build', 'astunparse', 'readability-lxml', 'chonkie', 'fastcore', 'pyan3', 'jupyterlab_server', 'python-fasthtml', 'fastaudit', 'liteparse', 'asttokens', 'watchdog'} ...
Updating packages: 0%| | 0/52 [00:00<?, ?pkg/s]
Updating packages: 4%|███▋ | 2/52 [00:00<00:03, 14.11pkg/s]updating pkg: notebook ...
package {'name': 'notebook', 'version': '7.6.1'} already loaded.
updating pkg: usearch ...
package {'name': 'usearch', 'version': '2.26.0'} already loaded.
updating pkg: codesigs ...
Updating packages: 8%|███████▍ | 4/52 [00:00<00:03, 13.57pkg/s]
Updating packages: 12%|███████████▏ | 6/52 [00:00<00:03, 14.48pkg/s]package {'name': 'codesigs', 'version': '0.0.3'} already loaded.
updating pkg: model2vec ...
package {'name': 'model2vec', 'version': '0.8.2'} already loaded.
updating pkg: anyio ...
package {'name': 'anyio', 'version': '4.14.2'} already loaded.
updating pkg: ddgs ...
package {'name': 'ddgs', 'version': '9.14.4'} already loaded.
updating pkg: scrapling ...
Updating packages: 15%|██████████████▉ | 8/52 [00:00<00:02, 15.25pkg/s]
Updating packages: 19%|██████████████████▍ | 10/52 [00:00<00:02, 15.77pkg/s]package {'name': 'scrapling', 'version': '0.4.12'} already loaded.
updating pkg: execnb ...
package {'name': 'execnb', 'version': '0.2.9'} already loaded.
updating pkg: Jinja2 ...
package {'name': 'Jinja2', 'version': '3.1.6'} already loaded.
updating pkg: nbdev ...
package {'name': 'nbdev', 'version': '3.3.3'} already loaded.
updating pkg: watchfiles ...
Updating packages: 23%|██████████████████████▏ | 12/52 [00:00<00:02, 16.35pkg/s]
Updating packages: 27%|█████████████████████████▊ | 14/52 [00:00<00:02, 16.40pkg/s]package {'name': 'watchfiles', 'version': '1.2.0'} already loaded.
updating pkg: onnxruntime ...
package {'name': 'onnxruntime', 'version': '1.28.0'} already loaded.
updating pkg: setuptools ...
package {'name': 'setuptools', 'version': '83.0.0'} already loaded.
updating pkg: mcp ...
package {'name': 'mcp', 'version': '2.0.0'} already loaded.
updating pkg: FlashRank ...
Updating packages: 31%|█████████████████████████████▌ | 16/52 [00:00<00:02, 17.29pkg/s]
Updating packages: 35%|█████████████████████████████████▏ | 18/52 [00:01<00:01, 17.82pkg/s]package {'name': 'FlashRank', 'version': '0.2.10'} already loaded.
updating pkg: ghapi ...
package {'name': 'ghapi', 'version': '2.0.5'} already loaded.
updating pkg: pdf_oxide ...
package {'name': 'pdf_oxide', 'version': '0.3.77'} already loaded.
updating pkg: tornado ...
package {'name': 'tornado', 'version': '6.5.7'} already loaded.
updating pkg: litesearch ...
Updating packages: 38%|████████████████████████████████████▉ | 20/52 [00:01<00:01, 18.13pkg/s]
Updating packages: 42%|████████████████████████████████████████▌ | 22/52 [00:01<00:01, 18.37pkg/s]package {'name': 'litesearch', 'version': '0.1.5'} already loaded.
updating pkg: jupyter_builder ...
package {'name': 'jupyter_builder', 'version': '1.2.1'} already loaded.
updating pkg: fossick ...
package {'name': 'fossick', 'version': '0.0.15'} already loaded.
updating pkg: pillow ...
package {'name': 'pillow', 'version': '12.3.0'} already loaded.
updating pkg: html2text ...
Updating packages: 46%|████████████████████████████████████████████▎ | 24/52 [00:01<00:01, 18.40pkg/s]
Updating packages: 50%|████████████████████████████████████████████████ | 26/52 [00:01<00:01, 17.92pkg/s]package {'name': 'html2text', 'version': '2025.4.15'} already loaded.
updating pkg: spacy ...
package {'name': 'spacy', 'version': '3.8.14'} already loaded.
updating pkg: fastlite ...
package {'name': 'fastlite', 'version': '0.2.4'} already loaded.
updating pkg: jupyterlab ...
package {'name': 'jupyterlab', 'version': '4.6.2'} already loaded.
updating pkg: pyskills ...
Updating packages: 54%|███████████████████████████████████████████████████▋ | 28/52 [00:01<00:01, 17.30pkg/s]
Updating packages: 58%|███████████████████████████████████████████████████████▍ | 30/52 [00:01<00:01, 17.75pkg/s]package {'name': 'pyskills', 'version': '0.0.27'} already loaded.
updating pkg: pandas ...
package {'name': 'pandas', 'version': '3.0.5'} already loaded.
updating pkg: diskcache ...
package {'name': 'diskcache', 'version': '5.6.3'} already loaded.
updating pkg: onnx ...
package {'name': 'onnx', 'version': '1.22.0'} already loaded.
updating pkg: PyYAML ...
parse files from PyYAML: 0%| | 0/1 [00:00<?, ?it/s]
parse files from PyYAML: 100%|████████████████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 803.81it/s]
Updating packages: 62%|███████████████████████████████████████████████████████████ | 32/52 [00:01<00:01, 14.82pkg/s]
Updating packages: 65%|██████████████████████████████████████████████████████████████▊ | 34/52 [00:02<00:01, 15.39pkg/s]{'changed': 0, 'same': 0, 'removed': 0}
updating pkg: yake ...
package {'name': 'yake', 'version': '0.7.3'} already loaded.
updating pkg: yt-dlp ...
package {'name': 'yt-dlp', 'version': '2026.7.4'} already loaded.
updating pkg: tokenizers ...
package {'name': 'tokenizers', 'version': '0.23.1'} already loaded.
updating pkg: notebook_shim ...
Updating packages: 69%|██████████████████████████████████████████████████████████████████▍ | 36/52 [00:02<00:00, 16.44pkg/s]package {'name': 'notebook_shim', 'version': '0.2.4'} already loaded.
updating pkg: fastprogress ...
package {'name': 'fastprogress', 'version': '1.1.6'} already loaded.
updating pkg: curl_cffi ...
package {'name': 'curl_cffi', 'version': '0.16.0'} already loaded.
updating pkg: fastgit ...
package {'name': 'fastgit', 'version': '0.1.1'} already loaded.
updating pkg: fastcdp ...
package {'name': 'fastcdp', 'version': '0.0.7'} already loaded.
Updating packages: 75%|████████████████████████████████████████████████████████████████████████ | 39/52 [00:02<00:00, 17.66pkg/s]
Updating packages: 81%|█████████████████████████████████████████████████████████████████████████████▌ | 42/52 [00:02<00:00, 18.41pkg/s]updating pkg: jupyter_server ...
package {'name': 'jupyter_server', 'version': '2.20.0'} already loaded.
updating pkg: build ...
package {'name': 'build', 'version': '1.5.0'} already loaded.
updating pkg: astunparse ...
package {'name': 'astunparse', 'version': '1.6.3'} already loaded.
updating pkg: readability-lxml ...
Updating packages: 85%|█████████████████████████████████████████████████████████████████████████████████▏ | 44/52 [00:02<00:00, 18.58pkg/s]
Updating packages: 88%|████████████████████████████████████████████████████████████████████████████████████▉ | 46/52 [00:02<00:00, 18.63pkg/s]package {'name': 'readability-lxml', 'version': '0.8.4.1'} already loaded.
updating pkg: chonkie ...
package {'name': 'chonkie', 'version': '1.7.0'} already loaded.
updating pkg: fastcore ...
package {'name': 'fastcore', 'version': '2.1.17'} already loaded.
updating pkg: pyan3 ...
package {'name': 'pyan3', 'version': '2.6.2'} already loaded.
updating pkg: jupyterlab_server ...
Updating packages: 92%|████████████████████████████████████████████████████████████████████████████████████████▌ | 48/52 [00:02<00:00, 18.92pkg/s]
Updating packages: 96%|████████████████████████████████████████████████████████████████████████████████████████████▎ | 50/52 [00:02<00:00, 19.06pkg/s]package {'name': 'jupyterlab_server', 'version': '2.28.0'} already loaded.
updating pkg: python-fasthtml ...
package {'name': 'python-fasthtml', 'version': '0.14.11'} already loaded.
updating pkg: fastaudit ...
package {'name': 'fastaudit', 'version': '0.2.7'} already loaded.
updating pkg: liteparse ...
package {'name': 'liteparse', 'version': '2.11.0'} already loaded.
updating pkg: asttokens ...
Updating packages: 100%|████████████████████████████████████████████████████████████████████████████████████████████████| 52/52 [00:02<00:00, 19.16pkg/s]
Updating packages: 100%|████████████████████████████████████████████████████████████████████████████████████████████████| 52/52 [00:02<00:00, 17.35pkg/s]package {'name': 'asttokens', 'version': '3.0.2'} already loaded.
updating pkg: watchdog ...
package {'name': 'watchdog', 'version': '6.0.0'} already loaded.k.env_st(where='embedding is NULL', select='count(*)')[{'count(*)': 0}]k.process_env()k.update_pkgs(['fastcore','litesearch','fastlite','apsw','ghapi','httpx'])loading pkgs ['fastcore', 'litesearch', 'fastlite', 'apsw', 'ghapi', 'httpx'] ...
Updating packages: 0%| | 0/6 [00:00<?, ?pkg/s]
Updating packages: 33%|████████████████████████████████▋ | 2/6 [00:00<00:00, 17.10pkg/s]updating pkg: litesearch ...
package {'name': 'litesearch', 'version': '0.1.5'} already loaded.
updating pkg: fastcore ...
package {'name': 'fastcore', 'version': '2.1.17'} already loaded.
updating pkg: apsw ...
package {'name': 'apsw', 'version': '3.53.4.0'} already loaded.
updating pkg: fastlite ...
Updating packages: 67%|█████████████████████████████████████████████████████████████████▎ | 4/6 [00:00<00:00, 18.56pkg/s]
Updating packages: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████| 6/6 [00:00<00:00, 18.58pkg/s]
Updating packages: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████| 6/6 [00:00<00:00, 18.39pkg/s]package {'name': 'fastlite', 'version': '0.2.4'} already loaded.
updating pkg: httpx ...
package {'name': 'httpx', 'version': '0.28.1'} already loaded.
updating pkg: ghapi ...
package {'name': 'ghapi', 'version': '2.0.5'} already loaded.Structured Search
parseqstripskey:valuefilter tokens from a query string.filt2whmaps them to SQL WHERE clauses.Kosha.contextfans out searches across detected packages and merges results with chained RRF.
parseq
def parseq(
q:str
)->tuple:Parse key:value filter tokens from a query. Returns (bare_query, filters).
Keys are file/path/package/lang/type, plus plurals and the short forms people reach for first (pkg, dir, ext, …); a trailing ! is accepted and means the same thing, since every filter is already a hard SQL predicate. A filter-shaped token whose key is none of these lands under _unknown rather than vanishing into the query text: pkg:x used to leave the whole index unfiltered and search for the literal string, which reads as a plausible answer to a question that was never asked.
# aliases and the `!` suffix resolve to the canonical key
for tok in ['package:litesearch', 'pkg:litesearch', 'pkgs:litesearch', 'package!:litesearch', 'pkg!:litesearch']:
raw, fs = parseq(f'how do I add indexes with {tok}')
assert fs['package'] == ['litesearch'], (tok, dict(fs))
assert raw == 'how do I add indexes with', (tok, raw)
assert parseq('atomic save dir:xtras')[1]['path'] == ['xtras']
assert parseq('atomic save ext:py')[1]['lang'] == ['py']
assert parseq('search package:httpx,requests')[1]['package'] == ['httpx', 'requests']
# an unknown filter key is reported, not silently searched as text
assert parseq('add indexes with libr:litesearch')[1]['_unknown'] == ['libr']
assert parseq('add indexes with module:foo')[1]['_unknown'] == ['module']
# ...and known keys, urls and bare prose never trip it
for q in ['add indexes with package:litesearch', 'see https://example.com/x', 'how do I add indexes']:
assert '_unknown' not in parseq(q)[1], qparseq('how do I merge dicts package:fastcore path:data*')('how do I merge dicts',
defaultdict(list, {'package': ['fastcore'], 'path': ['data*']}))assert parseq('stripe payments package:fasthtml file:routes*') == ('stripe payments', {'package': ['fasthtml'], 'file': ['routes*']})
assert parseq('package:monsterui package:fasthtml create a table') == ('create a table', {'package': ['monsterui', 'fasthtml']})
assert parseq('no filters here') == ('no filters here', {})
assert parseq('type:FunctionDef lang:py') == ('type:FunctionDef lang:py', {'type': ['FunctionDef'], 'lang': ['py']})
assert parseq('package:only')[0] == 'package:only'
# plural forms + comma-separated values
assert parseq('merge dicts packages:fastcore,litesearch') == ('merge dicts', {'package': ['fastcore', 'litesearch']})
assert parseq('search paths:basics,core,data') == ('search', {'path': ['basics', 'core', 'data']})
assert parseq('query packages:fastcore,litesearch paths:basics,core') == ('query', {'package': ['fastcore', 'litesearch'], 'path': ['basics', 'core']})
assert parseq('langs:py,js files:routes*,api*') == ('langs:py,js files:routes*,api*', {'lang': ['py', 'js'], 'file': ['routes*', 'api*']})
print('parse_query: all assertions pass')parse_query: all assertions passfrom litesearch import pre, cleanassert clean('with_uv') == 'with_uv'filt2wh
def filt2wh(
filters:dict, store:str='code'
)->str | None:Convert a filter dict (from parse_query) to a SQL WHERE clause for the given store (code or env).
filt2wh(parseq('how do I merge dicts package:fastcore path:data*')[1], 'env')"(json_extract(metadata, '$.path') like '%data%') AND (package='fastcore')"filt2wh({'type': ['FunctionDef']}, 'code')"(json_extract(metadata, '$.type') = 'FunctionDef')"assert filt2wh({'file': ['routes*']}, 'code') == "(path LIKE '%routes%')"
assert filt2wh({'path': ['api/*']}, 'code') == "(path LIKE '%api/%')"
assert filt2wh({'lang': ['py']}, 'code') == "(json_extract(metadata, '$.lang') = '.py')"
assert filt2wh({'lang': ['python']}, 'code') == "(json_extract(metadata, '$.lang') = '.py')"
assert filt2wh({'package': ['fasthtml']}, 'env') == "(package='fasthtml')"
assert filt2wh({'type': ['FunctionDef']}, 'code') == "(json_extract(metadata, '$.type') = 'FunctionDef')"
assert filt2wh({}, 'code') is None
assert filt2wh({}, 'env') is None
assert filt2wh({'package': ['fasthtml']}, 'code') is None
print('filters_to_where: all assertions pass')filters_to_where: all assertions passKosha.pkgs2consider
def pkgs2consider(
sys_wide:bool=True
)->set:Determine which packages to consider for search intersecting packages table and the environment.
Kosha.env_context
def env_context(
q:str, # query to search (supports key:value filters)
emb_q:str=None, # query to embed; defaults to bare query after filter parsing
wide:bool=False, # whether to use wide search
columns:str='content,metadata,package', # comma separated columns string to return from search
where:str=None, # additional where clause to filter search results
ann:bool=True, # HNSW Approximate Nearest Neighbors (ann) search; defaults to True
rerank:bool=False, # reorder the merged hits with a flashrank cross-encoder
rerank_model:str=None, # flashrank model name (None -> fast default)
**kw
)->L: # additional args to pass to db.searchCode search over the env store, with optional key:value filters (e.g. package:fasthtml).
fanout
def fanout(
kw, limit, rerank
):Widen the retrieval limit when reranking, so the cross-encoder has candidates to reorder.
Kosha.watch_repo
def watch_repo(
dir:Path=None, **kw
):Block and watch repo for changes, re-indexing incrementally. Ctrl-C to stop.
Kosha.awatch_repo
async def awatch_repo(
dir:Path=None, **kw
):Async watcher: re-indexes changed files on every watchfiles event.
Kosha.repo_context
def repo_context(
q:str, # query to search (supports key:value filters)
emb_q:str=None, # query to embed; defaults to bare query after filter parsing
wide:bool=False, # use wide (OR) FTS search
columns:str='content,path,metadata', # columns to return
where:str=None, # extra SQL filter
ann:bool=True, # HNSW Approximate Nearest Neighbors (ann) search; defaults to True
rerank:bool=False, # reorder the merged hits with a flashrank cross-encoder
rerank_model:str=None, # flashrank model name (None -> fast default)
**kw
)->L: # additional args to pass to db.searchSemantic + keyword search through indexed repo code.
Kosha.pkg_context
def pkg_context(
q:str, # the search query
limit:int=10, # limits
rerank:bool=False, # reorder the merged hits with a flashrank cross-encoder
rerank_model:str=None, # flashrank model name (None -> fast default)
)->L:FTS5+vector search over package descriptions in pkg_store.
# `cast_emb` pins the stored dtype to what `Database.search` reads back (float16), so a
# custom `efn` emitting float32 can no longer corrupt the vector leg silently.
emb = k.emb_doc(['def f(): pass'])
qry = k.emb_query('a function')
assert emb.dtype == DTYPE == np.float16, emb.dtype
assert qry.dtype == DTYPE, qry.dtype
f32 = cast_emb(lambda txts, **kw: np.zeros((len(txts), 4), dtype=np.float32))
assert f32(['a','b']).dtype == DTYPE# rerank fans out to RERANK_FANOUT candidates, then the cross-encoder cuts back to `limit`.
assert fanout({}, 5, True)['limit'] == RERANK_FANOUT
assert fanout({}, 50, True)['limit'] == 50
assert fanout({}, 5, False)['limit'] == 5
# the live leg needs flashrank's model on disk; skip rather than fail on a cold/offline machine.
try: rr = k.env_context('atomic file write', limit=5, rerank=True)
except Exception as e: print('rerank skipped:', type(e).__name__)
else:
assert len(rr) <= 5
wide = k.env_context('atomic file write', limit=RERANK_FANOUT)
assert {r['content'] for r in rr} <= {r['content'] for r in wide}, 'reranked hits must come from the fanout'
print(rr.attrgot('metadata').attrgot('mod_name'))Docs index
The code stores hold AST chunks; long-form prose (READMEs, docs/ trees) wants sections, not chunks. litesearch.api.Index already carries that tree layer — toc, sections, read, context — so we mount one as a third, lazily-created store rather than reimplementing it. It shares the code embedder to avoid loading a second model; pass encoder= a text embedder (e.g. static_embedder()) if prose recall matters more than the shared-model saving.
Kosha.docs_context
def docs_context(
q:str, # the search query
limit:int=5, # hits to return
sections:bool=True, # ranked sections (with `read` handles) vs raw chunks
**kw
)->L: # forwarded to Index.sections / Index.searchSearch the docs index; sections reassemble whole passages instead of fragments.
Kosha.add_pkg_docs
def add_pkg_docs(
pkg:str
)->int:Ingest a package README in full — pkg_store keeps only a 2k-char blurb.
Kosha.add_docs
def add_docs(
src, # a docs directory, a file, or {title: text}
**kw
)->int: # forwarded to Index.addIngest long-form docs. Returns the number of chunks gained.
Kosha.docs
def docs()->Index:Lazy tree-aware Index over long-form docs — READMEs and docs/ trees, not AST chunks.
from tempfile import TemporaryDirectory
with TemporaryDirectory() as td:
_dk = Kosha(dir=Path(td), xdg_dir=Path(td))
n = _dk.add_docs({'install': '# Install\n\nRun `uv add kosha` to install kosha into your project.',
'search': '# Search\n\nCall `env_context` to search installed packages by meaning.'})
assert n > 0, 'docs index ingested nothing'
assert len(_dk.docs) == n
hits = _dk.docs_context('how do I install this', sections=False)
assert hits, 'no docs hits'
assert 'uv add kosha' in hits[0]['content']
secs = _dk.docs_context('search installed packages')
assert secs and _dk.docs.read(secs[0]['node_id'])['text']
print(repr(_dk.docs))Index(path='/tmp/tmppwphfsx7/kosha/docs.db', chunks=2, docs=2)k.env_context('payment page with fasthtml package:python-fasthtml', limit=10)[{'rowid': 35281, 'content': 'def account_management(sess):\n user_email = sess[\'auth\']\n user_payments = payments("email=?", (user_email,))\n # Create table rows for each payment\n payment_rows = []\n for payment in user_payments:\n action_button = ""\n if payment.payment_status == \'paid\':\n action_button = Button("Request Refund", hx_post=f"/refund?checkout_sid={payment.checkout_session_id}",hx_target="#refund-status")\n elif payment.payment_status == \'refunded\': action_button = "Refunded"\n \n # Add row to table\n payment_rows.append(\n Tr(*map(Td, (payment.created_at, payment.amount, payment.payment_status, action_button))))\n \n # Create payment history table\n payment_history = Table(\n Thead(Tr(*map(Th, ("Date", "Amount", "Status", "Action")))),\n Tbody(*payment_rows))\n \n return Titled(\n "Account Management",\n Div(H2(f"Account: {user_email}"),\n H3("Payment History"),\n payment_history,\n Div(id="refund-status"), # Target for refund status messages\n A("Back to Home", href="/")))', 'metadata': {'path': '/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/fasthtml/stripe_otp.py', 'uploaded_at': 1785635980.530908, 'name': 'account_management', 'lang': '.py', 'type': 'FunctionDef', 'lineno': 185, 'end_lineno': 211, 'mod_name': 'fasthtml.stripe_otp.account_management', 'package': 'python-fasthtml', 'version': '0.14.11', 'docstring': None, 'public_api': True}, 'package': 'python-fasthtml', '_dist': 0.48605406284332275, '_rrf_score': 0.016666666666666666}, {'rowid': 35278, 'content': 'def success(sess, checkout_sid:str): \n # Get payment record from database (saved in the webhook)\n payment = payments[checkout_sid]\n\n if not payment or payment.payment_status != \'paid\': \n return Titled("Error", P("Payment not found"))\n\n return Titled(\n "Success",\n Div(H2("Payment Successful!"),\n P(f"Thank you for your purchase, {sess[\'auth\']}"),\n P(f"Amount Paid: ${payment.amount / 100:.2f}"),\n P(f"Status: {payment.payment_status}"),\n P(f"Transaction ID: {payment.checkout_session_id}"),\n A("Back to Home", href="/")))', 'metadata': {'path': '/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/fasthtml/stripe_otp.py', 'uploaded_at': 1785635980.530908, 'name': 'success', 'lang': '.py', 'type': 'FunctionDef', 'lineno': 133, 'end_lineno': 147, 'mod_name': 'fasthtml.stripe_otp.success', 'package': 'python-fasthtml', 'version': '0.14.11', 'docstring': None, 'public_api': True}, 'package': 'python-fasthtml', '_dist': 0.5118991136550903, '_rrf_score': 0.01639344262295082}, {'rowid': 35227, 'content': 'def show(*s, **kwargs):\n "Same as fasthtml.components.show, but also adds `htmx.process()`"\n if IN_NOTEBOOK: return _show(*s, Script(\'if (window.htmx) htmx.process(document.body)\'), **kwargs)\n return _show(*s, **kwargs)', 'metadata': {'path': '/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/fasthtml/jupyter.py', 'uploaded_at': 1785635980.4980536, 'name': 'show', 'lang': '.py', 'type': 'FunctionDef', 'lineno': 41, 'end_lineno': 44, 'mod_name': 'fasthtml.jupyter.show', 'package': 'python-fasthtml', 'version': '0.14.11', 'docstring': 'Same as fasthtml.components.show, but also adds `htmx.process()`', 'public_api': True}, 'package': 'python-fasthtml', '_dist': 0.5131857395172119, '_rrf_score': 0.016129032258064516}, {'rowid': 35216, 'content': 'def _app_factory(*args, **kwargs):\n "Creates a FastHTML or FastHTMLWithLiveReload app instance"\n from .live_reload import FastHTMLWithLiveReload\n if kwargs.pop(\'live\', False): return FastHTMLWithLiveReload(*args, **kwargs)\n kwargs.pop(\'reload_attempts\', None)\n kwargs.pop(\'reload_interval\', None)\n return FastHTML(*args, **kwargs)', 'metadata': {'path': '/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/fasthtml/fastapp.py', 'uploaded_at': 1785635980.4972112, 'name': '_app_factory', 'lang': '.py', 'type': 'FunctionDef', 'lineno': 19, 'end_lineno': 25, 'mod_name': 'fasthtml.fastapp._app_factory', 'package': 'python-fasthtml', 'version': '0.14.11', 'docstring': 'Creates a FastHTML or FastHTMLWithLiveReload app instance', 'public_api': False}, 'package': 'python-fasthtml', '_dist': 0.5457382202148438, '_rrf_score': 0.015873015873015872}, {'rowid': 35228, 'content': 'def render_ft(**kw):\n "Call once in a notebook or solveit dialog to auto-render components with HTMX support"\n @patch\n def _repr_html_(self:FT):\n scr_proc = Script(\'if (window.htmx) htmx.process(document.body)\')\n return to_xml(Div(self, scr_proc, **kw))', 'metadata': {'path': '/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/fasthtml/jupyter.py', 'uploaded_at': 1785635980.4980536, 'name': 'render_ft', 'lang': '.py', 'type': 'FunctionDef', 'lineno': 47, 'end_lineno': 52, 'mod_name': 'fasthtml.jupyter.render_ft', 'package': 'python-fasthtml', 'version': '0.14.11', 'docstring': 'Call once in a notebook or solveit dialog to auto-render components with HTMX support', 'public_api': True}, 'package': 'python-fasthtml', '_dist': 0.5844467282295227, '_rrf_score': 0.015625}, {'rowid': 35112, 'content': 'def show(ft, *rest, iframe=False, height=\'auto\', style=None):\n "Renders FT Components into HTML within a Jupyter notebook."\n from IPython import display\n if isinstance(ft, str): ft = Safe(ft)\n if rest: ft = (ft,)+rest\n res = to_xml(ft)\n if iframe:\n style = "border: none; " + (style or "")\n cfg = dict(frameborder=0, width=\'100%\', height=height, style=style)\n res = to_xml(Iframe(srcdoc=res, **cfg))\n with warnings.catch_warnings():\n warnings.simplefilter("ignore", UserWarning)\n display.display(display.HTML(res))', 'metadata': {'path': '/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/fasthtml/components.py', 'uploaded_at': 1785635980.4775577, 'name': 'show', 'lang': '.py', 'type': 'FunctionDef', 'lineno': 126, 'end_lineno': 138, 'mod_name': 'fasthtml.components.show', 'package': 'python-fasthtml', 'version': '0.14.11', 'docstring': 'Renders FT Components into HTML within a Jupyter notebook.', 'public_api': True}, 'package': 'python-fasthtml', '_dist': 0.6196398138999939, '_rrf_score': 0.015384615384615385}, {'rowid': 35280, 'content': 'async def refund(sess, checkout_sid:str):\n # Get payment record from database\n payment = payments[checkout_sid]\n \n if not payment or payment.payment_status != \'paid\':\n return P("Error: Payment not found or not eligible for refund")\n \n try:\n # Get the payment intent ID from the checkout session\n checkout_session = stripe.checkout.Session.retrieve(checkout_sid)\n \n # Process the refund\n refund = stripe.Refund.create(payment_intent=checkout_session.payment_intent, reason="requested_by_customer")\n \n # Update payment status in database\n payments.update(Payment(checkout_session_id= checkout_sid, payment_status="refunded"))\n \n return Div(\n P("Refund processed successfully!"),\n P(f"Refund ID: {refund.id}"))\n \n except Exception as e: return P(f"Refund failed: {str(e)}")', 'metadata': {'path': '/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/fasthtml/stripe_otp.py', 'uploaded_at': 1785635980.530908, 'name': 'refund', 'lang': '.py', 'type': 'AsyncFunctionDef', 'lineno': 160, 'end_lineno': 181, 'mod_name': 'fasthtml.stripe_otp.refund', 'package': 'python-fasthtml', 'version': '0.14.11', 'docstring': None, 'public_api': True}, 'package': 'python-fasthtml', '_dist': 0.6311675310134888, '_rrf_score': 0.015151515151515152}, {'rowid': 35160, 'content': 'def is_full_page(req, resp):\n "Check if response should be rendered as full page or fragment"\n if resp and any(getattr(o, \'tag\', \'\')==\'html\' for o in resp): return True\n return \'hx-request\' in req.headers and \'hx-history-restore-request\' not in req.headers', 'metadata': {'path': '/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/fasthtml/core.py', 'uploaded_at': 1785635980.496347, 'name': 'is_full_page', 'lang': '.py', 'type': 'FunctionDef', 'lineno': 418, 'end_lineno': 421, 'mod_name': 'fasthtml.core.is_full_page', 'package': 'python-fasthtml', 'version': '0.14.11', 'docstring': 'Check if response should be rendered as full page or fragment', 'public_api': True}, 'package': 'python-fasthtml', '_dist': 0.6416814923286438, '_rrf_score': 0.014925373134328358}, {'rowid': 35123, 'content': 'def _get_htmx(h):\n res = {k:h.get(v.lower(), None) for k,v in htmx_hdrs.items()}\n return HtmxHeaders(**res)', 'metadata': {'path': '/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/fasthtml/core.py', 'uploaded_at': 1785635980.496347, 'name': '_get_htmx', 'lang': '.py', 'type': 'FunctionDef', 'lineno': 77, 'end_lineno': 79, 'mod_name': 'fasthtml.core._get_htmx', 'package': 'python-fasthtml', 'version': '0.14.11', 'docstring': None, 'public_api': False}, 'package': 'python-fasthtml', '_dist': 0.6486342549324036, '_rrf_score': 0.014705882352941176}, {'rowid': 35130, 'content': 'def HtmxResponseHeaders(**kwargs):\n "HTMX response headers"\n res = tuple(HttpHeader(_to_htmx_header(k), v) for k,v in kwargs.items())\n return res[0] if len(res)==1 else res', 'metadata': {'path': '/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/fasthtml/core.py', 'uploaded_at': 1785635980.496347, 'name': 'HtmxResponseHeaders', 'lang': '.py', 'type': 'FunctionDef', 'lineno': 130, 'end_lineno': 133, 'mod_name': 'fasthtml.core.HtmxResponseHeaders', 'package': 'python-fasthtml', 'version': '0.14.11', 'docstring': 'HTMX response headers', 'public_api': True}, 'package': 'python-fasthtml', '_dist': 0.6605545282363892, '_rrf_score': 0.014492753623188406}]Fast sync contract
The core index is designed for a quick edit–search loop. Repository and package updates are incremental, and graph enrichment is optional. Use graph=False when only semantic search is needed; the default graph path analyzes changed Python files with a fast AST pass. Full pyan3 analysis and PageRank are explicit graph operations, not hidden costs of ordinary indexing.