# graph
------------------------------------------------------------------------
### CodeGraph
``` python
def CodeGraph(
path:str | pathlib.Path=':memory:'
):
```
*Call graph backed by apswutils SQLite.*
Storage: four tables in graph.db — graph_edges (caller, callee, kind,
confidence) graph_nodes (node, flavor, file, pagerank, …) co_dispatch
(group_id, node) file_index (path, root, last_analyzed_at)
``` python
self = CodeGraph(':memory:')
tables = {r[0] for r in self.db.execute("SELECT name FROM sqlite_master WHERE type='table'")}
assert {'graph_edges','graph_nodes','co_dispatch','file_index'} <= tables, f"Missing tables: {tables}"
print("schema ok:", tables)
```
schema ok: {'graph_edges', 'co_dispatch', 'graph_nodes', 'file_index'}
------------------------------------------------------------------------
### static_edges
``` python
def static_edges(
sources:dict=None, filenames:list=None, root:str=None
)->tuple:
```
*Static call edges via pyan3. Provide either filenames+root or sources
dict.*
------------------------------------------------------------------------
### dyn_edges
``` python
def dyn_edges(
src:str, module:str
)->list:
```
*All dynamic dispatch edges: decorator, connect_body, registration,
co_dispatch.*
``` python
_SRC = '''
import flask
app = flask.Flask(__name__)
@app.route('/hello')
def hello(): pass
def setup(other_app):
other_app.register(hello)
'''
edges = dyn_edges(_SRC, 'mymod')
kinds = {e['kind'] for e in edges}
assert 'decorator' in kinds, f"Expected decorator edge, got: {edges}"
assert 'registration' in kinds, f"Expected registration edge, got: {edges}"
assert dyn_edges('def (broken', 'bad') == L()
print("_dyn_edges ok:", edges)
```
_dyn_edges ok: [{'caller': 'mymod.app', 'callee': 'mymod.hello', 'kind': 'decorator', 'confidence': 0.75}, {'caller': 'mymod.setup', 'callee': 'mymod.hello', 'kind': 'connect_body', 'confidence': 0.9}, {'caller': 'mymod.other_app', 'callee': 'mymod.hello', 'kind': 'registration', 'confidence': 0.75}]
``` python
_DELEGATES_SRC = '''
from fastcore.all import delegates
def target(x, y, z=1): pass
@delegates(target)
def wrapper_pos(**kw): pass
@delegates(to=target)
def wrapper_kw(**kw): pass
@delegates
def bare(**kw): pass
@delegates()
def empty(**kw): pass
'''
dyn_edges(_DELEGATES_SRC, 'mymod')
```
[{'caller': 'mymod.wrapper_pos',
'callee': 'mymod.target',
'kind': 'delegates',
'confidence': 0.85},
{'caller': 'mymod.wrapper_kw',
'callee': 'mymod.to=target',
'kind': 'delegates',
'confidence': 0.85}]
``` python
_PATCH_SRC = '''
from fastcore.all import patch, delegates
from apswutils.db import Database, Table, View
@patch
def basic(self:Database, x): pass
@patch(as_prop=True)
def prop(self:Database): pass
@patch(cls_method=True)
def cls_m(cls:Database): pass
@patch
def no_ann(self): pass
@patch
def union_m(self:Table|View): pass
'''
dyn_edges(_PATCH_SRC, 'mymod')
```
[{'caller': 'mymod.Database',
'callee': 'mymod.basic',
'kind': 'patch',
'confidence': 0.9},
{'caller': 'mymod.Database',
'callee': 'mymod.prop',
'kind': 'patch',
'confidence': 0.9},
{'caller': 'mymod.Database',
'callee': 'mymod.cls_m',
'kind': 'patch',
'confidence': 0.9},
{'caller': 'mymod.Table',
'callee': 'mymod.union_m',
'kind': 'patch',
'confidence': 0.9},
{'caller': 'mymod.View',
'callee': 'mymod.union_m',
'kind': 'patch',
'confidence': 0.9}]
``` python
edges, meta = static_edges({"mod": "def foo(): pass\ndef bar(): foo()"})
meta
```
{'mod.foo': {'node': 'mod.foo', 'flavor': 'function', 'file': 'mod'},
'mod.foo.^^^argument^^^': {'node': 'mod.foo.^^^argument^^^',
'flavor': 'unspecified',
'file': 'mod'},
'mod.bar.^^^argument^^^': {'node': 'mod.bar.^^^argument^^^',
'flavor': 'unspecified',
'file': 'mod'},
'mod.bar': {'node': 'mod.bar', 'flavor': 'function', 'file': 'mod'}}
``` python
assert all(k in edges[0] for k in ('caller','callee','kind','confidence'))
assert all(e['kind'] == 'static' for e in edges)
```
``` python
static_edges({"bad": "def (: !!!"})
```
pyan3 static analysis failed: invalid syntax (bad, line 1)
([], {})
------------------------------------------------------------------------
### CodeGraph.from_sources
``` python
def from_sources(
sources:dict
):
```
*Build from {module_name: source_str}.*
``` python
g_pr = CodeGraph(':memory:')
g_pr.db['graph_edges'].insert_all([
{'caller':'A','callee':'B','kind':'static','confidence':1.0},
{'caller':'B','callee':'C','kind':'static','confidence':1.0},
{'caller':'A','callee':'C','kind':'static','confidence':1.0},
])
pr = _pagerank(g_pr.db)
print(pr)
assert 'C' in pr, "C should be in pagerank"
assert pr['C'] > pr['A'], f"C (most linked-to) should rank higher than A: {pr}"
print("pagerank ok:", pr)
```
{'A': 0.05000000000000001, 'B': 0.07125000000000001, 'C': 0.13181250000000003}
pagerank ok: {'A': 0.05000000000000001, 'B': 0.07125000000000001, 'C': 0.13181250000000003}
``` python
CodeGraph(':memory:').from_sources({'mod': 'def foo(): pass\ndef bar(): foo()\n'}).db.t.graph_nodes()
```
[{'node': 'mod.foo',
'flavor': 'function',
'file': 'mod',
'pagerank': 0.06938,
'in_degree': 1,
'out_degree': 0},
{'node': 'mod.foo.^^^argument^^^',
'flavor': 'unspecified',
'file': 'mod',
'pagerank': 0.0375,
'in_degree': 0,
'out_degree': 0},
{'node': 'mod.bar.^^^argument^^^',
'flavor': 'unspecified',
'file': 'mod',
'pagerank': 0.0375,
'in_degree': 0,
'out_degree': 0},
{'node': 'mod.bar',
'flavor': 'function',
'file': 'mod',
'pagerank': 0.0375,
'in_degree': 0,
'out_degree': 1}]
------------------------------------------------------------------------
### CodeGraph.from_pkg
``` python
def from_pkg(
pkg:str, path:pathlib.Path | str='.', recursive:bool=True, symlinks:bool=True, file_glob:str=None,
file_re:str=None, folder_re:str=None, skip_file_glob:str=None, skip_file_re:str=None, skip_folder_re:str=None,
func:callable=join, ret_folders:bool=False, sort:bool=True, types:str | list=None, exts:str | list=None
)->CodeGraph:
```
*Build from an installed package. Uses pyan3 on the package source
files.*
------------------------------------------------------------------------
### CodeGraph.from_file
``` python
def from_file(
path:str | pathlib.Path
)->CodeGraph:
```
*Build from a single .py file. Module name derived from filename.*
------------------------------------------------------------------------
### CodeGraph.from_dir
``` python
def from_dir(
dir:str | pathlib.Path, path:pathlib.Path | str='.', recursive:bool=True, symlinks:bool=True, file_glob:str=None,
file_re:str=None, folder_re:str=None, skip_file_glob:str=None, skip_file_re:str=None, skip_folder_re:str=None,
func:callable=join, ret_folders:bool=False, sort:bool=True, types:str | list=None, exts:str | list=None
)->CodeGraph:
```
*Build from .py files under path — pyan reads files directly.*
------------------------------------------------------------------------
### CodeGraph.process_files
``` python
def process_files(
files, root:NoneType=None
):
```
*Call self as a function.*
``` python
cg=CodeGraph(':memory:').from_pkg('httpx').from_pkg('fastcore').from_pkg('litesearch').from_pkg('fastlite').from_pkg('apswutils')
```
``` python
cg.db.t.graph_nodes(select='*', where='node="httpx._api.request"',limit=3)
```
[{'node': 'httpx._api.request',
'flavor': 'function',
'file': '/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/httpx/_api.py',
'pagerank': 8e-05,
'in_degree': 8,
'out_degree': 22}]
``` python
cg.from_dir('../kosha')
```
<__main__.CodeGraph>
``` python
cg.db.t.graph_nodes.count
```
11421
``` python
cg.gn('node like "%emb_doc%"')
```
[{'node': 'kosha.core.emb_doc',
'flavor': 'function',
'file': '../kosha/core.py',
'pagerank': 0.00012,
'in_degree': 0,
'out_degree': 0}]
------------------------------------------------------------------------
### CodeGraph.node_info
``` python
def node_info(
node:str, with_kind:bool=False
)->dict:
```
*Call self as a function.*
------------------------------------------------------------------------
### CodeGraph.edge_kinds
``` python
def edge_kinds(
)->dict:
```
*Call self as a function.*
------------------------------------------------------------------------
### CodeGraph.short_paths
``` python
def short_paths(
nodes, k:int=10
)->L:
```
*Shortest paths between all pairs in top-k nodes via combinations.*
------------------------------------------------------------------------
### CodeGraph.short_path
``` python
def short_path(
src:str, tgt:str
)->L:
```
*Shortest path from src to tgt via recursive CTE. Returns L of node
names.*
------------------------------------------------------------------------
### CodeGraph.ranked
``` python
def ranked(
k:int=10, module:str=None
)->L:
```
*Top-k nodes by pagerank, optionally filtered to a module prefix.*
------------------------------------------------------------------------
### CodeGraph.co_dispatched
``` python
def co_dispatched(
node:str
)->L:
```
*Call self as a function.*
------------------------------------------------------------------------
### CodeGraph.neighbors
``` python
def neighbors(
n:str, depth:int=1
)->L:
```
*callers + callees up to depth hops.*
------------------------------------------------------------------------
### CodeGraph.callees
``` python
def callees(
n:str, with_kind:bool=False
)->L:
```
*Call self as a function.*
------------------------------------------------------------------------
### CodeGraph.callers
``` python
def callers(
n:str, with_kind:bool=False
)->L:
```
*Call self as a function.*
``` python
cg.db.t.graph_edges(where='caller like "%apswutils.db.Table.insert_all%" and callee like "%insert_chunk%"')
```
[{'id': 15617,
'caller': 'apswutils.db.Table.insert_all',
'callee': 'apswutils.db.Table.insert_chunk',
'kind': 'static',
'confidence': 1.0}]
``` python
to_date_co = cg.co_dispatched('fastcore.basics.to_date')
assert all('fastcore' in n for n in to_date_co), \
f"fastcore.basics.to_date co_dispatched leaked into httpx: {to_date_co}"
assert len(to_date_co) > 0, "fastcore.basics.to_date should have co_dispatched peers"
print("co_dispatched cross-package isolation ok:", to_date_co)
```
co_dispatched cross-package isolation ok: ['fastcore.basics.to_int', 'fastcore.basics.to_bool', 'fastcore.basics.to_float']
``` python
cg.node_info('fastcore.basics.to_date')
```
{'node': 'fastcore.basics.to_date',
'flavor': 'function',
'file': '/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/fastcore/basics.py',
'pagerank': 3e-05,
'in_degree': 0,
'out_degree': 4,
'callers': [],
'callees': ['None.str', 'None.isinstance', 'fastcore.basics._typeerr', 'fastcore.basics.str2date'],
'co_dispatched': ['fastcore.basics.to_int', 'fastcore.basics.to_bool', 'fastcore.basics.to_float']}
``` python
n = cg.db.t.graph_nodes(where='node like "%mk_write"')[0]['node']
cg.node_info(n)
```
{'node': 'fastcore.xtras.mk_write',
'flavor': 'function',
'file': '/Users/71293/code/personal/orgs/kosha/.venv/lib/python3.13/site-packages/fastcore/xtras.py',
'pagerank': 3e-05,
'in_degree': 2,
'out_degree': 7,
'callers': ['fastcore.xtras.write_json', 'fastcore.xtras.Path'],
'callees': ['None.parent', 'fastcore.basics.patch', 'None.chown', 'None.NoneType', 'None.write_text', 'None.Path', 'None.int'],
'co_dispatched': []}
``` python
cg.short_path('apswutils.db.Table.upsert', 'apswutils.db.Table.insert_chunk')
```
['apswutils.db.Table.upsert', 'apswutils.db.Table.upsert_all', 'apswutils.db.Table.insert_all', 'apswutils.db.Table.insert_chunk']
``` python
cg.ranked(5, module='litesearch')
```
[{'node': 'litesearch.data.kw', 'pagerank': 0.00064}, {'node': 'litesearch.utils.FastEncode._load_tok.listcomp.0', 'pagerank': 0.00034}, {'node': 'litesearch.utils.encode_pdf_images.listcomp.1', 'pagerank': 0.00034}, {'node': 'litesearch.core.vec_search', 'pagerank': 0.00033}, {'node': 'litesearch.data.file_parse.meta_', 'pagerank': 0.00033}]
``` python
cg.callers('litesearch.data.kw')
```
['litesearch.core.get_store', 'litesearch.core.database', 'litesearch.data.pkg2chunks', 'litesearch.data.pre', 'litesearch.utils.FastEncode.encode', 'litesearch.utils.FastEncode.encode.lambda.0', 'litesearch.utils.FastEncode.encode_document', 'litesearch.utils.FastEncode.encode_query', 'litesearch.utils.FastEncodeImage.embed', 'litesearch.utils.FastEncodeImage.embed.lambda.0', 'litesearch.utils.FastEncodeMultimodal.encode_text', 'litesearch.utils.FastEncodeMultimodal.encode_image', 'litesearch.utils.encode_pdf_texts']
------------------------------------------------------------------------
### CodeGraph.file2nodes
``` python
def file2nodes(
path:str
)->set:
```
*Return set of node names whose file column matches path.*
``` python
g_drop = CodeGraph(':memory:')
g_drop.db.t.graph_nodes.insert_all([
{'node':'mod.foo','flavor':'function','file':'/proj/mod.py'},
{'node':'mod.bar','flavor':'function','file':'/proj/mod.py'},
])
g_drop.db.t.graph_edges.insert({'caller':'mod.foo','callee':'mod.bar','kind':'static','confidence':1.0})
assert g_drop.file2nodes('/proj/mod.py') == {'mod.foo','mod.bar'}
g_drop._drop_file('/proj/mod.py')
assert g_drop.file2nodes('/proj/mod.py') == set()
assert not list(g_drop.db.execute("SELECT * FROM graph_edges"))
print("_drop_file + _nodes_for_file ok")
```
_drop_file + _nodes_for_file ok
------------------------------------------------------------------------
### CodeGraph.sync
``` python
def sync(
dir:NoneType=None, pkgs:NoneType=None
)->CodeGraph:
```
*Incremental sync: from_dir per dir, from_pkg per pkg; manage
file_index.*
------------------------------------------------------------------------
### CodeGraph.sync_pkgs
``` python
def sync_pkgs(
pkgs:list
)->CodeGraph:
```
*Incremental sync for packages: drop missing files, update changed
files, add new files.*
------------------------------------------------------------------------
### CodeGraph.sync_dir
``` python
def sync_dir(
dir:str | pathlib.Path
)->CodeGraph:
```
*Incremental sync for a directory: drop missing files, update changed
files, add new files.*
``` python
import tempfile, time
with tempfile.TemporaryDirectory() as tmp:
pa, pb = Path(f'{tmp}/a.py'), Path(f'{tmp}/b.py')
pa.write_text('def foo(): pass\n'); pb.write_text('def bar(): pass\n')
g = CodeGraph(':memory:')
g.sync(dir=tmp)
fi = {r['path']: r['last_analyzed_at'] for r in g.db.t.file_index.rows}
assert str(pa) in fi and str(pb) in fi, fi
# Modify b.py — mtime changes
time.sleep(0.01)
pb.write_text('def bar(): return 42\n')
pb.touch() # ensure mtime update
g.sync(dir=tmp)
fi2 = {r['path']: r['last_analyzed_at'] for r in g.db.t.file_index.rows}
assert fi2[str(pa)] == fi[str(pa)], f"a.py should not be reprocessed: {fi2}"
assert fi2[str(pb)] != fi[str(pb)], f"b.py should be reprocessed: {fi2}"
# Delete a.py — should be removed from file_index
pa.unlink()
g.sync(dir=tmp)
fi3 = {r['path'] for r in g.db.t.file_index.rows}
assert str(pa) not in fi3, f"a.py should be removed: {fi3}"
print("sync incremental ok, remaining files:", fi3)
# add packages to codegraph
g.sync(pkgs=['httpx', 'fastcore'])
fi4 = {r['path'] for r in g.db.t.file_index.rows}
assert any('httpx' in p for p in fi4), f"httpx files should be indexed: {fi4}"
assert any('fastcore' in p for p in fi4), f"fastcore files should be indexed: {fi4}"
print("sync_pkgs ok, indexed packages:", fi4)
```
no action. pkgs empty
no action. pkgs empty
no action. pkgs empty
sync incremental ok, remaining files: {'/tmp/tmpphfek2l5/b.py'}
no action. dir empty
sync_pkgs ok, indexed packages: {'/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_transports/wsgi.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_urls.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_transports/default.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_decoders.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/all.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/parallel.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/net.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/foundation.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/basics.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/docscrape.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/py2pyi.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/__init__.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/shutil.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/__version__.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/imghdr.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/docments.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/style.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_transports/mock.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/transform.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_api.py', '/tmp/tmpphfek2l5/b.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/test.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_models.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_status_codes.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_utils.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/imports.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_transports/base.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_content.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_main.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/tools.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/_modidx.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_urlparse.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/utils.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_auth.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/nbio.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/script.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/xdg.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/xtras.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_types.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_multipart.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/nb_imports.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_exceptions.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_config.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_transports/asgi.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/__init__.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_transports/__init__.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/dispatch.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/meta.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/httpx/_client.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/xml.py', '/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/fastcore/ansi.py'}
------------------------------------------------------------------------
### Kosha.short_paths
``` python
def short_paths(
):
```
*Shortest paths helper: shortest paths between all pairs in top-k
nodes.*
------------------------------------------------------------------------
### Kosha.short_path
``` python
def short_path(
):
```
*Shortest path helper: shortest path between two nodes.*
------------------------------------------------------------------------
### Kosha.neighbors
``` python
def neighbors(
):
```
*Neighbors helper: callers + callees up to depth hops.*
------------------------------------------------------------------------
### Kosha.ni
``` python
def ni(
):
```
*Node info helper: graph_nodes row + callers, callees, co-dispatched
nodes.*
------------------------------------------------------------------------
### Kosha.ge
``` python
def ge(
):
```
*graph_edges table for direct queries.*
------------------------------------------------------------------------
### Kosha.gn
``` python
def gn(
):
```
*graph_nodes table for direct queries.*
------------------------------------------------------------------------
### Kosha.graphdb
``` python
def graphdb(
):
```
*Underlying graph.db database for direct queries.*
------------------------------------------------------------------------
### Kosha.graph
``` python
def graph(
)->CodeGraph:
```
*code graph for this kosha instance*
------------------------------------------------------------------------
### Kosha.context
``` python
def context(
q:str, # query with optional key:value filters
limit:int=50, repo:bool=True, env:bool=True, graph:bool=True, columns:str='content,metadata', sys_wide:bool=True,
kw:VAR_KEYWORD
)->L: # forwarded to env_context / repo_context
```
*Fan-out semantic search: parse filters, run repo + env searches, merge
with chained RRF.*
------------------------------------------------------------------------
### Kosha.sync
``` python
def sync(
pkgs:NoneType=None, dir:NoneType=None, emb:function=embedder, verbose:bool=True, in_parallel:bool=False
)->Kosha:
```
*Sync code store, env store, and code graph. Runs in a daemon thread by
default.*
``` python
k = Kosha(xdg_dir=Path('.'))
```
``` python
k.sync(pkgs=['httpx', 'fastcore', 'litesearch','fastlite','apswutils','python-fasthtml','apsw','ghapi'])
```
syncing files [Path('/Users/71293/code/personal/orgs/kosha/kosha/core.py'), Path('/Users/71293/code/personal/orgs/kosha/kosha/graph.py')] .....
synced repo
loading pkgs {'fastlite', 'httpx', 'ghapi', 'fastcore', 'apswutils', 'python-fasthtml', 'apsw', 'litesearch'} ......
Updating packages: 0%| | 0/8 [00:00]
``` python
k.sync(in_parallel=True)
```
loading pkgs {'fastlite', 'pillow', 'model2vec', 'pdf_oxide', 'fastcore', 'onnxruntime', 'anyio', 'notebook', 'yake', 'litesearch', 'Jinja2', 'pyan3', 'tokenizers', 'pandas', 'codesigs', 'chonkie', 'python-fasthtml', 'watchfiles', 'fastprogress', 'usearch'} ......
Updating packages: 20%|██ | 4/20 [00:00<00:00, 35.32pkg/s]
updating pkg: fastlite ...
no action. pkgs empty
package [{'name': 'fastlite', 'version': '0.2.4'}] already loaded.
updating pkg: pillow ...
package [{'name': 'pillow', 'version': '12.2.0'}] already loaded.
updating pkg: model2vec ...
package [{'name': 'model2vec', 'version': '0.8.1'}] already loaded.
updating pkg: pdf_oxide ...
package [{'name': 'pdf_oxide', 'version': '0.3.37'}] already loaded.
updating pkg: fastcore ...
package [{'name': 'fastcore', 'version': '1.12.40'}] already loaded.
updating pkg: onnxruntime ...
package [{'name': 'onnxruntime', 'version': '1.24.4'}] already loaded.
updating pkg: anyio ...
package [{'name': 'anyio', 'version': '4.13.0'}] already loaded.
Updating packages: 60%|██████ | 12/20 [00:00<00:00, 32.23pkg/s]
updating pkg: notebook ...
package [{'name': 'notebook', 'version': '7.5.5'}] already loaded.
updating pkg: yake ...
package [{'name': 'yake', 'version': '0.7.3'}] already loaded.
updating pkg: litesearch ...
package [{'name': 'litesearch', 'version': '0.0.23'}] already loaded.
updating pkg: Jinja2 ...
package [{'name': 'Jinja2', 'version': '3.1.6'}] already loaded.
updating pkg: pyan3 ...
package [{'name': 'pyan3', 'version': '2.5.0'}] already loaded.
updating pkg: tokenizers ...
Updating packages: 100%|██████████| 20/20 [00:00<00:00, 33.21pkg/s]
package [{'name': 'tokenizers', 'version': '0.22.2'}] already loaded.
updating pkg: pandas ...
package [{'name': 'pandas', 'version': '3.0.2'}] already loaded.
updating pkg: codesigs ...
package [{'name': 'codesigs', 'version': '0.0.2'}] already loaded.
updating pkg: chonkie ...
package [{'name': 'chonkie', 'version': '1.6.4'}] already loaded.
updating pkg: python-fasthtml ...
package [{'name': 'python-fasthtml', 'version': '0.13.3'}] already loaded.
updating pkg: watchfiles ...
package [{'name': 'watchfiles', 'version': '1.1.1'}] already loaded.
updating pkg: fastprogress ...
package [{'name': 'fastprogress', 'version': '1.1.5'}] already loaded.
updating pkg: usearch ...
package [{'name': 'usearch', 'version': '2.25.1'}] already loaded.
[None, None, <__main__.CodeGraph>]
``` python
k.gn(where='node like "fastcore.basics.me%"', limit=1)
```
[{'node': 'fastcore.basics.merge.str',
'flavor': 'attribute',
'file': '/Users/71293/code/personal/orgs/karma/.venv/lib/python3.13/site-packages/fastcore/basics.py',
'pagerank': 3e-05,
'in_degree': 0,
'out_degree': 0}]
``` python
k.graph.ranked(module='fastcore.basics')
```
[{'node': 'fastcore.basics.patch', 'pagerank': 0.00089}, {'node': 'fastcore.basics.NS.__iter__', 'pagerank': 0.00056}, {'node': 'fastcore.basics.NotStr.__iter__', 'pagerank': 0.00056}, {'node': 'fastcore.basics.GetAttr', 'pagerank': 0.00035}, {'node': 'fastcore.basics.NotStr', 'pagerank': 0.0003}, {'node': 'fastcore.basics.listify', 'pagerank': 0.00025}, {'node': 'fastcore.basics.NS', 'pagerank': 0.0002}, {'node': 'fastcore.basics.adict', 'pagerank': 0.00018}, {'node': 'fastcore.basics.AttrDict', 'pagerank': 0.00017}, {'node': 'fastcore.basics.not_._f', 'pagerank': 0.00014}]
``` python
k.ni('fastcore.basics.merge')
```
{'node': 'fastcore.basics.merge',
'flavor': 'function',
'file': '/Users/71293/code/personal/orgs/karma/.venv/lib/python3.13/site-packages/fastcore/basics.py',
'pagerank': 3e-05,
'in_degree': 1,
'out_degree': 12,
'callers': ['fastcore.script.call_parse._f'],
'callees': ['fastcore.docscrape.NumpyDocString.__iter__', 'fastcore.nbio.Notebook.__iter__', 'fastcore.xtras.IterLen.__iter__', 'fastcore.basics.NotStr.__iter__', 'None.__next__', 'fastcore.xml.FT.__iter__', 'None.ds', 'fastcore.basics.NS.__iter__', 'fastcore.foundation.CollBase.__iter__', 'fastcore.xtras._save_iter.__iter__', 'fastcore.xtras.CachedIter.__iter__', 'fastcore.xtras.SaveReturn.__iter__'],
'co_dispatched': []}
``` python
first(k.context('how do I merge dicts package:fastcore path:basics', limit=1))
```
``` python
{ '_rrf_score': 0.016666666666666666,
'_src_id': 'env:641',
'callees': ['fastcore.docscrape.NumpyDocString.__iter__', 'fastcore.nbio.Notebook.__iter__', 'fastcore.xtras.IterLen.__iter__', 'fastcore.basics.NotStr.__iter__', 'None.__next__', 'fastcore.xml.FT.__iter__', 'None.ds', 'fastcore.basics.NS.__iter__', 'fastcore.foundation.CollBase.__iter__', 'fastcore.xtras._save_iter.__iter__', 'fastcore.xtras.CachedIter.__iter__', 'fastcore.xtras.SaveReturn.__iter__'],
'callers': ['fastcore.script.call_parse._f'],
'co_dispatched': [],
'content': 'def merge(*ds):\n'
' "Merge all dictionaries in `ds`"\n'
' return {k:v for d in ds if d is not None for k,v in '
'd.items()}',
'file': '/Users/71293/code/personal/orgs/karma/.venv/lib/python3.13/site-packages/fastcore/basics.py',
'flavor': 'function',
'in_degree': 1,
'metadata': { 'end_lineno': 657,
'lang': '.py',
'lineno': 655,
'mod_name': 'fastcore.basics.merge',
'name': 'merge',
'package': 'fastcore',
'path': '/Users/71293/code/personal/orgs/karma/.venv/lib/python3.13/site-packages/fastcore/basics.py',
'type': 'FunctionDef',
'uploaded_at': 1776124140.6147513,
'version': '1.12.39'},
'node': 'fastcore.basics.merge',
'out_degree': 12,
'pagerank': 3e-05,
'rank': -10.449557921383162,
'rowid': 641}
```
------------------------------------------------------------------------
### Kosha.task_context
``` python
def task_context(
q:str, depth:int=3, limit:int=10
)->dict:
```
*Structured context: candidate packages → dep stack → graph entry points
→ call paths.*
------------------------------------------------------------------------
### Kosha.dep_stack
``` python
def dep_stack(
seeds:list=None, depth:int=1
)->list:
```
*BFS over pkg_deps, ordered by coupling strength.*
``` python
# dep_stack smoke test
k2 = Kosha(xdg_dir=Path('.'))
k2.update_pkg('fastlite')
rows = list(k2.envdb.t.pkg_deps(where='from_pkg="fastlite"'))
assert rows, 'pkg_deps should have rows after update_pkg'
assert any(r['to_pkg'] in ('fastcore','fastlite') for r in rows), f'expected fastcore/fastlite: {rows[:3]}'
print('pkg_deps via update_pkg ok:', rows[:3])
```
pkg_deps via update_pkg ok: [{'from_pkg': 'fastlite', 'to_pkg': 'apsw', 'n_modules': 1}, {'from_pkg': 'fastlite', 'to_pkg': 'apswutils', 'n_modules': 2}, {'from_pkg': 'fastlite', 'to_pkg': 'dataclasses', 'n_modules': 2}]
``` python
layers = k2.dep_stack(['fastlite'])
print(layers)
print('\n\n-------------------------------------------------\n\n')
stack = L(layers).flatten()
assert 'fastcore' in stack, f'fastcore should be in dep_stack: {stack}'
print('_dep_stack ok:', stack)
```
[['fastlite'], ['apswutils', 'dataclasses', 'enum', 'typing', 'fastcore', 'inspect', 'types', 'apsw']]
-------------------------------------------------
_dep_stack ok: ['fastlite', 'apswutils', 'dataclasses', 'enum', 'typing', 'fastcore', 'inspect', 'types', 'apsw']
``` python
tc = k2.task_context('payments page monsterui fasthtml')
print('task_context packages:', tc['packages'])
print('task_context dep_stack:', tc['dep_layers'])
```
task_context packages: ['fastcore', 'httpx', 'fastlite', 'apsw', 'ghapi', 'apswutils', 'litesearch']
task_context dep_stack: [['fastcore', 'httpx', 'fastlite', 'apsw', 'ghapi', 'apswutils', 'litesearch'], ['typing', 'os', 're', 'inspect', 'sys', 'functools', 'json', 'time', 'contextlib', 'collections', 'types', 'io', 'dataclasses', 'enum', 'urllib', 'importlib', 'warnings', 'random', 'argparse', 'ast', 'textwrap', 'math', 'copy', 'itertools', 'datetime', 'tempfile', 'pathlib', 'shutil', 'base64', 'contextvars', 'ssl', 'numpy', 'subprocess', 'html', 'asyncio', 'pprint', 'logging', 'codecs', 'fnmatch', 'csv', 'PIL', 'threading', 'shlex', 'traceback', 'mimetypes', 'http', 'pickle', 'hashlib', 'pdf_oxide', 'ipaddress', 'webbrowser', 'socket', 'xml', 'gzip', 'usearch', 'idna', 'atexit', 'difflib', 'uuid', 'string', 'struct', 'httpcore', 'fractions', 'certifi', 'resource', 'builtins', 'decimal', 'getpass', 'weakref', 'tokenize', 'pygments', 'readline', 'tomllib', 'queue', 'abc', 'tokenizers', 'onnxruntime', 'wcwidth', 'click', 'email', 'sqlite3', 'operator', 'numbers', 'netrc', 'gc', 'codesigs', 'pandas', 'platform', 'statistics', 'zlib', 'configparser', 'concurrent', 'termios', 'tty', 'binascii', 'rich', 'yake', 'IPython', 'unicodedata', 'ctypes', 'keyword', 'bz2', 'chonkie', 'zipfile', 'anyio', 'code', 'pdb', 'huggingface_hub', 'secrets', 'yaml', 'multiprocessing', 'glob']]
``` python
k2.context('payments page monsterui fasthtml', repo=False)[:10]
```
[{'rowid': 1068, 'content': 'def _repr_html_(self:FT): return self.__html__()', 'metadata': {'path': '/Users/71293/code/personal/orgs/karma/.venv/lib/python3.13/site-packages/fastcore/xml.py', 'uploaded_at': 1776124140.6237516, 'name': '_repr_html_', 'lang': '.py', 'type': 'FunctionDef', 'lineno': 224, 'end_lineno': 224, 'package': 'fastcore', 'version': '1.12.39', 'mod_name': 'fastcore.xml._repr_html_'}, '_dist': 0.7265547513961792, '_rrf_score': 0.016666666666666666, '_src_id': 'env:1068', 'node': 'fastcore.xml._repr_html_', 'flavor': 'function', 'file': '/Users/71293/code/personal/orgs/karma/.venv/lib/python3.13/site-packages/fastcore/xml.py', 'pagerank': 0.00013, 'in_degree': 1, 'out_degree': 4, 'callers': ['fastcore.xml.FT'], 'callees': ['fastcore.xml.__html__', 'fastcore.basics.patch', 'fastcore.xml.FT', 'fastcore.xml.Safe.__html__'], 'co_dispatched': []}, {'rowid': 1067, 'content': 'def __html__(self:FT): return to_xml(self, indent=False)', 'metadata': {'path': '/Users/71293/code/personal/orgs/karma/.venv/lib/python3.13/site-packages/fastcore/xml.py', 'uploaded_at': 1776124140.6237516, 'name': '__html__', 'lang': '.py', 'type': 'FunctionDef', 'lineno': 219, 'end_lineno': 219, 'package': 'fastcore', 'version': '1.12.39', 'mod_name': 'fastcore.xml.__html__'}, '_dist': 0.7330434918403625, '_rrf_score': 0.01639344262295082, '_src_id': 'env:1067', 'node': 'fastcore.xml.__html__', 'flavor': 'function', 'file': '/Users/71293/code/personal/orgs/karma/.venv/lib/python3.13/site-packages/fastcore/xml.py', 'pagerank': 0.00018, 'in_degree': 6, 'out_degree': 3, 'callers': ['fastcore.xml._escape', 'fastcore.xml._noescape', 'fastcore.xml._to_attr', 'fastcore.xml._repr_html_', 'fastcore.xtras.hl_md', 'fastcore.xml.FT'], 'callees': ['fastcore.basics.patch', 'fastcore.xml.FT', 'fastcore.xml.to_xml'], 'co_dispatched': []}, {'rowid': 1060, 'content': 'def Html(*c, doctype=True, **kwargs)->FT:\n "An HTML tag, optionally preceeded by `!DOCTYPE HTML`"\n res = ft(\'html\', *c, **kwargs)\n if not doctype: return res\n return (ft(\'!DOCTYPE\', html=True, void_=True), res)', 'metadata': {'path': '/Users/71293/code/personal/orgs/karma/.venv/lib/python3.13/site-packages/fastcore/xml.py', 'uploaded_at': 1776124140.6237516, 'name': 'Html', 'lang': '.py', 'type': 'FunctionDef', 'lineno': 128, 'end_lineno': 132, 'package': 'fastcore', 'version': '1.12.39', 'mod_name': 'fastcore.xml.Html'}, '_dist': 0.7629344463348389, '_rrf_score': 0.016129032258064516, '_src_id': 'env:1060', 'node': 'fastcore.xml.Html', 'flavor': 'function', 'file': '/Users/71293/code/personal/orgs/karma/.venv/lib/python3.13/site-packages/fastcore/xml.py', 'pagerank': 3e-05, 'in_degree': 0, 'out_degree': 5, 'callers': [], 'callees': ['None.bool', 'fastcore.script.Param.kwargs', 'fastcore.xml.ft', 'fastcore.xml.FT', 'None.c'], 'co_dispatched': []}, {'rowid': 1073, 'content': 'def showtags(s):\n return f"""\n{escape(to_xml(s))}\n\n{escape(to_xml(s))}\n