zenon-nebula 0.6.17

Autonomous intelligence platform for the Zenon Network

Zenon Nebula

██████████████████▇▇▇▇▇▇▇▇▆▆▅▅▆▆▆▇▆▆▆▆▆▆▇▇▆▇▇▇▇▇▇▇▇▇▇▇▇████████
▇▇██████▇█▇███████▇▆▆▅▅▅▅▆▆▆▆▅▅▅▅▅▅▅▄▅▇▇▇▆▇▅▅▅▆▇▆▆▇▇▇▇█████████
█▇███ █▇▇▇▇▇▇▇▇▇▆▆▅▅▆▆▆▆▆▅▅▄▄▄▅▅▄▄▃▃▅▇▇▇▆▅▃▃▄▂▄▅▇▇▇▆▆▇▇▇▆▇▇▇███
█▇▇▇▇▇▇▇▆▆▆▆▆▆▆▅▅▆▇▇▇▇▇▆▆▅▄▃▄▄▅▄▅▃▂▅▆▅▃▄▅▇▇▆▅▄▓▄▅▆▅▅▄▆▇▇▇▇▇▇▇▇▇
█▇▇▇▇▇▇▇▇▄▆▆▄▆▆▆▅▆▆▆▆▆▅▄▃▃▄▅▄▂▁▃▒▁▂▂▃▄▅▅▇▇▇▇▆▅▅▄▅▅▆▆▆▆▇▇▇▇▇▇▇▇▇
█████▇▇▇▆▆▆▆▆▆▆▆▆▅▄▄▅▄▄▃▃▄▄▁▓▒▒▁▄▃▂▅▄▄▅▅▆▇▆▆▇▇▆▄▆▄▅▅▅▅▅▆▇▇▇▇▇▇▇
████▇▅███▅▆▅█▇▄▄█▇▆▇▇▇▇▃▇▇▇▆▇▇▓▃▁█▇▃▂▂▇▇▂▄▆▄▄▆▇▇▇▇▆▄███▄▇▇▇▇▇▇▇
██▇▇▇▃██▇█▂▄▇▇▂▃▇▇▂▁▓▁▁▁▇█▓▓▒█▆▃▁▆▇▃▄▄▇▆▂▓▆▅▃▆▆▆▆▆▁██▁█▇▅▇▇▇▇▇▇
▇▇▇▇▆▄▆▆▃▆█▇█▇▂▁▇▅▅▃▁▁▁▓▅▆▒▓▒▆▆▓▒▆▃▄▅▄▇▆▁▃▇▇▃▆▆▆▆▄▇▆▃▁▇██▆▇▇▇▇▇
█▇▇▇▆▅██▁▅▄▆▇▆▓▓▇▆▆▆▆▅▅▓▄▄▄▆▆▆▅▁▃▆▆▇▆▇▇▅▅▄▇▇███▇▃██▂▅▂▃▇▇▂▇▆▇▇▇
██▇▇▇▆▄▄▆▆▆▆▅▃▁▂▂▂▂▂▂▂▃▃▁▒▓▓▓▓▄▄▄▅▃▁▂▃▅▆▇▆▆▅▅▅▅▅▆▅▆▆▆▇▆▆▆▅▆▇▇▇▇
▇▇▇▇▇▇▇▇▇▇▇▇▅▓▃▃▂▁▃▂▂▃▂▂▄▃▁▒▓▂▂▃▃▄▃▃▃▅▆▇▇▆▆▆▆▆▆▆▆▆▇▆▇▇▇▇▇▇▇▇▇▇█
██▇▇▇█▇▇▇▇▆▅▂▅▅▄▂▂▂▃▂▓▂▄▅▅▄▁▒▓▓▁▂▂▄▄▄▆▆▆▅▆▆▆▆▆▆▆▆▄▇▇▇▇▇▇▇▇▇▇▇▇█
████████▇▇▆▅▇▇▆▆▇▆▆▆▅▄▄▆▆▆▅▄▄▃▄▁▂▁▁▓▓▃▁░▁▄▅▂▄▂▃▆▅▅▄▅▆▆▇▇▇▇▇▇███
███████▇▇▇▇▇▇▇▆▅▆▇▆▅▄▅▆▆▇▇▇▅▅▅▅▅▄▃▄▄▄▂▆▇▇▆▆▇▇▆▅▅▆▇▇▇▃▇▇▇▇▇▇████
█████████▇▇▇▇▇▇▇▇▇▆▆▆▆▆▇▇▇▇▇▇▇▇▆▆▆▇▆▆▆▇▇▇█████▇▇███████████████

autonomous intelligence for the Network of Momentum

Metric	Count
Python files	578
Lines of code	166,773
Core modules	147
Domains	18
Engines	104
Test files	209
Scripts	25
Schema tables	96
MCP tools	14

Nebula is an autonomous intelligence platform for the Network of Momentum. It monitors the entire Zenon ecosystem in real time - specs, code, governance, bridge health, liquidity, narratives, and security - cross-references every signal through Bayesian hypothesis evolution and collision detection, and produces mission-aligned battle plans. Nebula is critical Zenon infrastructure: the nervous system that keeps the community informed, the network hardened, and the roadmap honest.

Docs

Full operator + contributor documentation lives at ZenonOrg/nebula-docs — architecture, capabilities, mission, ADRs, threat model, feature deep-dives (MCP, RPC, cross-chain, discovery, corroboration, transport, spec audit).

Local preview:

git clone https://github.com/ZenonOrg/nebula-docs
cd nebula-docs
pip install mkdocs-material "mkdocstrings[python]"
mkdocs serve   # http://127.0.0.1:8000

What stays in this repo (alongside the code):

• CHANGELOG.md — shipped releases
• CLAUDE.md — auto-regenerated machine-readable dev guide
• docs/claims.yml — executable claim ledger (README truth gate)
• docs/tasks.yaml — internal task backlog
• docs/runbooks/ — operational failure-mode docs
• docs/DOMAINS.md — auto-generated domain + engine catalog

Mission

Nebula is mission-driven via core/mission/definition.py. Five pillars (trustlessness, sovereignty, composability, auditability, adoption) with weights that sum to 1. When the spec corpus is available, core/mission/spec_derivation.py re-derives the pillars; otherwise the hardcoded five are the fallback. The mission belongs to Nebula and the Zenon protocol's trajectory, not to any one author. See docs/mission for the full section and ADR-0010.

Quick Start

git clone https://github.com/ZenonOrg/nebula
cd nebula
pip install -r requirements.txt
cp env.example.txt .env
./nebula --cycles 5
./nebula status

Zero infra needed. The first cycle runs against a fresh SQLite DB and populates data/engine.db with baseline findings.

CLI commands

CLI Commands

Command	Description
./nebula	Run continuously (24/7)
./nebula --cycles N	Run N cycles then stop
./nebula --budget N	Run with a USD budget cap
./nebula --hours N	Run for N hours
./nebula --domains sec,qual	Run only selected domains
./nebula status	Show evidence count, hypotheses, collisions, uptime
./nebula dashboard	One-shot operational snapshot: findings, forecasts, disagreements, aspirations, peer catalogue, proposals, battle plan
./nebula findings [--domain D] [--evidence-type T] [--limit N] [--full]	Show recent findings; filter by domain or evidence_type (e.g. model_disagreement, counterfactual_forecast, symbolic_pattern, clarification_request)
./nebula plan	Show the latest War Room battle plan
./nebula domains	List every registered domain and its engines
./nebula hypotheses	Show Bayesian hypotheses with current confidence
./nebula costs	LLM cost breakdown by provider and model
./nebula specs	Spec coverage matrix across go-zenon, SDKs, CLI, wallet
./nebula height	Evidence-chain height (append-only)
./nebula serve	Start the MCP server (8 tools)
./nebula rpc	Start the JSON-RPC server (default: 127.0.0.1:8484)
./nebula providers	List shipped + user providers (kind, trust tier, status)
./nebula providers test <name>	Dry-run a provider to confirm it's reachable
./nebula providers reload	Re-read ~/.config/nebula/providers.toml without restarting
./nebula findings --by-provider	Group findings by the provider that produced them
./nebula findings --by-author	Group findings by discoverer_peer_id (task #64 attribution surface)
./nebula snapshot export	Export evidence snapshot for peer sharing
./nebula snapshot import FILE	Import a peer snapshot
./nebula sync	Pull the latest snapshot from configured peers
./nebula workspace list	Show the workspace manifest with per-entry clone status
./nebula workspace bootstrap	Clone every required Zenon repo into $ZENON_WORKSPACE_ROOT (idempotent)
./nebula workspace update	git fetch on every cloned manifest entry (never auto-merges)
./nebula workspace pin	Report current HEAD SHAs + branches of cloned entries
./nebula plugins list	Show plugins registered on this instance (name, source, engine count, author)
./nebula plugins discover	Show peer-plugin catalogue (metadata only; populated once Phase 3b transport ships)
./nebula plugins lineage <name>	Show which peers run a plugin by name
./nebula aspirations list	Show active aspirations (title, pillar, status)
./nebula aspirations export [--label LABEL] [--note TEXT] [--output FILE]	Write an AspirationPack JSON for sharing research focus
./nebula aspirations import FILE [--activate]	Insert aspirations from a pack (proposed by default; --activate promotes to active)
./nebula threads list FILE	Inspect a ResearchThread file (.thread.json) without importing — shows exporter, label, aspiration + evidence counts
./nebula threads export [--label LABEL] [--note TEXT] [--domain DOMAIN] [--limit N] [--tag TAG]... [--output FILE]	Write a ResearchThread JSON bundling aspirations + seed evidence + mission tags for end-to-end research sharing
./nebula threads import FILE [--activate]	Import a ResearchThread; aspirations land proposed (or active with --activate), evidence capped at 0.30 confidence and attributed to the exporter
./nebula agents list [--ascending] [--limit N] [--tier high|known|fresh|untrusted] [--json]	Show registered executor agents with trust + completion stats; --tier filters by trust band; --json emits a structured payload for scripting (task #68 I2)
./nebula agents show <id> [--limit N] [--json]	Detail view for one agent — trust, counters, timestamps, recent completion events; --json emits a structured payload
./nebula agents trust <id>	Print just the trust score (scripting-friendly; exit 1 when unknown)
./nebula agents retire <id> [--yes]	Deregister an agent; prompts for confirmation unless --yes is passed (leaves agent_completions audit trail intact)
./nebula sim [governance|economic_shock|validator_set|bridge_liquidity] [--trials N] [--horizon N] [--min-severity stable|warning|critical]	Run a simulation engine on-demand (counterfactual Monte Carlo forecasts)
./nebula ask "question"	Freeform query against the knowledge graph

Adding a domain

Domains are auto-discovered at runtime. Drop a plugin in domains/, restart. Every engine declares its own SCHEMA_SQL constant so the registry picks the table up automatically.

from nebula_sdk import DomainPlugin, EngineDefinition

class MyDomain(DomainPlugin):
    def name(self) -> str:
        return "my_domain"

    def get_engines(self) -> list:
        return [EngineDefinition(
            name="my_engine",
            description="Does the thing.",
            module_path="domains.my_domain.engines.my_engine",
            priority=5,
        )]
    # ... plus the other abstract methods; see nebula_sdk/README.md

Third-party authors can pip install zenon-nebula-sdk — a small, dependency-free package that exposes the stable plugin ABCs. The SDK works standalone (stub implementations let you author + test a plugin without a Nebula install) and transparently re-exports the live core/ classes once Nebula is installed alongside.

See domains/ for eighteen complete examples.

Stats

The stat block at the top of this file is auto-regenerated by scripts/regen_docs.py. Live counts come directly from walking the codebase, so they self-update on every commit that affects the numbers.

python3 scripts/regen_docs.py            # rewrite in place
python3 scripts/regen_docs.py --check    # CI gate — no drift allowed

License

MIT - see LICENSE.

---

Built with Python 3.10+, SQLite, and xAI Grok.

Zenon Network / ZenonOrg / Developer Commons / Docs