velune-cli 0.9.1__tar.gz → 0.9.2__tar.gz

{velune_cli-0.9.1 → velune_cli-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velune-cli
-Version: 0.9.1
+Version: 0.9.2
 Summary: Local-first multi-model AI developer CLI — council-based agents, persistent memory, repository cognition
 Project-URL: Homepage, https://github.com/Surya-Hariharan/Velune-CLI
 Project-URL: Repository, https://github.com/Surya-Hariharan/Velune-CLI
@@ -226,52 +226,70 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: aiosqlite>=0.19.0
 Requires-Dist: anthropic>=0.18.0
-Requires-Dist: gitpython>=3.1.40
 Requires-Dist: httpx>=0.26.0
 Requires-Dist: keyring>=24.0.0
-Requires-Dist: lancedb>=0.5.0
 Requires-Dist: mcp>=1.0.0
 Requires-Dist: networkx>=3.2.0
 Requires-Dist: numpy>=1.24.0
 Requires-Dist: openai>=1.10.0
-Requires-Dist: opentelemetry-api>=1.22.0
-Requires-Dist: opentelemetry-exporter-otlp>=1.22.0
-Requires-Dist: opentelemetry-sdk>=1.22.0
 Requires-Dist: orjson>=3.9.0
 Requires-Dist: pathspec>=0.12.0
 Requires-Dist: platformdirs>=4.2.0
 Requires-Dist: prompt-toolkit>=3.0.0
 Requires-Dist: psutil>=5.9.0
-Requires-Dist: pyarrow>=14.0.0
 Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: pydantic>=2.5.0
-Requires-Dist: qdrant-client>=1.7.0
 Requires-Dist: rank-bm25>=0.2.2
 Requires-Dist: rich>=13.7.0
 Requires-Dist: structlog>=24.0.0
 Requires-Dist: tiktoken>=0.5.0
 Requires-Dist: toml>=0.10.2
-Requires-Dist: tree-sitter-go>=0.21.0
-Requires-Dist: tree-sitter-python>=0.21.0
-Requires-Dist: tree-sitter-rust>=0.21.0
-Requires-Dist: tree-sitter-typescript>=0.21.0
-Requires-Dist: tree-sitter>=0.21.0
 Requires-Dist: typer>=0.9.0
 Provides-Extra: all
 Requires-Dist: docker>=7.0.0; extra == 'all'
 Requires-Dist: gguf>=0.6.0; extra == 'all'
+Requires-Dist: gitpython>=3.1.40; extra == 'all'
+Requires-Dist: lancedb>=0.5.0; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.22.0; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp>=1.22.0; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.22.0; extra == 'all'
+Requires-Dist: pyarrow>=14.0.0; extra == 'all'
+Requires-Dist: qdrant-client>=1.7.0; extra == 'all'
+Requires-Dist: tree-sitter-go>=0.21.0; extra == 'all'
+Requires-Dist: tree-sitter-python>=0.21.0; extra == 'all'
+Requires-Dist: tree-sitter-rust>=0.21.0; extra == 'all'
+Requires-Dist: tree-sitter-typescript>=0.21.0; extra == 'all'
+Requires-Dist: tree-sitter>=0.21.0; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: bandit[toml]>=1.7.0; extra == 'dev'
 Requires-Dist: build>=1.0.0; extra == 'dev'
 Requires-Dist: pip-audit>=2.6.0; extra == 'dev'
 Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
 Requires-Dist: pyright>=1.1.350; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Requires-Dist: twine>=4.0.0; extra == 'dev'
 Provides-Extra: docker
 Requires-Dist: docker>=7.0.0; extra == 'docker'
 Provides-Extra: gguf
 Requires-Dist: gguf>=0.6.0; extra == 'gguf'
+Provides-Extra: git
+Requires-Dist: gitpython>=3.1.40; extra == 'git'
+Provides-Extra: parsing
+Requires-Dist: tree-sitter-go>=0.21.0; extra == 'parsing'
+Requires-Dist: tree-sitter-python>=0.21.0; extra == 'parsing'
+Requires-Dist: tree-sitter-rust>=0.21.0; extra == 'parsing'
+Requires-Dist: tree-sitter-typescript>=0.21.0; extra == 'parsing'
+Requires-Dist: tree-sitter>=0.21.0; extra == 'parsing'
+Provides-Extra: rag
+Requires-Dist: lancedb>=0.5.0; extra == 'rag'
+Requires-Dist: pyarrow>=14.0.0; extra == 'rag'
+Requires-Dist: qdrant-client>=1.7.0; extra == 'rag'
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-api>=1.22.0; extra == 'telemetry'
+Requires-Dist: opentelemetry-exporter-otlp>=1.22.0; extra == 'telemetry'
+Requires-Dist: opentelemetry-sdk>=1.22.0; extra == 'telemetry'
 Description-Content-Type: text/markdown
 
 # Velune
@@ -336,6 +354,34 @@ velune
 
 Get a free Groq key at <https://console.groq.com/keys> — no credit card.
 
+### Installing the `velune` command
+
+```bash
+pip install velune-cli
+velune --version
+```
+
+If your shell reports **`velune: command not found`** (or, on Windows,
+*"'velune' is not recognized…"*), the install succeeded but your Python
+scripts directory is not on `PATH`. Two reliable fixes:
+
+- **Recommended — install with [pipx](https://pipx.pypa.io/)** (isolated env, auto-managed PATH):
+
+  ```bash
+  pipx install velune-cli
+  ```
+
+- **Or run it as a module** (always works, no PATH changes needed):
+
+  ```bash
+  python -m velune --version
+  python -m velune            # start the REPL
+  ```
+
+On Windows, a plain `pip install` puts the launcher in a per-user
+`…\PythonXX\Scripts` folder; re-running the Python installer with **“Add
+Python to PATH”** checked (or using `pipx`) resolves it permanently.
+
 ---
 
 ## Hardware requirements
@@ -369,15 +415,23 @@ Velune features a modern, clean terminal interface designed for productivity:
 
 ## Providers
 
-| Provider              | Type  | Cost           | Models                               | Setup                            |
-|-----------------------|-------|----------------|--------------------------------------|----------------------------------|
-| Ollama                | Local | Free           | Any pulled model                     | Install Ollama, pull a model     |
-| Groq                  | Cloud | Free tier      | Llama 3.3 70B, Mixtral, Gemma2       | `velune setup` → enter key       |
-| OpenRouter            | Cloud | Pay-per-token  | 100+ models                          | `velune setup` → enter key       |
-| OpenAI                | Cloud | Pay-per-token  | GPT-4o, GPT-4o Mini                  | `velune setup` → enter key       |
-| Anthropic             | Cloud | Pay-per-token  | Claude Opus, Sonnet, Haiku           | `velune setup` → enter key       |
-| xAI (Grok)            | Cloud | Pay-per-token  | Grok 2, Grok 2 Mini                  | `velune setup` → enter key       |
-| Google Gemini         | Cloud | Free quota     | Gemini 2.0 Flash, 1.5 Pro/Flash      | `velune setup` → enter key       |
+| Provider     | Type  | Cost          | Models                                        | Setup                        |
+|--------------|-------|---------------|-----------------------------------------------|------------------------------|
+| Ollama       | Local | Free          | Any pulled model                              | Install Ollama, pull a model |
+| LM Studio    | Local | Free          | Any GGUF / MLX model                          | Launch LM Studio server      |
+| Groq         | Cloud | Free tier     | Llama 3.3 70B, Mixtral, Gemma2                | `velune setup` → enter key   |
+| OpenRouter   | Cloud | Pay-per-token | 100+ models                                   | `velune setup` → enter key   |
+| OpenAI       | Cloud | Pay-per-token | GPT-4o, GPT-4o Mini                           | `velune setup` → enter key   |
+| Anthropic    | Cloud | Pay-per-token | Claude Opus, Sonnet, Haiku                    | `velune setup` → enter key   |
+| xAI (Grok)   | Cloud | Pay-per-token | Grok 2, Grok 2 Mini                           | `velune setup` → enter key   |
+| Google       | Cloud | Free quota    | Gemini 2.0 Flash, 1.5 Pro/Flash               | `velune setup` → enter key   |
+| Together AI  | Cloud | Pay-per-token | Llama 3.3 70B, Qwen 2.5 Coder, DeepSeek R1    | `velune setup` → enter key   |
+| Fireworks AI | Cloud | Pay-per-token | DeepSeek R1, Qwen 2.5 Coder, Mixtral 8x22B    | `velune setup` → enter key   |
+| Mistral      | Cloud | Pay-per-token | Mistral Large, Codestral, Mixtral             | `velune setup` → enter key   |
+| DeepSeek     | Cloud | Pay-per-token | DeepSeek R1, DeepSeek Coder                   | `velune setup` → enter key   |
+| Cohere       | Cloud | Pay-per-token | Command R+, Command R                         | `velune setup` → enter key   |
+| NVIDIA NIM   | Cloud | Pay-per-token | Llama, Mistral, and other NIM models          | `velune setup` → enter key   |
+| HuggingFace  | Cloud | Free/paid     | Open models via Inference API                 | `velune setup` → enter key   |
 
 Keys are stored in your OS keyring — never in files, never in git.
 
@@ -385,46 +439,122 @@ Keys are stored in your OS keyring — never in files, never in git.
 
 ## Commands
 
-### CLI (before the REPL starts)
+### CLI (terminal, before the REPL)
 
 ```bash
-velune              # Start the persistent REPL session
-velune init         # Initialize Velune in a project
-velune setup        # Configure API keys securely (stored in OS keyring)
-velune doctor       # Check hardware, providers, dependencies
-velune models scan  # Discover all available local and cloud models
+# Core
+velune                    # Start the interactive REPL session
+velune chat               # Same as above (explicit form)
+velune run "<task>"       # Run a task non-interactively and exit
+velune ask "<question>"   # Ask a one-shot question and exit
+velune init               # Initialize Velune in a project directory
+
+# Workspace & sessions
+velune workspace init     # Index the current workspace
+velune workspace status   # Show index freshness and file counts
+velune workspace graph    # Render the workspace dependency graph
+velune workspace list     # List all known workspaces
+velune session list       # List saved chat sessions
+velune session delete <id>  # Delete a saved session
+
+# Setup & models
+velune setup              # Configure API keys (stored in OS keyring)
+velune models scan        # Discover all available local and cloud models
+velune models list        # List discovered models
+velune provider list      # Show all configured providers and their status
+velune provider add       # Add a new provider interactively
+velune config show        # Print effective velune.toml settings
+velune config set <k> <v> # Write a setting to velune.toml
+
+# Analytics & monitoring
+velune usage              # Token usage and estimated cost for recent sessions
+velune quota              # Check provider rate-limit and quota status
+velune health             # Check provider reachability and response time
+
+# Diagnostics
+velune doctor             # Run full environment health check
+velune logs               # View recent execution event log
+velune logs live          # Follow new events as they are written
+velune status             # Index freshness and workspace health snapshot
+velune pipeline "<query>" # Trace a retrieval query through the search pipeline
+velune daemon start       # Start the background Velune service
+velune daemon stop        # Stop the background service
+velune mcp serve          # Expose Velune's tool council as an MCP server
+velune mcp connect <url> <name>  # Connect to an external MCP server and list tools
+velune memory inspect     # Show memory tier sizes and record counts
+velune memory clear       # Clear all memory tiers for the current workspace
 ```
 
 ### Inside the REPL
 
 ```text
-/run <task>              Execute a task through the council
+─── Session ───────────────────────────────────────────────────────────────────
+/help                    Show all commands and their aliases
+/exit                    Exit Velune
+/clear                   Clear the terminal screen (context is preserved)
+/new [title]             Start a new conversation (project memory persists)
+/project [name|path]     Switch or manage project workspaces
+
+─── Council / Execution ───────────────────────────────────────────────────────
+/run <task>              Execute a task through the Reasoning Council
 /run --bg <task>         Submit task to background — prompt returns immediately
+/council <task>          Force full council tier regardless of task complexity
 /jobs                    List all background jobs (ID, status, phase, elapsed)
 /jobs cancel <id>        Cancel a running background job
 /dashboard               Live progress dashboard (jobs + alerts + provider health)
-/model                   Switch active model (arrow-key picker)
+
+─── Models ────────────────────────────────────────────────────────────────────
+/model [model-id]        Switch active model (arrow-key picker if no arg)
 /models                  List all available models
-/optimus                 Speed mode — instant tier, smallest model
-/godly                   Max power — full council, largest model
-/normal                  Return to balanced mode
-/mode                    Show current mode settings
-/memory                  Inspect memory tiers
-/session save            Save current session
-/session list            List saved sessions
-/session resume <id>     Resume a session
-/usage                   Token count and cost for this session
-/context                 Context window usage indicator
-/diff                    Show pending file changes
-/doctor                  Run health checks
-/help                    Show all commands
-/clear                   Clear screen and context
-/exit                    Exit Velune
+/pull [model-id]         Download an Ollama model with live progress
+/delete <model-id>       Delete a locally installed Ollama model
+/councilmodel            Assign specific models to Planner / Coder / Reviewer roles
+/bench [run]             View or run empirical model capability benchmarks
+
+─── Session Modes ─────────────────────────────────────────────────────────────
+/optimus                 Speed mode — instant tier, smallest model, 4k context
+/godly                   Max power — full council, largest model, 128k context
+/normal                  Return to balanced mode (auto-tier, 16k context)
+/mode                    Show current mode settings and active council tier
+
+─── Memory & Context ──────────────────────────────────────────────────────────
+/memory [clear|stats]    Inspect or clear memory tiers
+/session                 Interactive session picker (list / resume / save / export)
+/context                 Show context window usage for the current conversation
+/graph                   Render a tree of knowledge graph entities
+
+─── Diffs & Editing ───────────────────────────────────────────────────────────
+/diff                    Show uncommitted file changes from the last council run
+/undo                    Revert the last Velune-generated git commit (keeps changes staged)
+/hunk                    Toggle hunk-by-hunk review mode for edits
+/approve [safe|ask|block] Set tool/command approval gate
+
+─── Git Integration ───────────────────────────────────────────────────────────
+/push [--force]          Push current branch to remote origin
+/pr <title>              Create a pull request / merge request on GitHub or GitLab
+/issue <number>          Fetch a GitHub/GitLab issue and inject it as context
+/sandbox [docker|status] Show or switch sandbox type (subprocess or Docker)
+
+─── Code Intelligence ─────────────────────────────────────────────────────────
+/lint [file]             Lint a Python file and display diagnostic output
+/refactor <file>         Detect code smells and suggest refactoring targets
+/typify <file>           Suggest type hints for unannotated functions
+
+─── MCP & Plugins ─────────────────────────────────────────────────────────────
+/mcp [servers|tools|resources|connect|disconnect]  Inspect MCP servers and tools
+/plugin [list|enable|disable|reload|show]          Manage declarative plugins
+
+─── Diagnostics ───────────────────────────────────────────────────────────────
+/doctor                  Run environment health checks
+/config                  Show current configuration settings
+/stats                   Session statistics: tokens, cost, turns, uptime
+/history                 Show REPL command execution history
+/hooks                   List active lifecycle hooks and their configuration
 ```
 
-Tab-completion is active for all `/` commands and for model IDs (type `/model` then space to trigger).
+Tab-completion is active for all `/` commands and for model IDs (type `/model` then Space to trigger).
 
-The status bar shows `⚙ N bg` for active background jobs and `⚠ N` for unread proactive alerts. Alerts drain automatically after each prompt input and are printed as Rich panels above the input line.
+The status bar shows `⚙ N bg` for active background jobs and `⚠ N` for unread proactive alerts. Alerts drain automatically after each prompt and are printed as Rich panels above the input line.
 
 ---
 
@@ -433,20 +563,35 @@ The status bar shows `⚙ N bg` for active background jobs and `⚠ N` for unrea
 ```text
 velune/
 ├── cli/              REPL, slash commands, banner, autocomplete, session manager
-│   └── display/      Live dashboards (ProgressDashboard)
-├── providers/        Ollama, Groq, OpenAI, Anthropic, xAI, Google, OpenRouter
-├── cognition/        Council: Planner + Coder + Reviewer + Challenger + Synthesizer
+│   ├── commands/     Typer subcommands (workspace, session, models, doctor, mcp, …)
+│   ├── display/      Live dashboards and council pipeline view
+│   └── rendering/    Rich error panels and markdown streaming
+├── providers/        15 provider adapters (Ollama, Groq, OpenAI, Anthropic, Mistral, …)
+│   ├── adapters/     Per-provider inference + streaming implementations
+│   └── discovery/    Model catalog discovery for each provider
+├── cognition/        Council: Planner → Coder → Reviewer → Challenger → Synthesizer
+│   └── council/      DebateSession, CouncilRunner, per-role agents, tier classifier
 ├── memory/           5-tier: working → episodic → semantic → graph → lineage
 ├── proactive/        Alert store + watcher (CognitiveBus event subscriptions)
-├── repository/       AST indexing, dependency graph, .veluneignore
+├── repository/       AST indexing, import graph, blast-radius estimator, .veluneignore
+├── retrieval/        Hybrid retrieval: BM25 + vector + graph, cross-encoder reranker
 ├── execution/        Managed execution (allowlist + limits), diff preview, rollback
+│   └── edit_formats/ Diff format parsers (unified, search-replace, XML, JSON)
+├── analysis/         Code intelligence: linting, code-smell detection, type inference
+├── integrations/     GitHub and GitLab REST clients (push, PR, issues)
+├── hooks/            Lifecycle hook dispatcher and executor (pre/post tool events)
+├── observability/    Context reports, execution trace log, workspace dependency graph
+├── mcp/              MCP server + client; stdio / SSE / HTTP / WebSocket transports
 ├── hardware/         Hardware detection, tier classification, GPU probe
 ├── telemetry/        Token tracking, cost estimation, latency profiling
 ├── models/           Model registry, capability scoring, specializations
-├── context/          Context window tracking, extractive compression
+├── context/          Context window tracking, token counting, extractive compression
+├── orchestration/    ContextOrchestrationEngine — wires intent → council → output
 ├── core/             Loop detector, retry policy, task/job registry, error types
 ├── kernel/           Bootstrap, lifecycle coordinator, service container
-└── plugins/          Plugin loader & hook registry (experimental; unsandboxed, off by default)
+├── daemon/           Background Velune service (server + IPC transport)
+├── tools/            File-system, git, web-fetch, and terminal tool implementations
+└── plugins/          Declarative plugin loader, SKILL.md injection, hook wiring
 ```
 
 ---
@@ -481,13 +626,18 @@ Switch modes at any time mid-session. The prompt badge updates immediately.
 
 ## MCP integration
 
-Velune exposes an MCP server so that Claude Desktop and VS Code can call
-Velune's local model council as a tool — giving cloud-based editors access
-to local hardware without sending your code to a third party.
+Velune works as both an MCP **server** and an MCP **client**:
 
-Run `velune mcp --help` for the server commands. Outbound connections to
-external MCP servers are trust-gated — see the
-[MCP trust gating](SECURITY.md#mcp-trust-gating) section of the security policy.
+- **Server** (`velune mcp serve`) — exposes Velune's local tool council over
+  stdio so Claude Desktop, VS Code, and other MCP-capable editors can call
+  Velune's models without sending your code to a third party.
+- **Client** (`velune mcp connect <url> <name>`) — connects to any external MCP
+  server, lists its tools, and makes them available inside the REPL via `/mcp`.
+- **Transports** — stdio, SSE, HTTP, and WebSocket (`ws://` / `wss://`) are all
+  supported. Servers can also be declared in `.mcp.json` and loaded automatically.
+
+Outbound connections to external MCP servers are trust-gated — see
+[MCP trust gating](docs/SECURITY.md#mcp-trust-gating) in the security policy.
 
 ---
 
@@ -495,37 +645,48 @@ external MCP servers are trust-gated — see the
 
 Velune runs natively on Windows (supporting native command execution sandboxing, local Ollama integration, and keyring credentials). It can also run via WSL2 if preferred.
 
-See [WINDOWS.md](WINDOWS.md) for the complete native Windows and WSL2 setup guides.
-
 ---
 
 ## Project docs
 
 | Doc | What's inside |
 | --- | --- |
-| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Layering and import-boundary rules |
-| [SECURITY.md](SECURITY.md) / [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) | Security posture, trust boundaries, reporting |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup and contribution workflow |
+| [docs/SECURITY.md](docs/SECURITY.md) | Security posture, trust boundaries, reporting |
+| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | Dev setup and contribution workflow |
+| [docs/CHANGELOG.md](docs/CHANGELOG.md) | Full version history |
 
 ---
 
 ## Optional extras
 
-| Extra | Installs | Notes |
+The default install is intentionally lean and pure-python-friendly so it
+resolves fast and cleanly on every platform. Heavy or feature-specific
+dependencies live in extras — every feature that needs one **degrades
+gracefully** when it is absent (e.g. semantic search becomes a no-op, but
+lexical search and chat keep working).
+
+| Extra | Installs | Enables |
 | --- | --- | --- |
-| `[gguf]` | `gguf` library | GGUF file metadata reading — safe, no transitive risk |
-| `[llamacpp]` | `llama-cpp-python` | In-process GGUF inference. **Security advisory**: pulls in `diskcache ≤ 5.6.3` (unsafe pickle deserialization, no patched version). Only install in trusted, single-user environments. |
+| `[rag]` | `lancedb`, `pyarrow`, `qdrant-client` | Semantic memory + vector retrieval (large compiled wheels) |
+| `[parsing]` | `tree-sitter` + grammars | Tree-sitter source parsing for deep repository cognition |
+| `[telemetry]` | `opentelemetry-*` | Export spans/metrics to an OTLP collector |
+| `[git]` | `gitpython` | Git provider tools (push / PR / issue) and richer git context |
+| `[gguf]` | `gguf` | GGUF file metadata reading — safe, no transitive risk |
 | `[docker]` | `docker` | Docker sandbox for isolated code execution |
-| `[all]` | `[gguf,docker]` | Full install — deliberately excludes `[llamacpp]` due to the advisory above |
+| `[all]` | everything above | Full-featured install |
 | `[dev]` | Test/lint tools | For contributors |
 
 ```bash
-pip install velune-cli           # base install (Ollama, cloud providers)
-pip install 'velune-cli[gguf]'   # + GGUF metadata reading
-pip install 'velune-cli[all]'    # + GGUF + Docker sandbox
-pip install 'velune-cli[llamacpp]'  # + in-process GGUF inference (see advisory)
+pip install velune-cli            # lean base (Ollama, cloud providers, chat, lexical search)
+pip install 'velune-cli[rag]'     # + semantic memory & vector retrieval
+pip install 'velune-cli[all]'     # + every optional feature
 ```
 
+> The former `[llamacpp]` extra has been **permanently removed**:
+> `llama-cpp-python` pulls in `diskcache ≤ 5.6.3` (unsafe pickle
+> deserialization, no patched version). Install `llama-cpp-python` manually,
+> in a trusted single-user environment only, if you accept that risk.
+
 ---
 
 ## Contributing
@@ -541,8 +702,8 @@ pytest tests/ -q
 ```
 
 Report security issues via
-[GitHub Security Advisories](https://github.com/Surya-Hariharan/Velune-CLI/security/advisories/new) —
-not public issues.
+[GitHub Security Advisories](https://github.com/Surya-Hariharan/Velune-CLI/security/advisories/new)
+— not public issues.
 
 ---