env2llm
AI Cost Tracking
- 🤖 LLM usage: $1.7600 (13 commits)
- 👤 Human dev: ~$1194 (11.9h @ $100/h, 30min dedup)
Generated on 2026-07-19 using openrouter/qwen/qwen3-coder-next
Generate environment maps for LLM agents: available services, commands, artifacts, masked environment variables, and runtime policies.
Default output is DOQL-flavored LESS (environment.doql.less), compatible with
nlp2dsl examples:
environment[name="03-report-and-notify"] {
NLP2DSL_BACKEND_URL: "http://localhost:8010";
LLM_MODEL: "openrouter/...";
}
runtimes[0] { id: "orchestrator:nlp-service"; kind: "orchestrator"; ... }
commands[3] { name: "generate_report"; required: "report_type"; ... }
Install
cd env2llm
pip install -e ".[dev]"
CLI
# From an nlp2dsl example directory
env2llm /path/to/nlp2dsl/examples/03-report-and-notify
# Other formats
env2llm . --format yaml
env2llm . --format json
env2llm . --format markdown
# Optional: attach live Linux desktop snapshot (GNOME/X11 via wmctrl/xdotool)
env2llm . --probe-desktop
# or: ENV2LLM_DESKTOP_PROBE=1 env2llm .
# Koru projects: auto-attach MCP tool catalog (koru_list_tickets, …) when koruapi installed
env2llm . --probe-mcp
# or auto when cwd is a Koru repo with koruapi on PYTHONPATH
Writes to .nlp2dsl/registry/environment.<ext> (and mirrors legacy paths for DOQL).
Desktop / GUI probe (optional)
When --probe-desktop or ENV2LLM_DESKTOP_PROBE=1 is set, env2llm adds:
desktop { canvas_width, canvas_height, compositor, display_server, ... }desktop_displays[N] { id, output, left, top, width, height, is_primary, index }— full multi-monitor layout (xrandrormss)desktop_pointer { x, y, display_id, display_x, display_y, ... }— mouse position in global and display-local coords (xdotool)desktop_ide_calibrations[N] { ide, chat_x, chat_y, config_path, display_id, ... }— Koru OS-injector chat anchors from~/.koru/ide-os-injector.jsonand<project>/.koru/ide-os-injector.jsondesktop_windows[N] { title, x, y, width, height, ... }— top-level windows (wmctrl)- runtime
probe:desktop(desktop://session) for GUI automation via nlp2uri - commands
desktop_focus_window,desktop_move_window,desktop_screenshot_*,desktop_open_app - summary keys in
data(desktop.displays,desktop.pointer,desktop.pointer_display,desktop.window_titles, …)
Requires (Linux): xrandr (preferred) or Python mss for monitor layout; xdotool for pointer;
wmctrl for window titles/geometry. Headless hosts get status: unknown without failing workflow maps.
Host probe (cron, ports, processes, containers, agents)
When --probe-host or ENV2LLM_HOST_PROBE=1 (default on for project dirs), env2llm adds:
host { hostname, cron_taskinity_installed, capabilities_available, … }host_cron[N] { schedule, command, marker }— parsed fromcrontab -lhost_endpoint[N] { id, url, ok }— agents:8101–8130, WWW:8788host_port[N] { port, address, pid, process }— selected listening ports fromss -ltnphost_process[N] { pid, command, args }— relevant runtime processes (uvicorn,docker,hypervisor, monitors)host_container[N] { name, image, state, project, service }— currentdocker pssnapshothost_agent[N] { id, ok, runtime_status, effective_health_uri, recommended_action }—hypervisor inspect-agenthost_examples_test { pass, fail, skip, … }— fromoutput/examples/comprehensive_report.jsonwhen presenthost_monitor_log_tail { line_N }— tail of/tmp/taskinity-monitor.logschedules[N]— cron lines mirrored for workflow planners
env2llm /path/to/hypervisor --probe-host
ENV2LLM_HOST_PROBE=1 env2llm . -f json
Browser window titles are detected heuristically (Firefox, Chrome, Edge, …). Page DOM/content is not scraped — use testql / Playwright for that layer.
Python API
from env2llm import RegistryService, ensure_environment_map, render_format, generate_system_map
path = ensure_environment_map("examples/03-report-and-notify")
ir = generate_system_map("examples/03-report-and-notify", example_id="03-report-and-notify")
yaml_text = render_format(ir, "yaml")
# Live registry service (load / refresh / render / MQTT)
service = RegistryService(".", project_id="my-app")
registry_json = service.render("json")
# Deterministic service construction for orchestrators
from env2llm.service import RegistryServiceFactory, ServiceFactoryRequest
result = RegistryServiceFactory().create(
ServiceFactoryRequest(project_dir=".", project_id="my-app", mqtt=False)
)
descriptor = result.descriptor.to_dict()
# descriptor["schema"] == "env2llm.service-descriptor.v1"
# descriptor["descriptor_hash"] is stable for the same normalized request/state
The request, descriptor, and typed error contracts ship as JSON Schemas and
can be loaded with env2llm.service.service_contract_schema(...). Unknown
service kinds fail closed with UnknownServiceKindError; no LLM text is parsed
by the factory.
REST API (env2llm-serve)
env2llm-serve --project . --port 8770
# optional MQTT fan-out:
ENV2LLM_MQTT_ENABLED=1 env2llm-serve --project . --mqtt
| Method | Path | Opis |
|---|---|---|
GET |
/health |
status |
GET |
/v1/registry?format=json|yaml|doql|md&refresh=1 |
registry |
POST |
/v1/registry/refresh |
regenerate + persist (+ MQTT) |
GET |
/v1/registry/desktop |
desktop probe slice |
GET |
/v1/registry/commands |
command schemas |
GET |
/v1/registry/uris |
nlp2uri URI index (needs nlp2uri[envmap]) |
GET |
/v1/registry/mqtt |
MQTT bridge status |
MCP (env2llm-mcp)
{
"mcpServers": {
"env2llm": {
"command": "env2llm-mcp",
"args": ["--project", "/path/to/project"],
"env": { "ENV2LLM_MQTT_ENABLED": "1" }
}
}
}
Tools: env2llm_get_registry, env2llm_render_registry, env2llm_refresh_registry,
env2llm_get_desktop, env2llm_list_commands, env2llm_list_uris, env2llm_mqtt_status.
MQTT (env2llm-mqtt)
Requires pip install 'env2llm[mqtt]' (paho-mqtt).
# Standalone bridge: listen for refresh, publish retained snapshots
ENV2LLM_MQTT_ENABLED=1 env2llm-mqtt bridge --project .
# One-shot publish
env2llm-mqtt publish --project . --probe-desktop
Topics (prefix env2llm):
| Topic | Retain | Zawartość |
|---|---|---|
{prefix}/{project}/registry |
yes | full SystemMapIR JSON |
{prefix}/{project}/registry/desktop |
yes | desktop probe slice |
{prefix}/{project}/events |
no | refresh/metadata events |
{prefix}/{project}/registry/refresh |
— | subscribe: trigger refresh |
| Variable | Default |
|---|---|
ENV2LLM_MQTT_ENABLED |
off |
ENV2LLM_MQTT_HOST |
127.0.0.1 |
ENV2LLM_MQTT_PORT |
1883 |
ENV2LLM_MQTT_TOPIC_PREFIX |
env2llm |
ENV2LLM_MQTT_USERNAME / PASSWORD |
optional |
Output formats
| Format | File | Use case |
|---|---|---|
doql.less |
environment.doql.less |
LLM + nlp2dsl orchestrator (default) |
yaml |
environment.yaml |
Tooling, human edit |
json |
environment.json |
APIs, CI |
markdown |
environment.md |
Prompt injection summary |
Environment variables
| Variable | Purpose |
|---|---|
NLP2DSL_BACKEND_URL |
Gateway service URL |
NLP2DSL_NLP_SERVICE_URL |
NLP orchestrator URL |
NLP2DSL_WORKER_URL |
Worker executor URL |
LLM_MODEL |
LLM provider/model id |
ENV2LLM_CONTEXT |
Path to generated map (set after bootstrap) |
ENV2LLM_DESKTOP_PROBE |
1 to attach live desktop snapshot (same as --probe-desktop) |
NLP2DSL_DOQL_CONTEXT |
Alias for nlp2dsl compatibility |
Secrets (*_KEY, *_TOKEN) are masked in output.
Extraction from nlp2dsl
This package contains the former nlp2dsl_sdk modules:
doql/— parse/render runtime contextir.py—SystemMapIRschema (env2llm.system_map.v1)generate.py,bridge.py,runtimes.py— introspection pipelineregistry.py— live registry refresh after workflow stepspolicy/— process and invoice policies fromexample-profiles.yaml
nlp2dsl can depend on env2llm and replace direct imports over time.
License
Licensed under Apache-2.0.
Metadata
Release files for env2llm 0.1.14
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| env2llm-0.1.14.tar.gz | 89.3 kB | Without provenance | Details for env2llm-0.1.14.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| env2llm-0.1.14-py3-none-any.whl | Python 3 | none | any | Details for env2llm-0.1.14-py3-none-any.whl |
Total release size: 188.5 kB
Release files / env2llm-0.1.14.tar.gz
| Download URL | env2llm-0.1.14.tar.gz |
|---|---|
| Size | 89.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c45c23f94e1e739e40a99941e33aec2712e11233091a06e5b2d9f42693808c4f
|
|
BLAKE2b-256 checksum How to use checksums |
b6596f4ccf1b2bcdd8d86eb1f7eceaee414a52ef3917e153bfe762c3f5e7092c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / env2llm-0.1.14-py3-none-any.whl
| Download URL | env2llm-0.1.14-py3-none-any.whl |
|---|---|
| Size | 99.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
45ceadc236dfd6f80f4bb8c0b368da596215f415d58121b3e3c0b64c02afc947
|
|
BLAKE2b-256 checksum How to use checksums |
141e4f938e500713c1207602b20f10b257904464abbcdf12f121d78f9e6677ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for env2llm 0.1.14
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.