nlp2uri

AI Cost Tracking

This project uses AI-generated code. Total cost: $3.7500 with 25 AI commits.

Generated on 2026-06-29 using openrouter/qwen/qwen3-coder-next

Python library and CLI — kompilator NL → URI → akcje OS dla operacji desktopowych.

Wejście (naturalny język):

• „otwórz VS Code w folderze ~/projekty/nlp2uri”
• „zrób screenshot aktywnego okna przeglądarki”
• „otwórz plik invoice-2025.pdf”

Wyjście:

1. Abstrakcyjny URI (RFC 3986, niezależny od OS)
2. Plan akcji OSAction[] — konkretne komendy per platforma
3. (Opcjonalnie) wykonanie lub payload MCP (text/uri-list)

Architektura

flowchart LR
    NL[Natural language] --> PARSE[parse_nl]
    PARSE --> INTENT[UriIntent + slots]
    INTENT --> BUILD[schemes/build]
    BUILD --> SPEC[UriSpec abstract URI]
    SPEC --> COMPILE[compile_uri_to_actions]
    COMPILE --> ACTIONS[OSAction plan]
    ACTIONS --> EXEC[execute_uri / MCP]

Warstwy

Abstrakcyjne schemy URI

Metadata native_uri zawiera deep-link IDE (vscode://file/...) gdy istnieje.

Konfiguracja (nlp2uri.yaml)

Domyślne ustawienia w pliku nlp2uri.yaml (auto-tworzony przy pierwszym uruchomieniu):

platform: auto          # auto | linux | darwin | windows
host_platform: linux  # ostatnio wykryty host (informacyjnie)
locale: null
dry_run: false
capture_dir: /tmp/nlp2uri-captures

Kolejność wyboru platformy: --platform → NLP2URI_PLATFORM → nlp2uri.yaml → auto-detect OS.

nlp2uri config show --json    # efektywna konfiguracja
nlp2uri config init           # zapisz domyślny nlp2uri.yaml

Ścieżki szukania configu: NLP2URI_CONFIG → ./nlp2uri.yaml → ~/.config/nlp2uri/nlp2uri.yaml.

Quick start

pip install -e ".[dev]"

# Platforma wykrywana automatycznie (bez --platform)
nlp2uri plan "otwórz vscode w folderze ~/github/semcod/nlp2uri" --json
nlp2uri resolve "zrób screenshot aktywnego okna przeglądarki" --json
nlp2uri execute "open firefox" --dry-run

Sterowanie IDE (Koru / koruide)

Warstwa planowania koru.control.v1 — NL → URI → drive przez socket koruide (nie wykonuje samodzielnie klawiatury; wymaga działającego daemona Koru + pluginu VSIX w IDE).

export KORU_AUTOPILOT_INSTANCE=cursor-main   # socket instancji Cursor

# Plan (NL → control plan + URI)
nlp2uri control plan "wyślij probe do cursor" --text "treść wiadomości" --json

# Wykonanie (plan + drive); workspace z live status gdy daemon działa
nlp2uri control execute "probe test" --text "hello" --json

# Tylko wklejenie (submit=false — stabilniejsze na Cursor Glass UI)
nlp2uri control execute "..." --text "..." --no-submit --json

# Indeks URI z autopilot status
nlp2uri control list-uris --json

Odpowiedniki w Koru: koru ide control plan|execute|list-uris oraz narzędzia MCP koru_ide_* (wymagają koru mcp-serve, nie są komendami shell).

Dla cursor + submit=true plan domyślnie ustawia strategy_hint=submit_alt_glass_first (kolejność submit w probe ladder).

Python API (service facade)

from nlp2uri import NLP2URIService
from nlp2uri.models import HostPlatform

svc = NLP2URIService.default()  # ładuje nlp2uri.yaml + auto-detect

plan = svc.from_prompt("otwórz vscode w folderze /tmp/foo")
print(plan.uri)                    # app://vscode/open?path=/tmp/foo
print(plan.actions[0].argv())      # ['xdg-open', 'vscode://file/tmp/foo']

payload = svc.handle_prompt("open firefox", dry_run=True)  # prompt → URI → run

Adaptery i integratory (reużywalne powierzchnie)

REST (POST /v1/plan)

curl -s -X POST http://127.0.0.1:8766/v1/plan \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"open firefox"}'

MCP (Cursor / Windsurf)

{ "mcpServers": { "nlp2uri": { "command": "nlp2uri-mcp" } } }

Tools: nlp2uri_plan, nlp2uri_resolve, nlp2uri_compile, nlp2uri_execute, nlp2uri_handle.

Shell

eval "$(nlp2uri shell export 'open firefox')"
echo "$NLP2URI_URI"    # app://firefox/open
$nlp2uri-run           # alias do skompilowanej komendy

Własny adapter

from nlp2uri.adapters.base import AdapterRequest
from nlp2uri.adapters.rest import RestAdapter

response = RestAdapter().dispatch("plan", {"prompt": "capture screen", "platform": "linux"})
print(response.data["uri"])

Standardy

Przydatne biblioteki

Testy i Docker

python -m pytest
docker compose build && docker compose run --rm nlp2uri-test
./examples/run-e2e.sh

Przykłady per kategoria: examples/README.md.

W Dockerze:

• unit: NLP → URI → OSAction
• integracja: rejestracja testapp:// przez .desktop + xdg-open (NLP2URI_INTEGRATION=1)

CQRS + ES + Protobuf (generowanie driverów i API)

Każdy typ URI ma własne drzewo commands / events / queries / driver / api:

cd schemas && make all          # scaffold + MCP schemas + driver stubs
cd schemas && make proto        # buf → Python gRPC + OpenAPI (wymaga buf CLI)

→ schemas/README.md · schemas/uri_cqrs_es.v1.md

Orchestracja ekosystemu (MCP, usługi, artefakty, getv)

Pełny przewodnik z przykładami uruchomienia i kontroli wielu backendów:

• docs/orchestration.md — URI + MCP + todomat + koru + scenariusze E2E
• docs/system_map_uri.v1.md — command://, artifact://, service://, …
• docs/getv_uri.v1.md — getv:// zmienne środowiskowe
• docs/mcp-tools.md — lista narzędzi nlp2uri-mcp

pip install -e ".[envmap]"    # getv + env2llm
nlp2uri list-getv --json
nlp2uri resolve-getv "GROQ_API_KEY" --json
nlp2uri list-system-uris --example-dir ~/github/wronai/nlp2dsl/examples/01-invoice --json

Plan rozwoju

docs/roadmap.md · docs/mcp-tools.md · CI: .github/workflows/ci.yml

Relacja z ekosystemem Semcod

• nlpshim — NLP → DSL / workflow
• nlp2uri — NLP → URI → akcje (desktop, getv, SystemMap, MCP)
• todomat — orchestrator MCP/HTTP (curllm, nlp2dsl, iterun, nlp2uri)
• koru — bridge MCP koru_desktop_uri_* + planfile tickets
• getv — zmienne env → getv:// URI

License

Licensed under Apache-2.0.