Metadata-Version: 2.4
Name: nseg-runtime
Version: 0.5.6
Summary: Production-governed AI agent runtime with policy-driven risk routing, multi-model consensus, and full audit provenance.
Author: NSEG Runtime Contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/shuneka/nseg-runtime
Project-URL: Repository, https://github.com/shuneka/nseg-runtime
Project-URL: Issues, https://github.com/shuneka/nseg-runtime/issues
Project-URL: Changelog, https://github.com/shuneka/nseg-runtime/blob/main/CHANGELOG.md
Keywords: ai,agent,governance,policy,consensus,llm,runtime
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1,>=0.104.0
Requires-Dist: uvicorn[standard]<1,>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: respx>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

<div align="center">

![NSEG Runtime](docs/assets/banner.png)

# NSEG Runtime

### Production-Governed AI Agent Runtime

**Policy-driven risk routing · Multi-model consensus · Full audit provenance · Zero-trust execution**

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12%20%7C%203.13-blue)](pyproject.toml)
[![Tests](https://img.shields.io/badge/Tests-2146_passing-brightgreen)](tests/)
[![Code Style](https://img.shields.io/badge/code_style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

[Quick Start](#quick-start) · [Architecture](#architecture) · [Documentation](#documentation) · [Contributing](CONTRIBUTING.md)

</div>

---

## What is NSEG Runtime?

**NSEG (Neuro-Symbolic Event Generator) Runtime** is a standalone Python server that orchestrates **governed AI agent loops** with deterministic policy enforcement. Every action — from a simple read to a regulated infrastructure change — passes through a risk router that classifies operations into tiers (R0–R3), enforces approval workflows, and produces an immutable evidence chain from request to final response.

Unlike permissive agent frameworks, NSEG Runtime is **governance-first**: unknown or ambiguous operations are denied by default (fail-closed), and every capability — tools, skills, plugins, model providers — flows *through* the policy layer rather than around it.

### Why NSEG Runtime?

| Concern | NSEG Runtime Approach |
|---------|----------------------|
| **Safety** | Deterministic R0–R3 risk routing; fail-closed posture |
| **Auditability** | Immutable evidence records with SHA-256 content hashes |
| **Consensus** | Multi-model panel execution with judge selection and synthesis |
| **Extensibility** | Plugin sandbox, skill quarantine, governed MCP bridge |
| **Observability** | Verification ledger, trajectory tracking, OTel + Prometheus |
| **Compliance** | Profile-based strictness (developer → high-assurance) |

---

## Key Capabilities

### Core Governance

- **Policy-Driven Risk Routing** — Deterministic R0–R3 tier classification with reason codes and downgrade options
- **Multi-Model Consensus** — Parallel panel execution, judge selection, synthesis with replay verification
- **Mixture-of-Agents Orchestration** — MoA engine with model registry, usage pricing, credits tracking, provider pool
- **Evidence Chain** — Full provenance: source hashes, panel outputs, judge verdicts, content hashes
- **Security Hardening** — Secret scanning, prompt injection detection, URL safety, content isolation

### Agent Runtime

- **Tool Governance** — Risk-classified tool execution with approval gates, guardrails, progressive disclosure
- **Execution Backends** — Local, Docker, SSH, Singularity, Modal, and Daytona sandboxes with resource limits
- **Browser Automation** — CDP client, SSRF guard, secret exfiltration prevention, cloud router, CamoFox stealth
- **Computer Use** — CUA protocol, vision routing, platform detection, delivery ladder, action execution
- **Voice & TTS** — Multi-engine TTS, voice input, real-time conversation, wake-word detection (R0), audio bridge
- **Advanced Tooling** — Delegation (sync/async), vision, checkpoints, fuzzy matching, clarification

### Model & Provider Ecosystem

- **13 Provider Adapters** — OpenAI, Anthropic, Gemini, Bedrock, Azure, DeepSeek, Fireworks, OpenRouter, Ollama, Vertex, xAI, Nous, MiniMax
- **Model Catalog** — Capability metadata, pricing, data-classification filtering, fail-closed for restricted data
- **Cost Guard** — Circuit breaker for spending limits with per-session and daily budgets
- **Fallback Chain** — Ordered provider selection with health tracking and risk-tier filtering
- **Message Normalization** — Unified request/response format across all providers

### Integration & Communication

- **MCP Transport** — Model Context Protocol over stdio and HTTP/SSE with governed bridge, schema cache, stdio watchdog auto-recycle
- **MCP Security** — Per-server capability restrictions, trust levels, OAuth 2.0 flow
- **Agent Communication Protocol (ACP)** — Session management, tool routing, event streaming, edit approval
- **Platform Adapters** — Telegram, Discord, Line, DingTalk, Feishu, Slack, WhatsApp, Signal, Matrix, Teams, Email with capability negotiation
- **Channel Adapters** — Webhook (HMAC), Telegram, Discord gateway with streaming delivery; relay WS auth with stateless wake gate

### Learning & Intelligence

- **Learning Loop** — Knowledge graph, session search, memory nudges, skill genesis & evolution
- **User Modeling** — Dialectic preference inference with privacy governance (R3 for sensitive inferences)
- **Correction Loop** — Pattern detection from user corrections with proactive suggestions
- **Skills Library** — 19 curated skills across 6 domains with risk-tier gating
- **Skills Ecosystem** — Hub with quarantine, provenance tracking, blueprint bridge, cron scheduling

### Coordination & Context

- **Kanban Multi-Agent** — Board management, swarm coordination, task decomposition, worker lifecycle
- **Context Management** — Coding context builder, token budget breakdown, priority eviction
- **Plugin System** — Sandboxed registry with model providers, platform adapters, memory/observability providers
- **Durable Workers** — SQLite-backed job queue with lease-based execution

### Interfaces & Operations

- **Web Dashboard** — Real-time panels (evidence viewer, policy explorer, session monitor, cost tracker), WebSocket hub, plugin API
- **Desktop Application** — Electron + React with hardened CSP, sandboxed renderer, governed IPC
- **Terminal UI** — Streaming composer, session panel, interrupt handling, status bar
- **Billing & Proxy** — Plan tiers, usage records, invoicing; governed proxy routing
- **Operations** — Graceful shutdown, restart guard, i18n (6 locales)
- **CLI & Developer Experience** — Doctor diagnostics, audit queries, policy inspection, evidence browsing
- **Observability** — Verification ledger, trajectory tracking, OTel + Prometheus, insights engine
- **Evaluation** — Hallucination challenge sets, golden regression fixtures, consensus replay

---

## Quick Start

### Prerequisites

- **Python 3.11+** (3.12 and 3.13 supported)
- (Optional) Docker for containerized deployment

### Installation

```bash
# Clone the repository
git clone https://github.com/shuneka/nseg-runtime.git
cd nseg-runtime

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"
```

### Run Tests

```bash
python -m pytest
# 2146 tests — all passing
```

### Start the API Server

```bash
uvicorn nseg_runtime.api.app:create_app --factory --host 0.0.0.0 --port 8000
```

### CLI Usage

```bash
# Run a governed request
python -m nseg_runtime run "draft a short status update"

# External operation (triggers R2 approval flow)
python -m nseg_runtime run "send status" --operation-class external_message --data-class internal

# Worker process
python -m nseg_runtime worker

# Job management
python -m nseg_runtime job status <job_id>

# Audit & approvals
python -m nseg_runtime audit trace <trace_id>
python -m nseg_runtime approval approve <approval_id>

# Provider & tool discovery
python -m nseg_runtime providers list
python -m nseg_runtime mcp list
python -m nseg_runtime skills list

# Diagnostics
python -m nseg_runtime doctor
```

### Docker

```bash
docker compose up -d
# Health check: http://localhost:8000/health
```

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                          Interface Layer                             │
│  Desktop (Electron) │ TUI │ Web Dashboard │ CLI │ REST API │ ACP   │
├─────────────────────────────────────────────────────────────────────┤
│                        Gateway Layer                                 │
│  Webhook │ Telegram │ Discord │ Slack │ WhatsApp │ Signal │ Teams  │
├─────────────────────────────────────────────────────────────────────┤
│                     Policy Risk Router                               │
│       R0 (fast) │ R1 (approval) │ R2 (async) │ R3 (HA)             │
├─────────────────────────────────────────────────────────────────────┤
│                  Orchestration Layer                                 │
│  Consensus │ MoA Engine │ Provider Pool │ Cost Guard │ Fallback    │
├─────────────────────────────────────────────────────────────────────┤
│                    Agent Loop Engine                                 │
│  Context Engine │ Session Store │ Kanban Swarm │ Learning Loop     │
├─────────────────────────────────────────────────────────────────────┤
│              Tool & Skill Governance                                 │
│  Builtin │ Browser │ Computer Use │ Voice │ MCP │ Skills │ Plugins │
├─────────────────────────────────────────────────────────────────────┤
│              Execution Backends                                      │
│  Local │ Docker │ SSH │ Singularity │ Modal │ Daytona              │
├─────────────────────────────────────────────────────────────────────┤
│                  Observability & Evidence                            │
│  Verification Ledger │ Trajectory │ Trace Export │ Insights        │
├─────────────────────────────────────────────────────────────────────┤
│                   Infrastructure Layer                               │
│  Workers │ Cron │ Storage │ Security │ Billing │ i18n │ Ops        │
└─────────────────────────────────────────────────────────────────────┘
```

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full design.

---

## Module Map

| Module | Purpose |
|--------|---------|
| `policy/` | Risk routing, rule sets, reason codes, downgrade |
| `consensus/` | Multi-model panels, judge, synthesis, cache |
| `orchestration/` | MoA engine, model registry, usage pricing, credits, provider pool |
| `agent/` | Conversation loop, context engine, sessions |
| `acp/` | Agent Communication Protocol: sessions, tools, events, permissions, edit approval |
| `providers/` | 13 provider adapters, catalog, normalization, fail-closed data classification, cost guard, fallback chain, model switch |
| `tools/` | Builtin tools (incl. LSP diagnostics R0 read-only), delegation, guardrails, fuzzy match, checkpoints |
| `tools/browser/` | CDP client, SSRF guard, secret exfil guard, cloud router, CamoFox, LightPanda |
| `tools/computer_use/` | CUA protocol, vision routing, platform detection, action execution |
| `tools/voice/` | TTS engine, voice input, conversation, wake-word detection (R0), audio bridge |
| `skills/` | Skills hub, AST audit at intake, quarantine, provenance, blueprint bridge, cron, curated library (19 skills) |
| `plugins/` | Sandboxed plugin registry, model/platform/memory/observability providers |
| `mcp/` | MCP transport (stdio/HTTP), lifecycle + stdio watchdog, schema cache, governed bridge, catalog, security policy, OAuth |
| `execution/` | Terminal backends: local, Docker, SSH, Singularity, Modal, Daytona; resource limits |
| `kanban/` | Board management, swarm coordination, task decomposition, worker lifecycle, isolation |
| `learning/` | Knowledge graph, session search, memory nudge, skill genesis/evolution, user modeling, correction loop |
| `context/` | Context window management, coding context builder, token budget breakdown |
| `worker/` | Persistent queue, lease runner, notifications |
| `gateway/` | Channel adapters, session manager, relay WS auth + wake gate, streaming delivery |
| `channels/platforms/` | Telegram, Discord, Line, DingTalk, Feishu, Slack, WhatsApp, Signal, Matrix, Teams, Email adapters |
| `security/` | Secret scanner, injection detection, URL safety, content isolation |
| `security/secrets/` | Bitwarden, 1Password, env, command sources; credential pool, access audit |
| `observability/` | Verification ledger, trajectory, trace export, insights, usage accounting, metrics |
| `memory/` | Vector search, provider protocol, promotion |
| `extensions/` | Plugin loader, capability sandbox, certification |
| `cron/` | Scheduler, blueprints, job definitions |
| `evaluation/` | Governance eval harness, verification recipes, challenge runner, consensus replay |
| `evidence/` | HTTP fetch, readability, metadata, caching |
| `storage/` | SQLite store, migrations, audit |
| `configuration/` | Env config, profiles, validation |
| `runtime/` | Runtime context, shutdown, pipeline |
| `api/` | FastAPI routes, auth, dashboard |
| `dashboard/` | Web dashboard app, auth, WebSocket hub, plugin API, panels |
| `tui/` | Terminal UI: composer, stream view, session panel, status bar, interrupt |
| `billing/` | Plan tiers, usage records, invoicing |
| `proxy/` | Governed proxy routing |
| `i18n/` | Internationalization (6 locales) |
| `operations/` | Graceful shutdown, restart guard |
| `cli/` | Doctor, audit, policy, evidence, consensus, providers, security, gateway, skills |
| `apps/desktop/` | Electron + React desktop application (TypeScript) |

---

## Configuration

Copy `.env.example` to `.env` and configure:

```bash
cp .env.example .env
```

| Variable | Default | Description |
|----------|---------|-------------|
| `NSEG_PROFILE` | `developer` | Profile: developer, team, regulated, high-assurance |
| `NSEG_CONFIG_DIR` | `config` | Configuration directory |
| `NSEG_DB_PATH` | `data/nseg.db` | SQLite database path |
| `NSEG_LOG_LEVEL` | `INFO` | Logging level |
| `NSEG_API_TOKEN` | — | API bearer token (required in production) |
| `OPENAI_API_KEY` | — | OpenAI API key |
| `ANTHROPIC_API_KEY` | — | Anthropic API key |

### Configuration Profiles

| Profile | Required Keys | Behavior |
|---------|--------------|----------|
| `developer` | None | Relaxed, all operations allowed locally |
| `team` | `OPENAI_API_KEY` | Standard governance |
| `regulated` | Both keys | Strict approval flows |
| `high-assurance` | Both keys | All R2+ escalates to R3 |

See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for production configuration.

---

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run full test suite (2146 tests)
python -m pytest

# Run specific module tests
python -m pytest tests/policy/
python -m pytest tests/consensus/
python -m pytest tests/evaluation/

# Lint
ruff check src/ tests/

# Format
ruff format src/ tests/
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide.

---

## Documentation

| Document | Description |
|----------|-------------|
| [Architecture](docs/ARCHITECTURE.md) | System design, data flow, risk tiers |
| [Deployment](docs/DEPLOYMENT.md) | Production deployment, Docker, multi-worker |
| [API Reference](docs/API.md) | REST endpoint documentation |
| [Changelog](CHANGELOG.md) | Version history |
| [Contributing](CONTRIBUTING.md) | Development guide, code conventions |
| [Security](SECURITY.md) | Vulnerability reporting, production checklist |

---

## Security

NSEG Runtime is designed with a **fail-closed** security posture:

- Unknown operations are denied by default
- All inbound webhooks require HMAC verification
- Secrets are never logged; environment-variable only
- MCP subprocess execution is sandboxed
- Plugin code runs in a capability-restricted sandbox

To report a vulnerability, see [SECURITY.md](SECURITY.md). **Do not open a public issue.**

---

## Roadmap

- [ ] Multi-tenant isolation with per-org policy overrides
- [ ] Distributed consensus across geographic regions
- [ ] WASM-based plugin sandbox (replacing process isolation)
- [ ] Real-time collaboration sessions (CRDT-backed)
- [ ] Formal verification of policy rule sets
- [ ] SOC 2 Type II evidence automation

---

## Community

- **Issues** — [Bug reports & feature requests](../../issues)
- **Discussions** — [Questions & ideas](../../discussions)
- **Contributing** — [Development guide](CONTRIBUTING.md)

---

## License

[Apache License 2.0](LICENSE)

---

<div align="center">

**Built with governance-first principles.** Every action is classified, approved, and recorded.

</div>
