elora-voss (npm)

A research and authoring agent. Searches the web, builds a verified knowledge base, writes publication-quality narrative articles.

npm install -g elora-voss
elora-voss init
elora-voss set-key groq YOUR_KEY
elora-voss research "why the universe should not exist"

Requirements

• Node.js ≥ 18
• A free Groq API key from console.groq.com or an OpenRouter key
• Optional: Tavily key for deeper search; Unsplash / Pexels key for article images. Wikipedia works without any key.

Install

# from npm (once published)
npm install -g elora-voss

# from this checkout
npm install -g ./path/to/elora-voss/npm

Commands

elora-voss init                          Create local workspace files
elora-voss set-key <provider> <key>      Save an API key (groq | openrouter | tavily | unsplash | pexels)
elora-voss keys                          Show which API keys are saved
elora-voss set-max-results <n>           Set Tavily max_results (1-20, default 15)
elora-voss research "<topic>"            Run the full pipeline (6 phases)
elora-voss history                       List past research runs
elora-voss last                          Print the most recent article
elora-voss preferences                   Open preferences.txt in your editor
elora-voss --version                     Show installed version
elora-voss --help                        Show help

Workspace

After elora-voss init:

./elora-voss/
├── config              API keys (KEY=VALUE)
├── preferences.txt     personalisation settings
├── topics.csv          research history
├── output.txt          most recent article (always)
└── history/
    ├── context_NNN.md  verified knowledge base from run N
    └── output_NNN.md   article from run N

Pipeline

Six phases, run sequentially:

1. Search — DuckDuckGo (default) or Tavily
2. Cross-check — Groq critic pass, labels claims HIGH/MEDIUM/LOW
3. Knowledge base — compiles structured markdown; saved to disk before phase 4
4. Verify — consistency check, removes contradictions
5. Write — narrative article to the spec's quality standard
6. Illustrate — 3–5 inline images (skipped if INCLUDE_IMAGES=false)

Providers

LLM (MODEL_PROVIDER)

| Provider | Key command | Default model | | ----------- | -------------------------------------------- | --------------------------- | | groq | elora-voss set-key groq YOUR_KEY | llama-3.3-70b-versatile | | openrouter| elora-voss set-key openrouter YOUR_KEY | anthropic/claude-3.5-sonnet |

Set MODEL_PROVIDER in preferences.txt. Optional GROQ_MODEL / OPENROUTER_MODEL overrides.

Images (IMAGE_PROVIDER)

| Provider | Key required | Notes | | ----------- | ------------ | -------------------------------------------------------------------- | | unsplash | yes (free) | via the official unsplash-js SDK, with a REST fallback built-in | | pexels | yes (free) | Pexels REST API | | wikipedia | no | Wikimedia Commons + Wikipedia lead images, fully open-source |

The illustrator tries the preferred provider first, then falls through the remaining configured providers until one returns a hit. Use IMAGE_PROVIDER=wikipedia to skip the API-key requirement entirely.

Preferences

Edit ./elora-voss/preferences.txt to personalise every article:

TONE=intelligent and narrative, like a magazine feature
LENGTH=long-form (800-1200 words)
NICHE=general science and technology
AUDIENCE=curious general readers with no specialist knowledge
LANGUAGE=English
STYLE=editorial essay
OUTPUT_FORMAT=markdown
INCLUDE_IMAGES=true
MODEL_PROVIDER=groq
IMAGE_PROVIDER=unsplash

Every key is optional and falls back to a sensible default.

License

MIT