virtual-context 0.3.2__tar.gz → 0.3.4__tar.gz

{virtual_context-0.3.2 → virtual_context-0.3.4}/.gitignore

@@ -22,6 +22,11 @@ build/
 .virtualcontext/
 .virtualcontext-*/
 
+# Local scripts / experiments
+scripts/*
+!scripts/install.ps1
+!scripts/install.sh
+
 # Config files (may contain API keys)
 virtual-context-*.yaml
 !virtual-context.yaml.example

virtual_context-0.3.4/CLAUDE.md

@@ -0,0 +1,16 @@
+# Virtual Context
+
+## Environment
+
+Always run tests with `.venv/bin/pytest`. Always use `.venv/bin/python` for any Python commands. The project venv must be used for all operations.
+
+```bash
+# Run tests
+.venv/bin/pytest tests/
+
+# Run a specific test
+.venv/bin/pytest tests/test_foo.py -k "test_name"
+
+# Install dependencies
+.venv/bin/pip install -e ".[dev]"
+```

{virtual_context-0.3.2 → virtual_context-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: virtual-context
-Version: 0.3.2
+Version: 0.3.4
 Summary: OS-style virtual memory for LLM session context management
 Project-URL: Homepage, https://virtual-context.com
 Project-URL: Repository, https://github.com/virtual-context/virtual-context
@@ -69,10 +69,11 @@ Your client sets `contextWindow: 20000000` (20 million). Your model's real windo
 
 Virtualizing the context window has many advantages:
 
-- **Compression**: Topic-level summarization with structured fact extraction. A 937K-token payload collapses to ~65K. Everything is stored, indexed, and recoverable at full fidelity.
+- **Compression**: Topic-level summarization with structured fact extraction, tool chain stubbing (52 tool call/response pairs collapse to a single retrievable stub), and image scaling (a 391KB base64 screenshot becomes ~40KB, cutting payload size by ~90%). A 937K-token payload collapses to ~65K. Everything is stored, indexed, and recoverable at full fidelity.
 - **Memory**: Your agent recalls what the user said at turn 12 when it reaches turn 1000. Facts, preferences, and decisions persist across the full conversation, not just what fits in the raw window.
 - **Reasoning quality**: A curated 60K window of dense signal produces measurably better answers than a raw 200K window full of noise. The model reasons over what matters, not over everything.
 - **Cost**: Smaller payloads, fewer tokens billed. A conversation running at a 1M-token virtual window regularly produces 60-90K actual payloads, a fraction of the raw cost. The payload is organized to maximize prompt cache hits, so even compressed conversations achieve significant caching in most cases.
+- **Cache-Aware Payload Compaction**: VC compacts conversations in the background but defers rewriting the request payload until the provider's prompt cache has expired or the context window is nearly full. This preserves the byte-identical prefix that providers use for cache hits, giving you compaction savings without sacrificing cached-token discounts. You get full compaction savings when they're free and full cache savings when they matter.
 - **Collaboration**: VCATTACH lets agents share memory across platforms and sessions. Custom agents, local tools, and API clients can all work from the same context. Multiple agents collaborate through shared memory. Conversations survive client restarts, platform switches, and session boundaries.
 
 This is what makes virtual-context fundamentally different from memory systems that bolt a vector database onto your LLM. Those systems are *additive*: they retrieve chunks and compete for the context window your agent is working in right now. They do nothing to evict or curate what's already there.
@@ -223,7 +224,7 @@ proxy:
 
 ```bash
 virtual-context daemon install --upstream https://api.anthropic.com
-virtual-context onboard --wizard --install-daemon
+virtual-context onboard --install-daemon
 ```
 
 Daemon lifecycle: `daemon status | start | stop | restart | uninstall`
@@ -406,7 +407,7 @@ virtual-context transform -m "What about auth?"      # tag + retrieve + assemble
 virtual-context compact -i msgs.json                 # manual compaction
 virtual-context aliases list|suggest|add             # tag alias management
 virtual-context init coding                          # create config from preset
-virtual-context onboard [--wizard]                   # guided setup
+virtual-context onboard [--upstream URL]              # guided setup (interactive wizard)
 virtual-context daemon install|status|start|stop     # background service
 virtual-context config validate                      # check config syntax
 virtual-context telemetry [--verbose] [--json]       # cost, tokens, timing
@@ -573,7 +574,7 @@ cd virtual-context
 python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 python -m pytest tests/ -v --ignore=tests/ollama    # ~1500 unit tests
-python -m pytest tests/ollama/ -v -m ollama          # integration (requires Ollama)
+python -m pytest tests/ollama/ -v -m ollama          # integration (requires local LLM)
 ```
 
 ## License

{virtual_context-0.3.2 → virtual_context-0.3.4}/README.md

@@ -22,10 +22,11 @@ Your client sets `contextWindow: 20000000` (20 million). Your model's real windo
 
 Virtualizing the context window has many advantages:
 
-- **Compression**: Topic-level summarization with structured fact extraction. A 937K-token payload collapses to ~65K. Everything is stored, indexed, and recoverable at full fidelity.
+- **Compression**: Topic-level summarization with structured fact extraction, tool chain stubbing (52 tool call/response pairs collapse to a single retrievable stub), and image scaling (a 391KB base64 screenshot becomes ~40KB, cutting payload size by ~90%). A 937K-token payload collapses to ~65K. Everything is stored, indexed, and recoverable at full fidelity.
 - **Memory**: Your agent recalls what the user said at turn 12 when it reaches turn 1000. Facts, preferences, and decisions persist across the full conversation, not just what fits in the raw window.
 - **Reasoning quality**: A curated 60K window of dense signal produces measurably better answers than a raw 200K window full of noise. The model reasons over what matters, not over everything.
 - **Cost**: Smaller payloads, fewer tokens billed. A conversation running at a 1M-token virtual window regularly produces 60-90K actual payloads, a fraction of the raw cost. The payload is organized to maximize prompt cache hits, so even compressed conversations achieve significant caching in most cases.
+- **Cache-Aware Payload Compaction**: VC compacts conversations in the background but defers rewriting the request payload until the provider's prompt cache has expired or the context window is nearly full. This preserves the byte-identical prefix that providers use for cache hits, giving you compaction savings without sacrificing cached-token discounts. You get full compaction savings when they're free and full cache savings when they matter.
 - **Collaboration**: VCATTACH lets agents share memory across platforms and sessions. Custom agents, local tools, and API clients can all work from the same context. Multiple agents collaborate through shared memory. Conversations survive client restarts, platform switches, and session boundaries.
 
 This is what makes virtual-context fundamentally different from memory systems that bolt a vector database onto your LLM. Those systems are *additive*: they retrieve chunks and compete for the context window your agent is working in right now. They do nothing to evict or curate what's already there.
@@ -176,7 +177,7 @@ proxy:
 
 ```bash
 virtual-context daemon install --upstream https://api.anthropic.com
-virtual-context onboard --wizard --install-daemon
+virtual-context onboard --install-daemon
 ```
 
 Daemon lifecycle: `daemon status | start | stop | restart | uninstall`
@@ -359,7 +360,7 @@ virtual-context transform -m "What about auth?"      # tag + retrieve + assemble
 virtual-context compact -i msgs.json                 # manual compaction
 virtual-context aliases list|suggest|add             # tag alias management
 virtual-context init coding                          # create config from preset
-virtual-context onboard [--wizard]                   # guided setup
+virtual-context onboard [--upstream URL]              # guided setup (interactive wizard)
 virtual-context daemon install|status|start|stop     # background service
 virtual-context config validate                      # check config syntax
 virtual-context telemetry [--verbose] [--json]       # cost, tokens, timing
@@ -526,7 +527,7 @@ cd virtual-context
 python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 python -m pytest tests/ -v --ignore=tests/ollama    # ~1500 unit tests
-python -m pytest tests/ollama/ -v -m ollama          # integration (requires Ollama)
+python -m pytest tests/ollama/ -v -m ollama          # integration (requires local LLM)
 ```
 
 ## License

{virtual_context-0.3.2 → virtual_context-0.3.4}/models.yaml

@@ -197,10 +197,10 @@ models:
     aliases: [mimo, mimo-flash]
 
   # ---------------------------------------------------------------------------
-  # Local / Ollama (free)
+  # Local LLM (free)
   # ---------------------------------------------------------------------------
   qwen3:4b-instruct-2507-fp16:
-    provider: ollama
+    provider: local
     input_per_mtok: 0.00
     output_per_mtok: 0.00
     context_window: 32768

{virtual_context-0.3.2 → virtual_context-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "virtual-context"
-version = "0.3.2"
+version = "0.3.4"
 description = "OS-style virtual memory for LLM session context management"
 readme = "README.md"
 license = "AGPL-3.0-or-later"
@@ -71,6 +71,7 @@ exclude = [
 artifacts = [
     "virtual_context/proxy/static/*",
     "virtual_context/data/anthropic-tokenizer/tokenizer.json",
+    "virtual_context/data/models.yaml",
 ]
 
 [tool.hatch.build.targets.wheel]

virtual_context-0.3.4/scripts/install.ps1

@@ -0,0 +1,64 @@
+$ErrorActionPreference = "Stop"
+
+$PackageName = "virtual-context"
+
+function Write-Info {
+    param([string]$Message)
+    Write-Host "[virtual-context] $Message"
+}
+
+function Test-Command {
+    param([string]$Name)
+    return [bool](Get-Command $Name -ErrorAction SilentlyContinue)
+}
+
+function Install-WithPipx {
+    if (Test-Command pipx) {
+        Write-Info "Installing with pipx..."
+        pipx install --force $PackageName
+        return $true
+    }
+
+    if (Test-Command py) {
+        Write-Info "pipx not found. Installing pipx with py -m pip --user..."
+        py -m pip install --user pipx
+        py -m pipx ensurepath | Out-Null
+        if (py -m pipx --version) {
+            py -m pipx install --force $PackageName
+            return $true
+        }
+    }
+
+    return $false
+}
+
+function Install-WithPipUser {
+    if (Test-Command py) {
+        Write-Info "Falling back to py -m pip --user install..."
+        py -m pip install --user --upgrade $PackageName
+        return $true
+    }
+    return $false
+}
+
+Write-Info "Installing $PackageName"
+
+if (-not (Install-WithPipx)) {
+    if (-not (Install-WithPipUser)) {
+        throw "Installation failed: need Python launcher 'py' and pip, or pipx"
+    }
+}
+
+if (-not (Test-Command virtual-context)) {
+    Write-Info "Installed, but 'virtual-context' is not on PATH yet."
+    Write-Info "Open a new PowerShell session, then run: virtual-context --help"
+    exit 0
+}
+
+Write-Info "Install complete"
+Write-Info "Next:"
+Write-Info "  1) virtual-context onboard --wizard    # guided setup (config + proxy instances + daemon)"
+Write-Info "  Or manual setup:"
+Write-Info "  1) virtual-context init coding"
+Write-Info "  2) virtual-context config validate"
+Write-Info "  3) virtual-context proxy --upstream https://api.anthropic.com"

virtual_context-0.3.4/scripts/install.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE_NAME="virtual-context"
+
+log() {
+  printf "[virtual-context] %s\n" "$*"
+}
+
+need_cmd() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+install_with_pipx() {
+  if need_cmd pipx; then
+    log "Installing with pipx..."
+    pipx install --force "$PACKAGE_NAME"
+    return 0
+  fi
+
+  if need_cmd python3; then
+    log "pipx not found. Installing pipx via python3 --user..."
+    python3 -m pip install --user pipx
+    python3 -m pipx ensurepath >/dev/null 2>&1 || true
+
+    # shellcheck disable=SC2016
+    log 'If this is your first pipx install, restart your shell and rerun this script.'
+    if python3 -m pipx --version >/dev/null 2>&1; then
+      python3 -m pipx install --force "$PACKAGE_NAME"
+      return 0
+    fi
+  fi
+
+  return 1
+}
+
+install_with_pip_user() {
+  if ! need_cmd python3; then
+    return 1
+  fi
+  log "Falling back to python3 -m pip --user install..."
+  python3 -m pip install --user --upgrade "$PACKAGE_NAME"
+}
+
+main() {
+  log "Installing $PACKAGE_NAME"
+
+  if install_with_pipx; then
+    :
+  elif install_with_pip_user; then
+    :
+  else
+    log "Installation failed: need python3 (and pip) or pipx"
+    exit 1
+  fi
+
+  if ! need_cmd virtual-context; then
+    log "Installed, but 'virtual-context' is not on PATH yet."
+    log "Open a new shell, then run: virtual-context --help"
+    exit 0
+  fi
+
+  log "Install complete"
+  log "Next:"
+  log "  1) virtual-context daemon install --upstream https://api.anthropic.com"
+  log "     (creates ~/.virtualcontext/ with config + data, installs + starts daemon)"
+  log "  Or: virtual-context onboard --wizard    # interactive multi-instance setup"
+}
+
+main "$@"