Initial Commit.

Author: Tolin Simpson

.cursor/plans/vcs_pseudo-code_interpreter_c5fd4cea.plan.md

@@ -0,0 +1,38 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Build vector databases
+        run: python vc-database/vcdb.py
+
+      - name: Demo search
+        run: python vc-database/vcdb.py --demo-search add numbers
+
+      - name: Python tests
+        run: python -m unittest discover -s vc-database -p "test_*.py" -v
+
+      - name: JS interpreter smoke test
+        run: node vcs-js/smoke-test.js
+
+      - name: JS tests
+        run: node vcs-js/tests/test_vcs.js
+

.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyd
+.Python
+
+# Virtualenvs
+.venv/
+venv/
+ENV/
+env/
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# OS / editor
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+.vscode/
+.idea/
+
+# Build / cache
+dist/
+build/
+out/
+coverage/
+

.gitignore

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+- (placeholder)
+

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Code of Conduct
+
+This project follows a simple standard: be respectful and constructive.
+
+Unacceptable behavior includes harassment, discrimination, threats, or sustained disruption.
+
+Maintainers may remove content or restrict participation that violates this standard.
+

CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Contributing
+
+This repository is currently **proprietary** (see `LICENSE.txt`). External contributions may not be accepted unless explicitly requested by the maintainers.
+
+If you want to help, the most useful contributions are:
+
+- Clear bug reports (include OS, versions, and reproduction steps)
+- Feature requests with concrete use-cases
+- Documentation improvements (typos, clarifications, examples)
+
+## Development guidelines
+
+- Keep `.vcs` compatibility stable (avoid reordering `vc-database/source/*.txt` entries).
+- Prefer small, focused changes with clear commit messages.
+- Add/extend tests when changing interpreter parsing/execution or vector search behavior.
+

CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# LLMVCS - LLM-Friendly Vectorized Code Stack Interpreter
+
+A modular, cross-language stack-based interpreter with semantic search capabilities.
+
+## Architecture
+
+```
+LLMVCS/
+├── vc-database/
+│   ├── source/     # Human-readable function definitions (.txt)
+│   ├── vectors/    # Vectorized outputs (.dat)
+│   └── vcdb.py     # Converts .txt → .dat and semantic search via TF-IDF (pure Python)
+├── vcs-js/         # Working JavaScript interpreter + compiler for .vcs
+│   ├── modules/    # Opcode modules (registered into the engine by moduleId)
+│   ├── stacks/     # Example .vcs programs
+│   └── vcs.js      # Single-file interpreter + compiler (JS)
+├── vcs-pseudo/     # Language-agnostic single-file interpreter specification
+│   └── vcs.pseudo
+```
+
+## Database
+
+### Source Files (`vc-database/source/*.txt`)
+
+Define operations in a simple format. Each entry separated by `\n\n` gets a sequential ID (0, 1, 2...).
+
+```
+add | Adds two types.
+
+subtract | Subtracts two types.
+
+multiply | Multiplies two types.
+```
+
+### Vectorization
+
+```bash
+cd vc-database
+python vcdb.py
+```
+
+Converts `.txt` files to `.dat` (JSON TF-IDF vectors) for semantic search.
+
+### Vector Search
+
+```python
+# Run this from inside `vc-database/`
+from vcdb import search
+
+results = search(
+    query="how to add numbers",
+    db_path="vectors/llmvcc-ops.dat",
+    top_k=3,
+)
+```
+
+## .vcs File Format
+
+Compact instruction format: `moduleId.methodId(params)`
+
+```vcs
+// Comments start with //
+0.13("Hello")       // print("Hello")
+0.11("x", 10)       // store("x", 10)
+0.17($x, 5)         // add($x, 5)
+0.5(0, true)        // jump_if(0, true)
+0.1()               // stop()
+```
+
+### Note on naming
+
+The current JS compiler (`vcs-js/vcs.js`) parses numeric `moduleId.methodId(...)` only. Named variants like `math.add(...)` are a potential extension, but are not implemented today.
+
+### Parameters
+
+- Numbers: `10`, `3.14`
+- Strings: `"hello"`, `'world'`
+- Booleans: `true`, `false`
+- Variables: `$varName`
+
+## Compatibility policy (stable IDs)
+
+LLMVCS relies on **stable numeric IDs**:
+
+- **Module IDs** are derived from the entry order in `vc-database/source/vector-categories.txt`
+- **Operation IDs / opcodes** are derived from the entry order in each `vc-database/source/*.txt`
+
+Reordering existing entries is a breaking change. Prefer only appending new entries to preserve old IDs.
+
+Recommended convention (optional): add a format version header to `.vcs` programs:
+
+```text
+// vcs:1
+```
+
+
+## Adding New Modules
+
+1. Create `vc-database/source/your-module.txt` with operations
+2. Add entry to `vc-database/source/vector-categories.txt`
+3. Implement the module in your interpreter (for JS, add a class under `vcs-js/modules/` with `eval(methodId, args, ctx, regs, strings)`)
+4. Register it into the engine at the desired `moduleId`
+5. Run `vcdb.py` to update the search index
+
+## Cross-Language Compatibility
+
+The interpreter design is intended to be portable across languages. The authoritative portability reference is `vcs-pseudo/vcs.pseudo`, and `vcs-js/` is a working reference implementation.

DOCUMENTATION.md

@@ -0,0 +1,17 @@
+Copyright (c) 2026
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary.
+No permission is granted to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, in whole or in part, without
+prior written permission from the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

LICENSE.txt

@@ -0,0 +1,32 @@
+# VCS File Generator
+
+Convert user tasks into `.vcs` files using the vector database MCP tool.
+
+## Process
+
+1. **Search categories**: `search(query, "vc-database/vectors/vector-categories.dat", top_k=2)` → get relevant module names
+2. **Search operations**: `search(query, "vc-database/vectors/<module>.dat", top_k=5)` → get opcodes
+3. **Generate .vcs**: Use `MODULE_ID.OPCODE(params)` format
+
+## .vcs Syntax
+
+```
+// Comments start with //
+MODULE_ID.OPCODE(param1, param2)
+```
+
+- Strings: `"text"`
+- Variables: `$varname`
+- Numbers/booleans: literals
+
+## Example
+
+Task: "Print hello then stop"
+
+```vcs
+// Print and stop
+0.13("Hello")
+0.1()
+```
+
+Output the .vcs file with inline comments explaining each line.

Prompt.md

@@ -0,0 +1,119 @@
+# LLMVCS
+
+LLMVCS reduces LLM agent token costs by turning “what to do” into tiny, stable instruction references that a deterministic interpreter can execute.
+
+Instead of having the LLM repeatedly re-describe common operations in natural language, you define those operations once in human-readable `.txt` catalogs, index them for semantic search, and then have the LLM output compact `.vcs` programs that reference operations by numeric IDs.
+
+## The algorithm (in simple terms)
+
+1. **Write operations once (human-readable)**  
+   Put reusable operations in `.txt` files under `vc-database/source/`. Each entry is separated by a blank line and has a stable position (its index).
+
+2. **Build a searchable index**  
+   Run `vc-database/vcdb.py` to convert the `.txt` catalogs into `.dat` files under `vc-database/vectors/` (JSON TF‑IDF vectors).
+
+3. **At runtime: semantic lookup (via MCP in your system)**  
+   When a user asks for something, the agent calls your vector-search tool to retrieve the best matching **module** and **operation** IDs.
+
+4. **Emit low-token `.vcs`**  
+   The agent outputs a tiny instruction stack like `moduleId.opcode(params)` instead of verbose code.
+
+5. **Execute `.vcs` in an embedded interpreter**  
+   A small, language-agnostic, single-file interpreter executes the instructions deterministically inside your app.
+
+## Why this reduces tokens
+
+- **Knowledge is stored once** in the operation catalogs (`.txt`) and searchable indexes (`.dat`).
+- **Agent output stays small** because `.vcs` references operations numerically (stable IDs) instead of repeating long explanations or boilerplate.
+
+## Repository layout
+
+- `vc-database/` — builds/searches `.dat` indexes from human-readable `.txt` sources (zero-dependency Python).
+- `vcs-js/` — a working JavaScript interpreter + `.vcs` compiler and example stacks.
+- `vcs-pseudo/` — the language-agnostic pseudo-code spec used to generate new interpreters.
+
+## `.vcs` format (vectorized code stack)
+
+Each line is an instruction:
+
+```text
+MODULE_ID.OPCODE(param1, param2, ...)
+```
+
+- Comments start with `//` (and `#` is also ignored by the JS compiler).
+- Variables are referenced as `$name` (resolved to a register slot at compile time).
+- Strings can be `"double quoted"` or `'single quoted'`.
+- Labels are supported by the JS interpreter for authoring convenience:
+  - define: `:loop`
+  - jump to: `@loop` (compile-time label reference)
+
+Example:
+
+```text
+// x = 10
+0.11("x", 10)
+// x = x + 5
+0.17($x, 5)
+0.11("x", $result)
+// print x, then stop
+0.13($x)
+0.1()
+```
+
+## Quickstart
+
+### 1) Build the vector databases (`.dat`)
+
+From the repo root:
+
+```bash
+python vc-database/vcdb.py
+```
+
+This reads `vc-database/source/*.txt` and writes `vc-database/vectors/*.dat`.
+
+To demo search output:
+
+```bash
+python vc-database/vcdb.py --demo-search add numbers
+```
+
+### 2) Run the JavaScript interpreter smoke test
+
+From the repo root:
+
+```bash
+node vcs-js/smoke-test.js
+```
+
+### 3) (Optional) Run the browser demo
+
+Open `vcs-js/index.html` in a browser.
+
+## Porting to other languages
+
+Use the single-file interpreter spec in `vcs-pseudo/vcs.pseudo` as the authoritative reference. New-language interpreters can be generated by an LLM by following that spec (data structures, compiler, engine loop, module interface).
+
+## Compatibility: stable IDs (important)
+
+LLMVCS relies on **stable numeric IDs**:
+
+- **Module IDs** come from the entry order in `vc-database/source/vector-categories.txt`.
+- **Operation IDs / opcodes** come from the entry order in each `vc-database/source/*.txt` module catalog.
+
+This means reordering entries is a breaking change. Prefer only appending new entries to preserve old IDs.
+
+Recommended convention (optional): put a version header at the top of `.vcs` programs, for example:
+
+```text
+// vcs:1
+```
+
+## Safety / security note
+
+`.vcs` is executable instruction input. Treat it like code:
+
+- Only enable modules/opcodes you intend to allow.
+- Sandbox or validate inputs if `.vcs` can come from untrusted sources.
+- Keep module/opcode mappings stable; changing IDs is a breaking change.
+