AI-native development environment unifying code, memory, and intelligent automation

Aetherra pairs a lightweight Hub (APIs + metrics) with the Lyrixa AI assistant, pluggable memory systems, an intent-driven workflow language (.aether), and first-class observability. Core subsystems ship ready-to-use: Engine, Memory, Agents, Kernel, Chat, Security, and Coding system.

✅ Chat streams: SSE v2 resume (Last-Event-ID), consistent final payload with evidence[] and scratchpad_policy.

✅ Plugin UX: install/uninstall from GUI; sidebar/panels auto-reconfigure without blocking chat. (Hub lists/install endpoints provide the backend.)

✅ Plugin safety: manifest signing on (or policy explained), capability gates enforced, network allowlist documented.

✅ Kernel health: night cycle runs; heartbeats/metrics green; backpressure limits set in env (document defaults).

✅ Memory health: core works even when optional components are absent; typed recall + legacy adapters described.

✅ Spec→Tests gate enabled in your dev flow; tools/verify_aether_scripts.py wired in CI.

🚀 v0.3.0 shipped as "Stable" - High test reliability and security readiness achieved.

• v0.3.1 (≤ 30 days): ≥ 25%
• v0.3.2 (≤ 60 days): ≥ 40%
• v0.3.3 (≤ 90 days): ≥ 60%

Coverage waiver active: No regression below 13.80% allowed; new/changed files require unit tests.

Why Aetherra: Explicit feature gating via environment flags (secure by default), Prometheus-first metrics for every subsystem, and human-readable workflow artifacts for auditable evolution.

Aetherra/ ├── aetherra_core/ # Core engine, kernel, and orchestration

        │   ├── aetherra_os.py      # Main OS launcher

        │   ├── aetherra_kernel_loop.py

        │   └── aetherra_agent_fabric.py

        ├── lyrixa/                 # AI assistant and chat interfaces

        │   ├── lyrixa_basic.py     # Core chat implementation

        │   └── ui/                 # GUI components

        └── plugins/                # Extensible plugin system

        ├── memory_plugins/

        └── agent_plugins/

Public Hub Endpoints (default port 3001):

• /api/ai/ask - Direct chat interface
• /api/ai/stream - SSE streaming chat
• /api/lyrixa/chat - Lyrixa bridge
• /api/agents/submit - Task orchestrator
• /api/plugins/* - Plugin management
• /metrics - Prometheus metrics

Verify kernel and services start properly:

python tools/os_smoke.py

Launch local APIs and services with the AI API enabled:

python tools/run_hub_ai_api.py --port 3001
# Hub starts on http://localhost:3001 (AI API enabled, streaming on by default)

Direct Ask:

curl -X POST http://localhost:3001/api/ai/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello, what can you help me with?"}'

SSE Streaming:

curl -N http://localhost:3001/api/ai/stream \
  -H "Accept: text/event-stream" \
  -d "query=Tell me about Aetherra"

Lyrixa Bridge:

curl -X POST http://localhost:3001/api/lyrixa/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "System status check", "context": {}}'

Check system health:

curl http://localhost:3001/metrics
curl http://localhost:3001/api/health

STORM (Sheaf-Theoretic Optimal Recall via Manifolds) brings mathematically optimal semantic memory retrieval to Aetherra using optimal transport theory and sheaf coherence.

STORM transforms memory recall from keyword matching to geometric optimization:

• Optimal Transport: Uses Wasserstein distance to find the "cheapest" path between query and memory embeddings
• Sheaf Coherence: Ensures retrieved memories form a mathematically consistent structure
• Quality Guarantee: Retrieval is provably optimal under geometric constraints

In Python:

from Aetherra.aetherra_core.memory.aetherra_memory_engine import AetherraMemoryEngineAdvanced

engine = AetherraMemoryEngineAdvanced()

# Store memories
await engine.remember(
    content="STORM uses optimal transport for recall",
    tags=["storm", "memory"],
    category="docs"
)

# Recall with STORM (hybrid mode recommended)
result = await engine.recall_typed(
    query="how does STORM work?",
    recall_strategy="storm_hybrid",  # or "storm" for pure STORM
    limit=5
)

# Access results
for item in result.items:
    print(item)

# Check STORM metadata
storm_meta = result.metadata.get("storm_meta", {})
print(f"Transport cost: {storm_meta.get('transport_cost')}")
print(f"Sheaf inconsistency: {storm_meta.get('sheaf_inconsistency')}")

In .aether Scripts:

# Query STORM from workflow scripts
@recall
  query: "memory optimization techniques"
  strategy: storm_hybrid
  limit: 10

# Check coherence health
@storm.sheaf_status
  -> Returns: {cells: N, inconsistency: float, health: "ok"|"warning"|"critical"}

# Guard workflow execution
@storm.coherence_guard
  threshold: 0.3
  -> Aborts if sheaf inconsistency > threshold

• base: Traditional keyword/embedding recall (baseline)
• storm: Pure STORM optimal transport (experimental)
• storm_hybrid: STORM with baseline fallback (recommended)

Production Recommendation: Use storm_hybrid for best reliability while collecting metrics in shadow mode.

STORM acceptance testing shows:

• Quality: Recall relevance ≥ baseline (mathematically optimal)
• Latency: p95 < 500ms (avg ~160ms on test corpus)
• Stability: Sheaf inconsistency < 0.3 (coherent structure)
• Robustness: Graceful degradation on failures

See docs/STORM_AB_TESTING_RESULTS.md for full acceptance test results.

Enable STORM in your environment:

# Enable STORM with shadow mode (safe production testing)
export AETHERRA_MEMORY_STORM=1
export AETHERRA_STORM_SHADOW_MODE=1

# Or use hybrid mode directly
export AETHERRA_MEMORY_STORM=1
export AETHERRA_STORM_SHADOW_MODE=0

Monitor STORM metrics at /metrics:

• storm_recalls_total - Total STORM recalls
• storm_shadow_comparisons_total - Shadow mode comparisons
• storm_sheaf_inconsistency - Current coherence health

STORM respects all memory policy guards:

• Data flows only through policy-protected core memory
• storm_cells table stores 200-char excerpts (not full content)
• Privacy classes enforced before STORM access
• No bypass paths around redaction hooks

See docs/STORM_SECURITY_VERIFICATION.md for security audit details.

Start the OS with STORM integrated (shadow mode collects metrics, returns baseline results):

export AETHERRA_MEMORY_STORM=1
export AETHERRA_STORM_SHADOW_MODE=1
python aetherra_os_launcher.py --mode full -v

On successful boot, logs include a post-boot STORM status line like:

[STORM:POST-BOOT] enabled=1 shadow_mode=1 backend=ot:earthmover tt_rank_cap=128

Submit tasks to the orchestrator and track their progress:

curl -X POST http://localhost:3001/api/agents/submit \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "analysis",
    "description": "Analyze system performance metrics",
    "priority": "normal",
    "context": {}
  }'

Task Shape:

• task_type: analysis, automation, monitoring, custom
• description: Human-readable task description
• priority: low, normal, high, urgent
• context: Additional parameters and data

# Get task by ID
curl http://localhost:3001/api/agents/status/{task_id}

# List all tasks
curl http://localhost:3001/api/agents/tasks

Task States: pending → running → completed | failed | cancelled

Manage plugins dynamically through Hub endpoints with automatic UI updates:

# List installed plugins
curl http://localhost:3001/api/plugins/list

# Install plugin
curl -X POST http://localhost:3001/api/plugins/install \
  -H "Content-Type: application/json" \
  -d '{"name": "plugin_name", "source": "local|registry"}'

# Uninstall plugin
curl -X DELETE http://localhost:3001/api/plugins/uninstall/plugin_name

# Plugin status and metadata
curl http://localhost:3001/api/plugins/status/plugin_name

Lyrixa's GUI automatically refreshes when plugins change:

• Sidebar panels: Auto-generated when plugin declares UI surface
• Install/uninstall: Available directly from the GUI
• Non-intrusive: Plugin operations don't block chat functionality
• Real-time updates: Plugin status changes reflect immediately

See /api/plugins/* endpoints for complete plugin management API.

"Stable" GUI means flawless user experience across all core interactions:

• SSE v2 resume: Last-Event-ID support for reliable stream resumption
• Consistent payloads: Final responses include evidence[] and scratchpad_policy
• No interruptions: Plugin operations never block chat functionality

• UI auto-generation: Panels automatically appear when plugins declare UI surfaces
• Live install/uninstall: Direct from GUI without service restarts
• Sidebar management: Plugin panels dynamically reconfigure layout
• State preservation: Chat context maintained during plugin changes

• Streaming connections handle network interruptions gracefully
• Plugin manifest validation before UI integration
• Resource isolation prevents plugin failures from affecting chat
• Responsive design adapts to plugin panel additions/removals

The GUI meets "stable" criteria when these behaviors work consistently under normal operation and edge cases (network drops, plugin failures).

High-value environment variables for system behavior:

# Enable AI APIs with authentication
export AETHERRA_AI_API_ENABLED=1
export AETHERRA_AI_API_TOKEN=your_secure_token
export AETHERRA_AI_API_REQUIRE_TOKEN=1

# Enable streaming chat
export AETHERRA_AI_API_STREAM=1

# Enable safety mode (strict validation)
export AETHERRA_SAFETY_MODE=1

# Network allowlist for security
export AETHERRA_NETWORK_ALLOWLIST="localhost,127.0.0.1,.aetherra.dev"
export AETHERRA_NET_STRICT=1

# Kernel queue and backpressure control
export AETHERRA_KERNEL_QUEUE_SIZE=1000
export AETHERRA_KERNEL_BACKPRESSURE_LIMIT=5000

# Plugin timeouts and concurrency
export AETHERRA_PLUGIN_TIMEOUT=30
export AETHERRA_PLUGIN_MAX_CONCURRENT=10

See Environment Variables Index for complete list.

• Manifest verification: All plugins require signed manifests
• Code integrity: .aether scripts validated with cryptographic signatures
• Trust chains: Configurable signing authorities and key management

• Permission model: Plugins request specific capabilities (network, file, memory)
• Runtime enforcement: Capability violations terminate plugin execution
• Audit logging: All capability requests and denials logged

• Allowlist enforcement: Configurable network destination restrictions
• Protocol filtering: HTTP/HTTPS only in strict mode
• Proxy support: Corporate network compatibility

• Opt-in telemetry: No data collection without explicit consent
• Differential privacy: Statistical noise added to usage metrics
• Local-first: Core functionality works without network connectivity

# Lock down all security features
export AETHERRA_PROFILE=prod
export AETHERRA_NET_STRICT=1
export AETHERRA_SCRIPT_VERIFY_STRICT=1
export AETHERRA_PLUGIN_SIGNING_REQUIRED=1

Intent-driven workflow language with static verification:

goal: "Analyze system performance and generate report"

workflow:
  - step: "collect_metrics"
    plugin: "system_monitor"
    params:
      duration: "5m"

  - step: "analyze_data"
    plugin: "data_analyzer"
    depends_on: ["collect_metrics"]

parallel:
  - task: "cpu_analysis"
    plugin: "cpu_profiler"
  - task: "memory_analysis"
    plugin: "memory_profiler"

policy:
  timeout: "10m"
  retry_count: 3
  failure_action: "notify"

require:
  capabilities: ["system_read", "file_write"]
  plugins: ["system_monitor>=1.0", "data_analyzer"]

Verify .aether scripts in CI/CD:

# Basic verification
python tools/verify_aether_scripts.py --root .

# Strict mode (production)
python tools/verify_aether_scripts.py --root . --strict
export AETHERRA_SCRIPT_VERIFY_STRICT=1

Verification checks:

• Syntax validity and schema compliance
• Plugin dependency resolution
• Capability requirement validation
• Signature verification (in strict mode)

# Kernel status and metrics
curl http://localhost:3001/api/kernel/status
curl http://localhost:3001/api/kernel/metrics

# Memory system health
curl http://localhost:3001/api/memory/status
curl http://localhost:3001/api/memory/stats

# Overall system health
curl http://localhost:3001/api/health

Access metrics at http://localhost:3001/metrics:

• aetherra_kernel_tasks_total: Total tasks processed
• aetherra_memory_operations_total: Memory read/write operations
• aetherra_plugin_executions_total: Plugin execution counts
• aetherra_api_requests_total: HTTP API request metrics
• aetherra_errors_total: Error counts by subsystem

# Security events and alerts
curl http://localhost:3001/api/security/alerts
curl http://localhost:3001/api/security/events/recent

Alerts include capability violations, signature failures, and network policy breaches.

# Basic system boot verification
python tools/os_smoke.py

# Headless mode (CI/CD)
AETHERRA_QUIET=1 python tools/os_smoke.py

# Verify specification compliance
python tools/spec_tests_gate.py

# Check that tests cover documented features
python tools/verify_docs_consistency.py

# Run tests with coverage no-drop validation
python tools/quality_gates.py

# Coverage must not decrease from baseline
pytest --cov=aetherra_core --cov-fail-under=85

# .aether script validation
python tools/verify_aether_scripts.py --strict

# Code quality and security
python tools/quality_gates.py --all

Located in tests/capabilities/:

• test_ownership_memory.py: Memory ownership and isolation
• test_lyrixa_ownership_answer.py: Chat ownership validation
• test_hub_metrics_observability.py: Metrics and monitoring
• test_lyrixa_chat_bridge_schema.py: API schema compliance

# Run all capability tests
pytest tests/capabilities/

# Run specific capability validation
pytest tests/capabilities/test_ownership_memory.py

• QFAC: Fixed timing-based test; system passes stability checks
• Type system: Full PEP 585 modernization (Dict→dict, Optional→| None)
• Security: All scanners clean; strict defaults validated
• Tests: 98 passed, 1 skipped; 13.80% coverage (up from 8.36%)

• Script/plugin signing with manifest verification
• Capability gates enforced at runtime
• Network allowlist with strict mode toggles
• Audit logging for all security events

• SSE v2 with Last-Event-ID resume capability
• Event-driven kernel with backpressure control
• Plugin UI auto-generation without chat blocking
• Prometheus metrics for all subsystems

• No-regression coverage gate (13.80% baseline)
• Spec→Tests gate enabled in CI
• Static verification for .aether scripts
• Enhanced test reliability across all subsystems

• Chat/Kernel: SSE v2 streaming, event-driven coordination
• Agents: Task orchestrator with status tracking
• Memory: Persistent + quantum-augmented layers
• Security: Script signing, capability gates, network allowlist
• Observability: Prometheus metrics, health endpoints

• Plugin Ecosystem: Core system ready, expanding plugin library
• GUI Stability: Chat stable, plugin UI refinements ongoing
• Documentation: API docs complete, user guides expanding

• AI Trainer System: Adaptive model fine-tuning
• Advanced Memory: Semantic search and graph relationships
• Enterprise Features: SSO integration, advanced RBAC
• Multi-tenant: Isolated workspaces and resource quotas

🚀 v0.3.0 Released as Stable (Current)

Major achievements:

• 98 passed, 1 skipped tests (99% pass rate)
• All security scans clean
• QFAC & core systems operational
• PEP 585 modernization complete
• Coverage improved from 8.36% → 13.80%

Next Focus: Coverage Growth & Enhancement

• v0.3.1 (≤ 30 days): Coverage to 25%, plugin ecosystem expansion
• v0.3.2 (≤ 60 days): Coverage to 40%, GUI stability improvements
• v0.3.3 (≤ 90 days): Coverage to 60%, advanced memory features

Track progress at GitHub Issues and Project Board.

See CONTRIBUTING.md for development setup, coding standards, and contribution guidelines.

This project is licensed under the GNU General Public License v3.0 or later. See LICENSE for details.