File size: 6,646 Bytes

108cd52

---
license: other
license_name: sovereign-source-license-v2
library_name: custom
tags:
- code
- sovereign-compute
---

# Perplexity Macro VM

**Sovereign Source License v1.0** — Copyright (c) 2026 Ahmad Ali Parr + Jessica Westerhoff, BEL ESPRIT D ACCORD TRUST HOLDINGS INC. Patent Pending.

Deterministic 16-bit research VM that runs Perplexity-style planning, search, evidence, critique, and synthesis compiled to ROM. Elixir GenServer OTP + Phoenix LiveView streams every retired instruction. Host does web/model/code work behind typed capability boundaries; VM owns control flow.

> **Live Agent Console** — https://snapkittywest.github.io/perplexity-macro-vm/

## Features

- **Ollama / OpenAI / OpenRouter** model integration (local or cloud)
- **Python execution** via Pyodide (runs in browser, no server needed)
- **Web search** via DuckDuckGo (client-side)
- **Terminal tools** (client-side simulation, backend-ready)
- **Tool calling protocol** — model can invoke tools automatically
- **Deterministic VM** — 16-bit, 65K words, typed capabilities, transcript hashing

## Architecture

```
                Phoenix LiveView (trace | regs | memory | graph)
                              ^ PubSub
                     TraceHub (ring buffer 50k)
                              ^ {:retired, trace}
MacroVM GenServer — fetch/decode/execute -> commit -> emit one trace
      ^ capability request | host result v
ResearchBroker (search/fetch/LLM/evidence)   Compiler (.pqm -> ROM)
```

VM owns control flow and acceptance policy. Host returns typed evidence records to a waiting `RQ` instruction.

## VM Contract

```
Word: 16 bits, 65,536 words
ROM: $0000-$1FFF  RAM: $2000-$DFFF  MMIO: $E000-$E0FF  Stack: descending, RAM-backed
Regs: A,B,C,D, PC, SP=0xDFFF, BP, FLAGS
Cycles: fixed per opcode
State: %State{rom, ram, regs, cycles, retired, halted?, waiting?, fuel=128, transcript_hash, breakpoints, watches, trace_seq}
```

## Instruction Set

| Op | Mnemonic | Cyc | Meaning |
|---|---|---|---|
| 00 | NOP | 1 | |
| 01 | LDI r,imm16 | 2 | |
| 02 | LD r,[addr] | 3 | |
| 03 | ST [addr],r | 3 | |
| 04 | ADD rd,rs | 1 | |
| 05 | XOR rd,rs | 1 | |
| 06 | CMP ra,rb | 1 | |
| 07 | JMP addr | 2 | |
| 08 | JZ addr | 2/3 | |
| 09 | CALL addr | 3 | |
| 0A | RET | 3 | |
| 0B | DEC r | 1 | |
| 0C | HALT code | 1 | |
| 20 | RQ cap,ptr,len | 4 | capability request |
| 21 | POLL rd | 2 | status |
| 22 | READ rd,off | 3 | host result word |
| 23 | VERIFY ptr,len | 6 | schema/CRC |
| 24 | EVIDENCE claim,src | 3 | provenance |
| 25 | COVERAGE rd | 4 | cited-claim coverage |
| 26 | DISAGREE rd | 5 | contradiction flags |
| 27 | HASH ptr,len | 8+ | transcript hash |
| 28 | FUEL | 1 | trap at zero |
| 29 | EMIT kind,ptr,len | 3 | checkpoint |
| 2A | CONFIRM cap | 2 | one-shot auth |

Capabilities: `01=search 02=fetch 03=browser 04=code 05=local_model 06=file_read 07=file_write 08=calendar 09=email` — sensitive require `CONFIRM` + expiring token.

## Agent Console

**Live:** https://snapkittywest.github.io/perplexity-macro-vm/

Clean chat interface with tool calling:

1. **Connect** — Pick provider (Ollama/OpenRouter/OpenAI), enter credentials
2. **Chat** — Ask anything, model can call tools automatically
3. **Tools** — Python (Pyodide), web search (DuckDuckGo), terminal
4. **Terminal panel** — Toggle to see tool execution log

```
Onboarding -> Provider Selection -> Chat Interface
                                         |
                              Tool Detection (```python, ```search, ```terminal)
                                         |
                              Tool Execution (Pyodide / API / simulated)
                                         |
                              Result -> Model -> Answer
```

### Tool Calling

The model can invoke tools by emitting fenced code blocks:

```python
# Python execution (Pyodide, runs in browser)
import numpy as np
print(np.mean([1, 2, 3, 4, 5]))
```

```search
WebGPU latest news 2025
```

```terminal
ls -la
```

Results are fed back to the model for synthesis.

### Run locally

```bash
# Just open the HTML file
open docs/agent-console/index.html

# Or serve with Python
cd docs/agent-console && python -m http.server 8080
```

## Macro Language .pqm

`programs/research_loop.pqm` — declarative research logic compiled to ROM.

```
program research_loop
const fuel_budget=12, min_sources=3
entry: fuel fuel_budget
plan:  request search, query("topic decomposition") -> await -> verify -> branch_invalid retry_plan
search: request search, subquestion batch -> await -> verify -> evidence -> coverage -> branch_lt min_sources, search
read: request fetch, selected -> await -> verify -> evidence -> disagreement -> branch_true critique
synthesize: request local_model, render_cited_answer -> await -> verify -> emit final -> halt
critique: request search, counterevidence -> await -> verify -> jump synthesize
```

Compiler: `lexer -> parser -> typed AST -> policy checker -> CFG -> label resolution -> opcode selection -> .pqr + .pqmap + manifest.json`.

## API Endpoints (Research Host)

All via `ResearchBroker` -> `Adapters.*`. Every adapter returns normalized TLV-compatible maps with `source_hash`.

* **Tavily** `Adapters.Search` — `POST https://api.tavily.com/search`
* **Wikipedia** `Adapters.Wikipedia` — `GET https://en.wikipedia.org/w/api.php`
* **Mathematica** `Adapters.Mathematica` — `POST https://api.wolframalpha.com/v1/query`
* **Dictionary** `Adapters.Dictionary` — `GET https://api.dictionaryapi.dev/api/v2/entries/en/<word>`
* **Fetch** `Adapters.Fetch` — generic GET with allowlist
* **Browser** `Adapters.Browser` — Playwright automation
* **Code** `Adapters.Code` — sandboxed Python/JS
* **Local Model** `Adapters.LocalModel` — Ollama/LM Studio

## Run (Elixir Backend)

```bash
mix deps.get
mix test
iex -S mix
# Phoenix at http://localhost:4000
mix compile.pqm programs/research_loop.pqm --out priv/rom/
```

## Layout

```
cfg/macro_rom.cfg
asm/crc16.s
docs/agent-console/          # Frontend (static, GitHub Pages)
apps/AgentConsole/           # Swift frontend
java-sdk/                    # Java SDK (Maven)
lib/perplexity_macro/        # Elixir backend
proofs/MacroProtocol.lean    # Verification
programs/research_loop.pqm   # VM programs
priv/rom/                    # Compiled ROM
```

## License

**Sovereign Source License v1.0**

Copyright (c) 2026 Ahmad Ali Parr + Jessica Westerhoff
BEL ESPRIT D ACCORD TRUST HOLDINGS INC.

This software is provided under the Sovereign Source License. Use, modification, and distribution are permitted only as authorized by the copyright holders. Patent Pending.