Metadata-Version: 2.4
Name: zenon-nebula
Version: 0.6.17
Summary: Autonomous intelligence platform for the Zenon Network
Author: ZenonOrg
License: MIT
Project-URL: Homepage, https://github.com/ZenonOrg/nebula
Project-URL: Documentation, https://github.com/ZenonOrg/nebula-docs
Project-URL: Repository, https://github.com/ZenonOrg/nebula
Project-URL: Issues, https://github.com/ZenonOrg/nebula/issues
Project-URL: Changelog, https://github.com/ZenonOrg/nebula/blob/main/CHANGELOG.md
Keywords: zenon,blockchain,intelligence,monitoring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: networkx>=3.0
Requires-Dist: websocket-client>=1.6.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Provides-Extra: full
Requires-Dist: Pillow>=10.0.0; extra == "full"
Requires-Dist: PyPDF2>=3.0.0; extra == "full"
Requires-Dist: pdf2image>=1.16.0; extra == "full"
Requires-Dist: pytesseract>=0.3.10; extra == "full"
Requires-Dist: python-docx>=0.8.11; extra == "full"
Requires-Dist: openpyxl>=3.1.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: pip-tools>=7.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Dynamic: license-file

# Zenon Nebula

<div align="center">

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

_autonomous intelligence for the Network of Momentum_

</div>

<!--
  Badge strategy:
  - Static shields.io badge-endpoint badges work everywhere and are
    self-documenting via their alt text.
  - Dynamic badges (GitHub Actions status, PyPI version, last-commit)
    are re-enabled below once the GitHub repo is reachable
    unauthenticated — they 404 against restricted-visibility repos,
    so the static variants above are the portable fallback.
  - SLSA 3 badge becomes accurate only after the release workflow's
    `provenance` job runs on a tagged release.
-->
<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT"></a>
  <img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue" alt="Python 3.10–3.13">
  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Status: alpha">
  <img src="https://img.shields.io/badge/version-v0.6.17-informational" alt="Version v0.6.17">
</p>

<p align="center">
  <a href="docs/SECURITY-THREAT-MODEL.md"><img src="https://img.shields.io/badge/threat%20model-documented-green" alt="Threat model"></a>
  <a href="docs/SIGNING.md"><img src="https://img.shields.io/badge/sigstore-signed-5865F2" alt="sigstore signed"></a>
  <a href="https://slsa.dev"><img src="https://img.shields.io/badge/SLSA-level%203-brightgreen" alt="SLSA 3"></a>
  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-Keep%20a%20Changelog-orange" alt="Keep a Changelog"></a>
  <a href="https://conventionalcommits.org"><img src="https://img.shields.io/badge/commits-Conventional-fe5196" alt="Conventional Commits"></a>
  <a href="MAINTAINING.md"><img src="https://img.shields.io/badge/maintainers-AI%2BHuman-9cf" alt="Maintainers: AI+Human"></a>
</p>

<!-- nebula:quality-badges:start -->
<!-- Regenerated by scripts/regen_docs.py. Do not edit by hand.
     These badges are the operator-visible quality dashboard:
     every number auto-updates from the actual codebase state on
     every ship. If a count drops, the ship is rejecting reality. -->
<p align="center">
  <img src="https://img.shields.io/badge/tests-3497_passing-brightgreen" alt="Tests: 3497 passing">
  <img src="https://img.shields.io/badge/fuzz-12_properties-brightgreen" alt="Fuzz: 12 property-based tests">
  <img src="https://img.shields.io/badge/scenarios-48_gated-brightgreen" alt="Scenarios: 48 CI-gated regression tests">
  <img src="https://img.shields.io/badge/coverage-55%25_core%20%7C%2047%25_all-brightgreen" alt="Coverage: 55% core / 47% all">
  <img src="https://img.shields.io/badge/architecture-0_violations-brightgreen" alt="Architecture: 0 audit violations">
  <img src="https://img.shields.io/badge/dep%20graph-0_cycles-brightgreen" alt="Dep graph: 0 cycles">
  <img src="https://img.shields.io/badge/lint-ruff_clean-brightgreen" alt="Lint: ruff clean">
  <img src="https://img.shields.io/badge/mutation-Phase_F-orange" alt="Mutation: Phase F">
</p>

<p align="center">
  <img src="https://img.shields.io/badge/OPSEC-scanned-brightgreen" alt="OPSEC: scanned every push">
  <img src="https://img.shields.io/badge/anti--doxxing-enforced-brightgreen" alt="Anti-doxxing: enforced by rule + test">
  <img src="https://img.shields.io/badge/bandit-SAST_gated-brightgreen" alt="Bandit SAST gated">
  <img src="https://img.shields.io/badge/pip--audit-clean-brightgreen" alt="pip-audit clean">
  <img src="https://img.shields.io/badge/rule--adherence-auditor_live-brightgreen" alt="Rule adherence auditor live">
  <img src="https://img.shields.io/badge/README%20truth-gate_live-brightgreen" alt="README truth gate live">
  <img src="https://img.shields.io/badge/integrity-manifest_signed-brightgreen" alt="Integrity manifest signed">
  <img src="https://img.shields.io/badge/domains-18_plugins-blue" alt="18 domain plugins">
  <img src="https://img.shields.io/badge/engines-104_registered-blue" alt="104 engines registered">
</p>
<!-- nebula:quality-badges:end -->

<!--
When the repo goes public, uncomment the dynamic badges below and
delete the static Version/Status ones above.

<p align="center">
  <a href="https://github.com/ZenonOrg/nebula/actions/workflows/test.yml"><img src="https://github.com/ZenonOrg/nebula/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
  <a href="https://github.com/ZenonOrg/nebula/actions/workflows/codeql.yml"><img src="https://github.com/ZenonOrg/nebula/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
  <a href="https://github.com/ZenonOrg/nebula/actions/workflows/scorecard.yml"><img src="https://github.com/ZenonOrg/nebula/actions/workflows/scorecard.yml/badge.svg" alt="OSSF Scorecard"></a>
  <a href="https://pypi.org/project/zenon-nebula/"><img src="https://img.shields.io/pypi/v/zenon-nebula.svg" alt="PyPI"></a>
  <a href="https://github.com/ZenonOrg/nebula/releases"><img src="https://img.shields.io/github/v/release/ZenonOrg/nebula.svg" alt="Release"></a>
  <a href="https://github.com/ZenonOrg/nebula/commits/main"><img src="https://img.shields.io/github/last-commit/ZenonOrg/nebula.svg" alt="Last commit"></a>
</p>
-->


<!-- nebula:stats:start -->
<!-- Regenerated by scripts/regen_docs.py. Do not edit by hand. -->

| 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:stats:end -->

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](https://github.com/ZenonOrg/nebula-docs) —
architecture, capabilities, mission, ADRs, threat model, feature
deep-dives (MCP, RPC, cross-chain, discovery, corroboration,
transport, spec audit).

Local preview:

```bash
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`](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](https://github.com/ZenonOrg/nebula-docs/blob/main/docs/capabilities.md)
for the full section and [ADR-0010](https://github.com/ZenonOrg/nebula-docs/blob/main/docs/decisions/0010-spec-derived-mission.md).

## Quick Start

```bash
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.

```python
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.

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

## License

MIT - see [LICENSE](LICENSE).

---

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

[Zenon Network](https://zenon.network) / [ZenonOrg](https://github.com/ZenonOrg) / [Developer Commons](https://github.com/TminusZ/zenon-developer-commons) / [Docs](https://github.com/ZenonOrg/nebula-docs)
