{"id":50784318,"url":"https://github.com/av/holoiconic","last_synced_at":"2026-06-12T06:07:20.329Z","repository":{"id":358461670,"uuid":"1241380479","full_name":"av/holoiconic","owner":"av","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-17T13:13:53.000Z","size":429,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T15:39:59.919Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/av.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-17T10:12:20.000Z","updated_at":"2026-05-17T13:14:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/av/holoiconic","commit_stats":null,"previous_names":["av/holoiconic"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/av/holoiconic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/av%2Fholoiconic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/av%2Fholoiconic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/av%2Fholoiconic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/av%2Fholoiconic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/av","download_url":"https://codeload.github.com/av/holoiconic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/av%2Fholoiconic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34231270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-12T06:07:19.648Z","updated_at":"2026-06-12T06:07:20.322Z","avatar_url":"https://github.com/av.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# holoiconic\n\nHoloiconic is a self-modifying agentic runtime where everything, including code, data, configuration, conversation history, metrics, and versions, lives as RDF quads in a reactive graph database backed by Turso/libSQL. The kernel is small plumbing. Runtime behavior lives in graph-resident nodes that can inspect, modify, and spawn each other.\n\n## Quick start\n\n```bash\nbun install\nbun start\n```\n\nThis boots the kernel, seeds an empty graph from the template, installs the reactive compiler, starts the supervisor, API server, WebUI, and REPL.\nSee \"Using custom OpenAI-compatible providers\" below for `OPENAI_BASE_URL=...` etc (Groq, Ollama, vLLM...).\n\n## Using custom OpenAI-compatible providers (Groq, Ollama, vLLM, OpenRouter, ...)\n\nTrivial to launch against any OpenAI-compat endpoint via 6 methods.\n\nPrecedence (highest wins): CLI flags \u003e config file \u003e environment variables \u003e defaults (`mock:llm` only when neither key nor `baseUrl`).\n\n| Source | Example use | Scope |\n|--------|-------------|-------|\n| CLI flags | `bun start -- --openai-base-url=...` | per-invocation |\n| `.holoiconic.json` (or `holoiconic.config.json`) | persistent file (cwd or `~/`) | across restarts |\n| env vars | `OPENAI_BASE_URL=... bun start` | shell / `.env` |\n| REPL `.provider` | `.provider set --base ...` | REPL session |\n| WebUI form | inline inputs in chat header | browser tab |\n| per-request | body fields or `x-openai-*` headers | single API call |\n\n**1. Persistent config file** (`.holoiconic.json` or `holoiconic.config.json` in cwd or home dir):\n\nCopy the ready-to-use documented template (contains Groq, Ollama local, OpenRouter examples + comments + security notes + precedence):\n```bash\ncp .holoiconic.json.example .holoiconic.json\n```\nThen edit the copy (valid JSON only; supports the shape below or flat keys). `bun start` loads it automatically from cwd or `~/`.\n\n```json\n{\n  \"provider\": {\n    \"baseUrl\": \"https://api.groq.com/openai\",\n    \"apiKey\": \"gsk_...\",\n    \"model\": \"llama-3.1-70b-versatile\"\n  }\n}\n```\n(Flat top-level keys like `\"baseUrl\"` are also accepted, as are snake_case variants.) See `.holoiconic.json.example` for 3 full commented examples.\n\nOverride the searched locations (cwd + ~/) with an exact path using env `HOLOICONIC_CONFIG` (or `HOLOICONIC_CONFIG_PATH`) or CLI `--config PATH` (CLI \u003e file \u003e env precedence).\n\n**2. CLI flags** (pass after `--` for `bun start`; direct boot also supports):\n\n```bash\nbun start -- --openai-base-url=https://api.groq.com/openai \\\n  --openai-api-key=gsk_... --model=llama-3.1-8b-instant\n# shorts: -b URL -k KEY -m MODEL ; also --provider, --api-port etc.\nbun src/boot.ts --help\n```\n\n**3. Environment variables** (copy `.env.example` to `.env` and edit):\n\n```bash\nOPENAI_BASE_URL=https://api.groq.com/openai \\\nOPENAI_API_KEY=gsk_... \\\nHOLOICONIC_MODEL=llama-3.1-70b-versatile \\\nbun start\n```\nSupported: `OPENAI_BASE_URL` (or `OPENAI_API_BASE`), `OPENAI_API_KEY`, `HOLOICONIC_MODEL` (or `OPENAI_MODEL` / `MODEL`).\n\n**4. REPL** (per-session override, after boot):\n\n```\nholo\u003e .provider set --base https://api.groq.com/openai --key gsk_... --model llama-3.1-70b\nholo\u003e .provider show\nholo\u003e .provider clear\n```\n\n**5. WebUI** (http://localhost:3002): the chat header includes a status badge. Use the compact form right below it (baseUrl, apiKey, model fields + set/clear buttons). Configuration is saved to localStorage and survives reloads; values are forwarded on each send.\n\n**6. Per-request** (overrides everything for one call to the OpenAI-compatible API on :3001):\n\n```bash\ncurl -X POST http://localhost:3001/v1/chat/completions \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-openai-base-url: https://api.groq.com/openai\" \\\n  -H \"x-openai-api-key: gsk_...\" \\\n  -d '{\"model\":\"llama-3.1-70b-versatile\",\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}'\n```\nBody also accepts `baseUrl`, `apiKey`, `model` (and snake_case variants). `Authorization: Bearer \u003ckey\u003e` works for the key (base from header or body).\n\n**Notes**\n\n- When a `baseUrl` is supplied (any method), a dummy key `sk-local` is used automatically if none provided — this works for local servers (Ollama, llama.cpp, vLLM, etc.) that need no auth.\n- Specify the exact model name expected by your target endpoint.\n- `bun src/boot.ts --help` (or via `bun start -- --help`) shows the full flag list.\n- Custom provider errors are actionable: they report the attempted base URL, the original fetch/HTTP error, verification advice, and the configuration source (CLI / config / env / REPL / per-request / WebUI).\n- Cross-references: `.env.example` (detailed vars + snippets), CLAUDE.md (\"Environment variables\" section), `facts list --section providers --tags spec` (and `facts check --tags \"spec\"` for the full provider spec).\n\n## Environment variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `OPENAI_API_KEY` | For OpenAI-compatible LLMs and embeddings | Used by the default `openai` provider path. |\n| `ANTHROPIC_API_KEY` | For Anthropic models | Used when selecting the `anthropic` provider. |\n| `TURSO_URL` | For cloud DB | Turso Cloud URL, for example `libsql://db-org.turso.io`. |\n| `TURSO_AUTH_TOKEN` | For cloud DB | Turso Cloud auth token. |\n\nWithout LLM API keys, `main` spawns the graph-resident `mock:llm` node. It registers a pi-ai faux provider for completions and serves OpenAI-compatible mock embeddings. Without Turso credentials, data is stored locally in `holoiconic.db`. For custom providers see 'Using custom OpenAI-compatible providers' section above (6 methods + table).\n\n## Interfaces\n\nThe runtime exposes three interfaces, all started automatically by the `main` node:\n\n- **REPL**: interactive command line at the `holo\u003e` prompt. Natural language input routes through `agent:loop`; dot-commands provide direct graph manipulation.\n- **API**: OpenAI-compatible API on `localhost:3001`, including `/v1/chat/completions`, streaming SSE support, `/v1/models`, and `/health`.\n- **WebUI**: browser-based chat and graph explorer on `localhost:3002`.\n\n## The ctx primitives\n\nEvery node receives a `ctx` object with these primitives:\n\n| Primitive | Signature | Description |\n|---|---|---|\n| `insert` | `ctx.insert(subject, predicate, object, graph?, embedding?)` | Insert an RDF quad. Idempotent for duplicate `(subject, predicate, object, graph)` values. |\n| `remove` | `ctx.remove(subject, predicate, object?, graph?)` | Remove matching quads. Omitting `object` removes all values for `(subject, predicate, graph)`. |\n| `query` | `ctx.query({ subject?, predicate?, object?, graph? })` | Pattern-match quads. Omitted fields are wildcards. |\n| `call` | `ctx.call(name, args?)` | Execute a graph-resident node by name. |\n| `set` | `ctx.set(subject, predicate, object, graph?, embedding?)` | Atomically replace all values for `(subject, predicate, graph)` with one value. |\n| `on` | `ctx.on(pattern, callback)` | Subscribe to quad changes matching a pattern. Returns an unsubscribe function. |\n\n`ctx.self` returns the name of the currently executing node via AsyncLocalStorage.\n\n## REPL commands\n\n```text\n.query {\"subject\":\"...\",\"predicate\":\"...\"}  query quads by pattern\n.insert subject predicate object [--g graph]     insert a quad\n.remove subject predicate object [--g graph]     remove a quad\n.call name [argsJSON]                            call a node\n.nodes                                           list Function nodes\n.source \u003cname\u003e                                   view node source\n.edit \u003cname\u003e                                     edit node source inline\n.create \u003cname\u003e                                   create a node interactively\n.spawn \u003cname\u003e                                    spawn a long-lived node\n.sessions                                        list conversation sessions\n.session                                         show current session ID\n.export [path]                                   export graph snapshot JSON\n.import \u003cpath\u003e                                   import graph snapshot JSON\n.deps \u003cname\u003e                                     show node dependencies\n.inspect \u003cname\u003e                                  show comprehensive node info\n.versions \u003cname\u003e                                 list saved source versions\n.restore \u003cname\u003e \u003cseq\u003e                            restore a source version\n.cron \u003cname\u003e \u003cinterval_ms\u003e                       run a node on a timer\n.crons                                           list cron jobs\n.metrics                                         show metrics report\n.eval \u003ccode\u003e                                     eval code with ctx in scope\n.help                                            show help\n```\n\nAny input not starting with `.` is sent to `agent:loop`.\n\n## Running tests\n\n```bash\nbun run src/test-boot.ts\n```\n\nThe integration test suite uses a custom harness and boots the full runtime against a local file DB.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fav%2Fholoiconic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fav%2Fholoiconic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fav%2Fholoiconic/lists"}