sangam 0.1.6__tar.gz

sangam-0.1.6/PKG-INFO

@@ -0,0 +1,494 @@
+Metadata-Version: 2.4
+Name: sangam
+Version: 0.1.6
+Summary: Intelligent type-checking based code analysis and generation CLI tool
+Author: sangam team
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: mypy>=0.900
+Requires-Dist: flask>=2.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# sangam
+
+> An **LLM harness** — a runtime and orchestration framework for coding agents
+> backed by large language models.
+
+`sangam` is being built as an **LLM harness**: a runtime that hosts
+LLM-driven coding agents, gives them isolated places to run code, and a typed set
+of tools to call. The design rests on four pieces —
+
+- **Runtime-agnostic execution** — a single `Executor` interface
+  (`RunSpec` in, `RunResult` out) with pluggable backends (Python venv, Node/nvm,
+  Docker/Podman, subprocess) so the agent never depends on a specific runtime.
+- **Typed tool registry** — each tool (read/write/edit files, run code,
+  type-check, run tests, search) exposes a JSON schema, letting the LLM act
+  through function-calling.
+- **Model client** — an LLM abstraction (`complete` / `chat` / `tools`) that can
+  talk to any provider: any OpenAI-compatible endpoint, or local models (Ollama /
+  LM Studio). When no API key is set it falls back to a local model automatically.
+- **Agent loop** — plan → act (call a tool) → observe (tests/lint/output) →
+  reflect, with conversation memory and resumable state.
+
+It started as a mypy-focused natural-language CLI, and those capabilities — mypy
+type analysis, file operations, and resumable task history — stay on as a
+built-in toolset and a working surface. Full architecture in
+[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+
+## Status
+
+The harness is under active construction: the core agent loop, multi-runtime
+executors, tool registry, model client, session store, headless HTTP API server,
+and VS Code extension are in place (Phases 1–4 complete). The local webapp and
+desktop app surfaces are the remaining roadmap. See [`todo.md`](todo.md) for the
+roadmap.
+
+**Available now**
+
+- Core engine split from the CLI surface (`core/engine.py`) — usable as a library.
+- `Executor` protocol + `RunSpec` / `RunResult` runtime contracts
+  (`core/runtime/base.py`).
+- **Multi-runtime executors** — pluggable backends behind the single `Executor`
+  interface:
+  - `VenvExecutor` (`core/runtime/venv.py`) — creates an isolated venv, installs
+    deps via pip, runs Python, captures stdout/stderr/exit.
+  - `NvmExecutor` (`core/runtime/nvm.py`) — runs JS/React via nvm + npm
+    (`nvm use`, `npm install`, run/build).
+  - `ShellExecutor` (`core/runtime/shell.py`) — runs native bash/zsh scripts and
+    one-off commands, auto-detecting the user's shell.
+  - `ContainerExecutor` (`core/runtime/container.py`) — runs arbitrary code in
+    Docker or Podman (image pull, run).
+  - `SubprocessExecutor` (`core/runtime/subprocess.py`) — plain subprocess
+    fallback backend.
+- **Runtime auto-detection** (`core/runtime/detect.py`) — maps a runtime name
+  (`python`/`venv`, `node`/`js`/`react`/`npm`, `shell`/`bash`/`zsh`,
+  `container`/`docker`/`podman`, `subprocess`/`direct`) to the matching backend.
+- **Environment registry** (`core/runtime/registry.py`) — records created venvs
+  and npm projects in `~/.sangam/environments.json` so they are reused across
+  runs instead of recreated.
+- **Sandbox Manager** (`core/sandbox.py`) — `SandboxPolicy` + `SandboxedExecutor`
+  wrapping any backend with filesystem scope (path-level validation, symlink
+  resolution), wall-clock timeouts (default/max clamping), network isolation
+  (proxy-env clearing), and POSIX resource limits (`cpu_time`, `fsize`,
+  `nofile`) via `resource_limit_preexec`.
+- **Agent loop** — `Agent` (`core/agent.py`) orchestrating `Planner`
+  (`core/planner.py`), `Memory` (`core/memory.py`), the `ToolRegistry`, and an
+  optional `ModelClient` in a plan → act → observe → reflect loop. Runs in a
+  deterministic mode when no model client is configured.
+- **Model client** (`core/model/`) — `ModelClient` protocol with
+  `OpenAIModelClient` (any OpenAI-compatible endpoint) and `LocalModelClient`
+  (local providers such as Ollama / LM Studio); credentials read from env/config.
+  `build_model_client(config)` picks the backend — the entry selected from the
+  model catalog when one is configured, otherwise OpenAI when an API key is set,
+  otherwise a local model (auto-detecting an available model from the running
+  server when `MODEL_NAME` is unset).
+- **Model catalog** (`core/model/catalog.py`) — `~/.sangam/models.yaml` is the
+  source of truth for which models sangam can use, following Continue's
+  `config.yaml` `models` shape (`name`, `provider`, `model`, optional `apiBase` /
+  `apiKey` / `roles` / `capabilities` / `defaultCompletionOptions` /
+  `requestOptions`). The active chat/agent model is the file's `default` entry,
+  else the first entry with role `chat`, else the first entry. `sangam models`
+  lists the configured entries merged with the ids advertised by probed local
+  runtimes (Ollama, LM Studio, and every configured `apiBase`) via `/v1/models`.
+  sangam never installs a model runtime.
+- **Typed tool registry** (`core/tools/`) — `read_file`, `write_file`,
+  `edit_file`, `list_files`, `search`, `run_python`, `run_js`, `run_container`,
+  `run_shell`, `install_deps`, `type_check`, `run_tests`, `suggest_fixes`, each
+  with a JSON schema for LLM function-calling.
+- **Session store** (`core/session_store.py`) — SQLite-backed sessions, messages,
+  model/token usage, and FTS5 search (`~/.sangam/sessions.db` by default).
+- **CLI subcommands** — `sangam agent "<goal>"`, `sangam models`,
+  `sangam exec --runtime <rt> <command>`, and `sangam serve` (headless HTTP API
+  server), plus the legacy single-task positional, REPL, and batch mode.
+- **Headless HTTP API server** (`sangam/server/`, Flask) — exposes the agent,
+  tools, runtimes, and session store over local HTTP with SSE streaming; the
+  single backend for the VS Code extension, local webapp, and desktop app.
+- **`install.sh`** — pulls sangam from GitHub `main`, installs it into a venv at
+  `~/.sangam/venv`, and runs the headless server. Before starting it probes for a
+  local model runtime (Ollama / LM Studio); if none is reachable it errors out
+  with "no model available/selected" rather than installing one.
+- mypy integration wired through the Executor backends — analyze a file or a
+  whole directory, JSON output parsing, and fix suggestions. Defaults to
+  `SubprocessExecutor` (`sys.executable -m mypy`); opt-in `use_venv=True` →
+  `VenvExecutor` with mypy installed; custom backend via `executor=`.
+- Regex-based task engine — natural-language commands mapped to file operations
+  and mypy analysis.
+- File operations — read, write, append, delete, list, and extract
+  functions/classes/imports.
+- JSONL task history with search.
+- Interactive REPL and batch mode.
+
+**Roadmap**
+
+- VS Code extension polish — chat panel, diagnostics, inline actions (extension
+  scaffolded and installable; UI activation pending a reload).
+- Local webapp — a single self-contained `index.html` (no build step) served on
+  localhost via Python (`sangam web`), talking to the headless server over HTTP.
+- Cross-platform desktop app — React UI over the Python core behind a native
+  shell, packaged for macOS (`.app`/`.dmg`) and Windows (`.exe`/`.msi`); reuses
+  the headless server as its backend.
+- Hardening — `doctor` capability probing, resumable `history`, runtime/model/
+  sandbox config, end-to-end sandbox limits, CI-ready non-interactive mode.
+
+## Local Webapp — Roadmap
+
+A **single-page webapp** is a zero-install surface for the same harness: one
+self-contained `index.html` (inline HTML + CSS + JS, no build step) served on
+localhost by a small Python static server and talking to the core over HTTP. It
+reuses the headless HTTPS API server from Phase 4 as its backend — another thin
+surface over the same core, not a separate engine.
+
+- **`webapp/index.html`** — the app shell (chat panel, file tree, diagnostics,
+  agent-step viewer, command palette, status bar) with an inline fetch-based
+  client to the core `serve` endpoint.
+- **`sangam web`** — starts the headless server and serves `index.html` on
+  localhost via Python's stdlib `http.server` (no extra deps); opens the default
+  browser.
+
+Full task breakdown in [`todo.md`](todo.md), Phase 6.
+
+## Desktop App — Roadmap
+
+A **cross-platform native desktop app** (macOS + Windows) is a target surface for
+the same harness. It keeps the existing **Python core** as the engine and adds a
+**React** UI on top — the same "core is a library, surfaces are thin" split used
+for the CLI and the VS Code extension:
+
+- **Python core** — the `sangam` package, frozen into a standalone per-OS
+  binary and run headless (`sangam serve`, the same HTTPS API server the VS
+  Code extension talks to). All agent/tool/runtime logic stays in Python.
+- **React UI** — a TypeScript + React frontend (chat panel, file tree,
+  diagnostics, agent-step viewer, command palette) that speaks HTTPS to the
+  core over localhost (optionally with TLS/cert configuration) — the same
+  wire protocol as the VS Code extension.
+- **Native shell** — a desktop wrapper that bundles the React build and spawns
+  the frozen Python core as a sidecar process. Ships a native `.app`/`.dmg` on
+  macOS and `.exe`/`.msi` on Windows (Tauri preferred for the OS-webview native
+  feel and small binary; Electron as a fallback).
+
+Planned packaging steps (full task breakdown in [`todo.md`](todo.md), Phase 7):
+
+1. **React UI** — scaffold `desktop-ui/` (Vite + TypeScript + React); build the
+   app shell and a typed HTTPS client to the core server.
+2. **Native shell** — scaffold `desktop-app/` (Tauri or Electron); configure it
+   to bundle and spawn the frozen Python core sidecar; wire frontend↔core IPC over
+   localhost HTTPS.
+3. **Python core packaging** — freeze the core with PyInstaller/Nuitka per OS
+   (including mypy + deps); confirm the headless `serve` entry point runs the
+   agent loop end-to-end.
+4. **macOS build** — universal `.app` (arm64 + x86_64), `.dmg` installer,
+   Developer ID code signing, Apple notarization + stapling, clean-launch test.
+5. **Windows build** — `.exe` + `.msi` installer (WiX/Tauri), WebView2 runtime
+   handling, code signing, clean-launch test.
+6. **Release CI** — GitHub Actions matrix (macOS arm64/x86_64, Windows x64):
+   build → sign → notarize (macOS) → package → attach to GitHub Releases.
+7. **Updates & polish** — auto-update, native menus/tray, first-run onboarding
+   (LLM creds + runtime detection), native window-state persistence.
+
+This builds on the headless HTTPS API server from Phase 4 — the desktop app is
+another thin surface over the same server, not a separate backend.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Requires Python >= 3.9 and `mypy>=0.900` (installed automatically).
+
+### Headless server install (`install.sh`)
+
+To install sangam and run it as a headless HTTP API server (the backend for the
+VS Code extension, local webapp, and desktop app), use `install.sh`:
+
+```bash
+./install.sh                 # install (or update) and run the server
+./install.sh --install-only  # install/update but do not start the server
+./install.sh --port 8765     # bind a specific port (default 8765)
+```
+
+`install.sh` pulls the source from GitHub `main`, creates a venv at
+`~/.sangam/venv`, installs the package, and runs `sangam serve`. The server
+needs a model to drive the agent, so before starting it `install.sh` **probes
+for a local model runtime**:
+
+- It queries the OpenAI-compatible `/v1/models` endpoint of **Ollama**
+  (`127.0.0.1:11434`) and then **LM Studio** (`127.0.0.1:1234`).
+- If a reachable endpoint advertises a model, the server is started using that
+  local model.
+- **sangam never installs a model runtime.** If no Ollama or LM Studio endpoint
+  is reachable, `install.sh` errors out with **"no model available/selected"**
+  and exits without starting the server.
+
+Override the probe with environment variables:
+
+```bash
+SANGAM_MODEL_ENDPOINT=http://127.0.0.1:12345 SANGAM_MODEL_NAME=bonsai-27b-mlx ./install.sh
+```
+
+`--install-only` installs without requiring a model.
+
+## Usage
+
+### CLI
+
+```bash
+# Run a single task
+sangam "read main.py"
+
+# Interactive mode
+sangam --interactive
+
+# Batch mode (from a file)
+sangam --batch tasks.txt
+
+# Verbose output
+sangam --verbose "type check src/"
+
+# Run the coding agent on a goal
+sangam agent "fix the type errors in src/ and run the tests"
+
+# List the models sangam can use (configured + discovered)
+sangam models
+sangam models --no-probe          # configured models only (no network)
+sangam models --json              # machine-readable listing
+sangam models --select fast-local # show the client for a named entry
+
+# Run a command in a chosen runtime
+sangam exec --runtime python "print('hello')"
+sangam exec --runtime node "console.log('hello')"
+sangam exec --runtime shell "ls -la"
+```
+
+### Model catalog (`~/.sangam/models.yaml`)
+
+`~/.sangam/models.yaml` is the source of truth for which models sangam can use.
+It follows Continue's `config.yaml` `models` shape:
+
+```yaml
+default: fast-local          # optional: the active chat/agent model
+
+models:
+  - name: fast-local
+    provider: ollama
+    model: qwen3:0.6b
+    apiBase: http://127.0.0.1:11434/v1
+    roles: [chat, agent]
+    capabilities: [tool_use]
+    defaultCompletionOptions:
+      temperature: 0.2
+      maxTokens: 2048
+    requestOptions:
+      timeout: 60  # seconds
+
+  - name: remote-gpt
+    provider: openai
+    model: gpt-4o-mini
+    apiKey: $OPENAI_API_KEY   # literal, $VAR, or ${VAR}
+    roles: [chat]
+```
+
+Selection order: the file's `default` entry, else the first entry with role
+`chat`, else the first entry. `sangam models` merges those configured entries
+with the model ids advertised by probed OpenAI-compatible runtimes (Ollama on
+`127.0.0.1:11434`, LM Studio on `127.0.0.1:1234`, and every configured
+`apiBase`) via `/v1/models`. Probing is read-only and best-effort — sangam never
+installs a model runtime. Override the catalog path with `SANGAM_MODELS_FILE` or
+`sangam models --catalog <path>`.
+
+`requestOptions` carries transport-level settings for the entry's HTTP calls.
+`timeout` (seconds) is honoured on every chat-completions request and overrides
+the `SANGAM_LLM_TIMEOUT` environment variable (which defaults the timeout to
+120 s). Invalid or non-positive values are ignored.
+
+### As a library
+
+```python
+from sangam import SangamCLI
+
+cli = SangamCLI()
+result = cli.execute_task("type check main.py")
+print(result)
+```
+
+The runtime contracts are importable for building backends:
+
+```python
+from sangam.core import Executor, RunSpec, RunResult
+```
+
+The agent harness is importable too:
+
+```python
+from sangam.core.agent import Agent
+from sangam.core.planner import Planner
+from sangam.core.tools import ToolRegistry
+from sangam.core.session_store import SessionStore
+from sangam.core.model import (
+    ModelClient,
+    OpenAIModelClient,
+    LocalModelClient,
+    build_model_client,
+)
+```
+
+## Project Structure
+
+```
+sangam/
+├── __init__.py            # Package exports
+├── cli/
+│   ├── main.py            # CLI surface (argparse, REPL, batch mode)
+│   └── commands/
+│       ├── agent.py       # sangam agent "<goal>"
+│       ├── models.py      # sangam models (list/select from models.yaml)
+│       ├── exec.py        # sangam exec --runtime <rt> <command>
+│       └── serve.py       # sangam serve (headless HTTP API server)
+├── core/
+│   ├── engine.py          # Core engine (config + logger + task engine wiring)
+│   ├── agent.py           # Agent orchestrator (plan → act → observe → reflect)
+│   ├── planner.py         # Goal → step plan
+│   ├── memory.py          # Conversation history + working-set
+│   ├── session_store.py   # SQLite sessions/messages/usage + FTS5 search
+│   ├── sandbox.py         # SandboxPolicy, SandboxedExecutor, resource limits
+│   ├── model/
+│   │   ├── __init__.py    # exports + build_model_client(config) factory
+│   │   ├── client.py      # ModelClient protocol + data contracts
+│   │   ├── catalog.py     # ~/.sangam/models.yaml catalog (load/select/probe)
+│   │   ├── model.py       # OpenAIModelClient (OpenAI-compatible)
+│   │   └── local.py       # LocalModelClient (local providers, e.g. Ollama/LM Studio)
+│   ├── tools/
+│   │   ├── registry.py    # Tool, ToolResult, ToolRegistry, JSON-schema gen
+│   │   ├── file_tools.py  # read_file, write_file, edit_file, list_files, search
+│   │   ├── exec_tools.py  # run_python, run_js, run_container, run_shell, install_deps
+│   │   └── type_check_tools.py # type_check, run_tests, suggest_fixes
+│   └── runtime/
+│       ├── base.py        # Executor protocol, RunSpec, RunResult contracts
+│       ├── venv.py        # VenvExecutor (isolated venv + pip + run Python)
+│       ├── nvm.py         # NvmExecutor (nvm/npm, JS/React)
+│       ├── shell.py       # ShellExecutor (native bash/zsh, detect_shell)
+│       ├── container.py   # ContainerExecutor (Docker/Podman)
+│       ├── subprocess.py  # SubprocessExecutor (plain subprocess fallback)
+│       ├── detect.py      # Runtime auto-detection → executor
+│       └── registry.py    # EnvironmentRegistry (~/.sangam/environments.json)
+├── server/                # Headless HTTP API server (Flask)
+│   ├── __init__.py        # Flask app exports
+│   └── http_api.py        # create_app factory, per-request SessionStore, SSE
+├── task_engine.py         # Natural-language task parsing and execution
+├── sangam_integration.py  # mypy subprocess wrapper and JSON parsing
+├── file_ops.py            # File read/write/analysis operations
+├── logger.py              # Logging and JSONL task history
+├── config.py              # Configuration management
+└── mypy_cli.py            # Backward-compatible shim (re-exports cli/main + core)
+tests/                     # pytest test suite
+docs/                      # Architecture docs
+```
+
+## Running Tests
+
+The test suite uses [pytest](https://docs.pytest.org/). Install it if you don't have it:
+
+```bash
+pip install pytest
+```
+
+Then run the tests from the project root:
+
+```bash
+python -m pytest tests/ -v
+```
+
+Or with the `pytest` command directly:
+
+```bash
+pytest tests/
+```
+
+To run a single test file:
+
+```bash
+pytest tests/test_file_ops.py
+```
+
+To run a single test:
+
+```bash
+pytest tests/test_file_ops.py::TestFileOperations::test_read_file
+```
+
+The mypy integration tests mock the `mypy` subprocess, so they run even if mypy is not installed.
+
+## Simulation Tests
+
+Beyond the unit tests, `sangam` ships a **live simulation suite** that drives
+real runtimes end-to-end — no mocking of venv, subprocess, or the model
+endpoint. These live in `tests/simulation/` and are tagged with the
+`simulation` pytest marker, so they are excluded from the default run and only
+execute when requested.
+
+**What they cover**
+
+- `test_sim_venv_executor.py` — `VenvExecutor`: real venv creation (idempotent
+  `prepare`), real pip installs of a local package, venv-vs-subprocess isolation
+  proof, `run_python` convenience + env passthrough, live timeout enforcement,
+  failure reporting, and sandbox-wrapped runs (allowed/disallowed cwd, proxy
+  clearing).
+- `test_sim_shell_executor.py` — `ShellExecutor`: real-life `.sh` fixture
+  scripts (`simulate_release.sh` release pipeline, `analyze_logs.sh` log
+  analysis), one-off commands (pipelines, env, stdin, cwd), multi-line
+  `run_script` constructs, live timeouts, and sandbox policy.
+- `test_sim_subprocess_executor.py` — `SubprocessExecutor`: real command
+  execution (PATH/absolute resolution, mypy `--version`), failure reporting,
+  stdin/env/cwd, live timeouts, sandbox enforcement (filesystem scope, default/
+  max timeout clamping, proxy clearing), and **live POSIX resource-limit
+  enforcement** (`fsize`, `cpu_time`, `nofile`).
+- `test_sim_openai_endpoint.py` — a real OpenAI-compatible endpoint (the
+  device's local Ollama at `http://localhost:11434/v1`, standing in for any
+  provider the future `ModelClient` will target): `/v1/models`, chat
+  completions (single/multi-turn, system prompt, usage accounting), SSE
+  streaming, tool-calling, and error-path validation.
+
+**Fixtures** — real-life usage-case files live in `tests/fixtures/real_life/`
+(`simulate_release.sh`, `analyze_logs.sh`, `report_env.py`, sample logs, and a
+small `src/` tree). The endpoint and model are overridable via
+`SANGAM_OLLAMA_BASE_URL` and `SANGAM_OLLAMA_MODEL` (default `qwen3:0.6b`).
+
+**Running the suite**
+
+```bash
+# All live simulation tests
+pytest -m simulation
+
+# A single backend
+pytest -m simulation tests/simulation/test_sim_shell_executor.py
+
+# Verbose runner with per-test traces, live logs, and a timestamped log file
+./run_live_tests.sh
+```
+
+The endpoint tests **skip** (never fail) when Ollama is not reachable or no
+model is pulled, so the default suite stays green without it. A full run is
+~60 tests (221 passed / 1 skipped across the whole suite; `pytest -m "not
+simulation"` = 162 for CI).
+
+## License
+
+MIT