dhrishti

dhrishti exposes a live Python namespace over JSON. Start it in a notebook kernel, a training script, or a web application. Clients can inspect variables, expand containers, page grids, and run code.

dhrishti has no user interface. It provides the API for an inspector or another client.

Agents use a separate sandboxed overlay. They read owner variables and create their own names. You can promote selected results into the owner namespace.

Install

pip install dhrishti

Or straight from source:

pip install git+https://github.com/vedicreader/dhrishti.git

What it shows

A namespace maps names to values. snapshot returns inspector rows with a name, type, value, and shape.

import pandas as pd
from dhrishti.core import snapshot, expand, grid_page
ns = dict(x=42, names=['ada','turing','hopper'], df=pd.DataFrame({'a':[1,2,3], 'b':[4,5,6]}))
for v in snapshot(ns): print(f'{v.name} = {v.value}  ({v.type})')

df = DataFrame [3×2]  (DataFrame)
names = ['ada', 'turing', 'hopper']  (list)
x = 42  (int)

expand returns one level of a container. A DataFrame expands into metadata and columns. grid_page pages NumPy and pandas data.

for v in expand(ns, ('df',)): print(f'{v.name}: {v.value}')

shape: (3, 2)
size: 6
dtypes: Series [2] object
a: Series [3] int64
b: Series [3] int64

grid_page(ns, ('df',))['cells']

[['1', '4'], ['2', '5'], ['3', '6']]

Serving it

serve_in_kernel() starts an API server in a live IPython kernel. It returns the server port.

serve() starts an API server for a plain process. It uses the caller’s globals by default. It returns the base URL.

Shell messages wait for the running cell. The HTTP server runs on its own thread and continues to answer requests while the cell runs.

from dhrishti.serving import serve, owner_token, active
import httpx2 as httpx

x, names = 42, ['ada', 'turing', 'hopper']
server, url = serve(name='readme')          # this process's namespace, over HTTP
rows = httpx.get(f'{url}/api/rows').json()
[n['name'] for g in rows['groups'] for n in g['nodes']]

<script> document.body.addEventListener('htmx:configRequest', (event) => { if(event.detail.path.includes('://')) return; htmx.config.selfRequestsOnly=false; event.detail.path = `${location.protocol}//${location.hostname}:8000${event.detail.path}`; }); </script>

['url',
 'server',
 'names',
 'x',
 'v',
 'ns',
 'active',
 'owner_token',
 'serve',
 'grid_page',
 'expand',
 'snapshot',
 'set_logging',
 'open']

The endpoints

Accessors are JSON-encoded tuples. ["df", "x", 0] addresses df['x'][0]. The same format addresses namespace bindings, container children, DataFrame columns, and array cells.

endpoint	what it gives you
GET /api/rows?profile=&sort=	the grouped node tree; sort is name|recent|type|size
GET /api/expand?accessor=&offset=	one level of children, paged
GET /api/grid?accessor=&roff=&coff=	a windowed grid for anything numpy- or pandas-backed
GET /api/result	the last expression, kept at the _ accessor so you can expand into it
GET /api/history?n=	the rolling exec-history notebook’s code cells
GET /api/sessions, /api/session?name=	logged notebooks, and one by stem
GET /api/envs	this env’s label plus every other live dhrishti process
GET /api/exec?code=&scope=	run code — global mutates, isolated uses a scratch copy
GET /api/set?accessor=&expr=	assign an expression at an accessor
GET /api/promote?accessor=	adopt an agent’s variable into the owner namespace

/api/exec, /api/set, and /api/promote require an owner token. The server writes the token to <reg_dir>/token-<port> with mode 0600. A local client sends it in X-Dhrishti-Token or ?token=. Agents never receive the token.

The token controls access between local tools. It is not a cryptographic boundary. The API binds to localhost. Anyone who can read the token file can use the token.

serve() writes a JSON entry to the registry directory. active() returns live entries and removes entries for dead processes.

tok = owner_token()                                     # what a local consumer would read off disk
httpx.get(f'{url}/api/exec', params={'code': 'y = x * 2', 'token': tok}).json()['ok']
print('y is now', y)                                    # the exec landed in this very namespace
[(e['name'], e['port']) for e in active()]

y is now 84

[('readme', 8000)]

Handing your namespace to an agent

Start a server with the agent surface on. A tool-calling model can work in the namespace you are watching. This example uses rishi. Its Chat runs an on-device model. No API keys are required. The agent page has the full walkthrough.

from dhrishti.serving import agent_session, AGENT_POLICY
from dhrishti.agent import agent_tools, run_coro, AgentSession

df = pd.DataFrame({'x': range(5), 'y': list('abcde')})   # your live data
sess = agent_session()                                   # the shared, sandboxed session
print(AGENT_POLICY[:120], '...')

agent access: persistent session defined by Sandboxed Python session over a shared owner namespace. You can read and acc ...

agent_tools(sess) provides list_vars and run_python for one session. conversation_logger(sess) writes each turn to a transcript notebook. Pass both to Chat.

from fastcore.docments import docstring
sp = f'You are a Python assistant. you have a persistent session defined by {docstring(AgentSession)} Use builtins where possible. import only once. dont run same code again. check globals check if a module before using it. numpy and pandas are always be avilable. Call list_vars before writing code. tools available: {docstring(agent_tools)}'; sp

'You are a Python assistant. you have a persistent session defined by Sandboxed Python session over a shared owner namespace. You can read and access any owner variable freely; your writes land in your own layer and never touch the owner. Mutating or deleting owner variables is blocked. copy to a new name first (e.g. `df2 = df.copy()`, `lst2 = lst[:]`). Check available variables before writing code. Use builtins where possible. import only once. dont run same code again. check globals check if a module before using it. numpy and pandas are always be avilable. Call list_vars before writing code. tools available: Tools for a tool-calling agent over an AgentSession. `list_vars` shows what is available; call it first. `run_python` executes code in the session.'

from rishi import *
from rishi.litert import gemma4_e4b
from litert_lm import set_min_log_severity, Backend
from dhrishti.agent import conversation_logger
from fastcore.docments import docstring
set_min_log_severity(5)

chat = Chat(model=gemma4_e4b, sp=sp, tools=agent_tools(sess), cbs=[conversation_logger(sess)], backend=Backend.GPU(),
            approve=hitl_policy({'list_vars':'approved', 'run_python':'approved'}))
chat('Scale the numeric columns of df to 0..1 as a new frame df_norm.')

The numeric columns of df have been successfully scaled to the range of 0..1 and the result is stored in the new frame df_norm. The output shows the first few rows of df_norm with the normalized values.

sess.ns['df_norm']

Agents that use HTTP call /agent/api/*. The endpoints return the same rows and grids. The overlay and restriction list apply to every request.

agent='restricted' uses the persistent overlay. agent='readonly' runs every cell in an isolated sandbox. agent='off' refuses all agent endpoints.

/agent/api/sessions and /agent/api/transcript expose transcripts. A frontend can list each agent session.

What the agent can’t do

The agent reads owner variables. It writes only to its overlay. The session refuses changes to owner variables and filesystem or shell access. Refused cells return the reason in place of a result.

print(sess.run("df['z'] = 0").error)   # mutating what you own is refused
print(sess.run("import shutil; shutil.rmtree('/nope')").error) # filesystem escapes are refused
list(df.columns)    # your df is exactly as it was

blocked: cannot modify owner variable 'df' in place; bind your result to a new name instead
blocked: 'shutil.rmtree' is a shell/filesystem escape and is not allowed in the agent session; use your own shell tool

['x', 'y']

Promote what you want to keep

/agent/api/rows lists names in the agent overlay. /api/promote binds one agent name in the owner namespace. Promotion keeps the same object reference. It requires the owner token.

sess.run('df_norm = df.assign(x_norm=(df.x - df.x.min()) / (df.x.max() - df.x.min()))')
print(httpx.get(f'{url}/agent/api/rows').json()['agent_names'])
import json as _json
httpx.get(f'{url}/api/promote', params={'accessor': _json.dumps(['df_norm']), 'token': tok}).json()

['col', 'df_norm', 'max_val', 'min_val', 'np', 'numeric_cols']

{'ok': True, 'error': None}

'df_norm' in globals()   # now it is yours, and any frontend watching this process sees it

True

Learn more

The documentation covers the inspection core, runtime, serving layer, and agent overlay.

Dhrishti uses nbdev. Edit notebooks under nbs/. Run nbdev-prepare to export the library, run tests, and rebuild documentation.