Skip to content

SETUP.md

Latest commit

 

History

History
193 lines (140 loc) · 7.33 KB

SETUP.md

File metadata and controls

193 lines (140 loc) · 7.33 KB
Raw

Voultra Grid — Full Setup Guide

Everything needed to run, configure, test, and publish Voultra Grid from a clean machine.

1. Prerequisites

Tool Why Check
Python 3.10+ Runs the FastAPI backend, agents, policy, tests python --version
pip Installs Python dependencies pip --version
Git Version control / GitHub push git --version
A modern browser Dashboard + landing page —

No Node.js, no build step, no bundler — the dashboard and landing page are vendored, zero-build static sites served by FastAPI.

2. Install

cd voultra_grid_hackathon
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

On macOS/Linux, activate with source .venv/bin/activate instead.

Optional extras:

pip install -e ".[agents]"   # Fetch.ai uAgents (asi_one_chat_agent.py, fetch_multi_agent_demo.py)

3. Configure .env

Copy the template and fill in only what you need — everything is safe-by-default and works with zero configuration for a demo.

Copy-Item .env.example .env

Open .env in a text editor. Key sections:

Variable Required? What it does
VOULTRA_DEMO_MODE No (default true) true = deterministic demo data, false = live NESO/Elexon
FETCH_AGENT_SEED Recommended to change Deterministic identity seed for your uAgent — change before a public demo
FETCH_MAILBOX No (default true) Lets the agent register on Agentverse without a public URL
ASI_ONE_API_KEY No Add your own key from https://asi1.ai/dashboard/api-keys to make the dashboard chat call the real ASI:One API. Leave blank to use the local agent logic instead — never paste this key into a chat with an AI assistant, including this one.
KASPA_ENABLED / KASPA_BROADCAST_COMMAND No Leave KASPA_BROADCAST_COMMAND blank for local-commit-only (safe default). Fill in your own wallet CLI command to broadcast to TN-10.
ETHEREUM_ENABLED / ETH_RPC_URL / ETH_PRIVATE_KEY No Off by default. Needs your own Sepolia RPC + key + deployed ImpactLedger.sol address to enable.

.env is in .gitignore — it will never be committed or pushed.

4. Run it

Landing page + dispatch console (one server, two routes)

uvicorn voultra_grid.api:app --port 8080
  • http://127.0.0.1:8080/ — marketing landing page (real photography, live telemetry strip)
  • http://127.0.0.1:8080/app — the actual dispatch console: Dispatch / Agent Chat / Backtest / Audit Log / Network tabs, plus the floating chat widget on every page

CLI (no server needed)

python -m voultra_grid.cli run-cycle          # deterministic demo
python -m voultra_grid.cli run-cycle --live   # real NESO + Elexon

Fetch.ai agents

$env:PYTHONPATH = ".\src"
python agents\asi_one_chat_agent.py          # ASI:One-compatible chat agent, port 8001
python agents\fetch_multi_agent_demo.py      # local 3-agent Bureau proof

If port 8001 is already in use:

netstat -ano | findstr :8001
taskkill /PID <the_pid_shown> /F

5. Run the tests

python -m pytest tests/ -q

22 tests covering: decision-hash determinism, all policy branches (including the live curtailment window), flex-market logic, Apex submission shape/constraints, every API endpoint end-to-end, hash verification (matching and tampered), stress-history, the real historical backtest, and the chat endpoint (local, real-ASI:One-mocked, and fallback-on-failure paths).

6. Push to GitHub

These commands never set your Git identity to anything but your own — run them yourself in PowerShell from inside the project folder. If you've never used Git on this machine before, set your name/email once (replace with your own):

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Then, from inside voultra_grid_hackathon:

git init
git add .
git status                       # sanity check: .env and data/ should NOT be listed
git commit -m "Voultra Grid: curtailment rescue network"

Create an empty repository on GitHub first (no README/license, so it stays empty), then:

git branch -M main
git remote add origin https://github.com/<your-username>/<your-repo-name>.git
git push -u origin main

If you'd rather use the GitHub CLI to create the repo in one step:

gh repo create <your-repo-name> --public --source=. --remote=origin --push

Before you push, double-check:

git status

.env and data/ must not appear as tracked files. If they do, they were committed before .gitignore took effect — remove them from tracking without deleting them locally:

git rm --cached .env
git rm -r --cached data
git commit -m "Stop tracking local env and generated data"

7. Project map

voultra_grid_hackathon/
├── README.md                    quickstart, judge script, bounty write-up
├── SETUP.md                     this file
├── .env.example                 copy to .env and fill in what you need
├── pyproject.toml / requirements.txt
├── src/voultra_grid/
│   ├── api.py                   FastAPI app: dashboard, chat, backtest, verify, health...
│   ├── orchestrator.py          run_cycle, chat_reply — the core dispatch logic
│   ├── apex_policy.py           battery dispatch policy (charge/discharge/hold)
│   ├── grid_data.py             NESO + Elexon clients, with demo fallback
│   ├── flex_market.py           simulated battery/EV/cold-storage providers
│   ├── settlement.py            SHA-256 commit-before-execute + audit log
│   ├── ethereum_impact.py       ImpactLedger.sol adapter (web3 v6/v7 compatible)
│   ├── asi_one_client.py        real ASI:One Chat Completions API client
│   ├── backtest.py              24h replay engine against real historical data
│   └── static/
│       ├── landing/             marketing home page (/) — real photos, real copy
│       └── *.html, app.js, styles.css   the dispatch console (/app)
├── agents/                      Fetch.ai uAgents (ASI:One chat agent, 3-agent demo)
├── apex_submission/policy.py    standalone numpy-only Apex CLI submission
├── contracts/ImpactLedger.sol   Solidity impact-ledger contract
├── tests/                       22 tests
└── docs/                        dashboard screenshots

8. Troubleshooting

Symptom Fix
ModuleNotFoundError: No module named 'voultra_grid' Run pip install -e ".[dev]" from the project root, or set $env:PYTHONPATH = ".\src"
only one usage of each socket address on port 8001 Another agent process is already running — see step 4 above
Dashboard shows stale UI after an update Hard refresh: Ctrl+Shift+R. If still stale, delete the extracted folder entirely and re-extract — don't overwrite-merge
Live mode shows hold with empty offers Correct behaviour, not a bug — the real grid isn't in a curtailment/high-stress window right now. Switch to Deterministic demo, or try the Backtest tab for a day that had one
ASI:One chip shows "local" ASI_ONE_API_KEY isn't set in .env — this is the safe default. Add your own key to go live