Skip to content

AETHERRA_SELF_IMPROVEMENT_API.md

Latest commit

 

History

History
451 lines (337 loc) · 12.9 KB

AETHERRA_SELF_IMPROVEMENT_API.md

File metadata and controls

451 lines (337 loc) · 12.9 KB

Aetherra Self-Improvement API

Updated: 2025-01-26

This document describes the Self-Improvement API endpoints exposed by the Aetherra Hub, which enable manual approval and application of autonomously generated improvement proposals. These endpoints integrate with the Lyrixa GUI Self-Improve tab and support both Hot Module Reload (HMR) and manual OS restart workflows.

Purpose and scope

  • Define the REST API contract for applying self-improvement proposals
  • Document harmonized HTTP status codes and response schemas
  • Explain the restart_required flag semantics and HMR integration
  • Provide guidance for UI integration and error handling
  • Document batch operations and approval workflows

Architecture overview

The Self-Improvement API is part of the Aetherra Maintenance System autonomous feedback loop:

  1. Homeostasis System monitors OS health and detects performance issues
  2. Self-Improvement Engine generates optimization proposals based on metrics
  3. Self-Improvement API (this document) enables manual review and approval via GUI
  4. Hot Module Reload (HMR) Controller applies approved proposals at runtime when enabled
  5. Self-Incorporation Service integrates changes and reports outcomes back to metrics

The API provides a human-in-the-loop gate for proposal application, ensuring safe evolution with user oversight.

Endpoints

POST /api/selfimprove/apply

Apply a single improvement proposal with optional HMR-based hot reload.

Request body:

{
  "proposal_id": "string",          // Required: Unique ID of proposal to apply
  "force": false,                   // Optional: Skip safety checks (default: false)
  "user": "string"                  // Optional: User ID for audit trail
}

Success response (HTTP 200):

{
  "ok": true,
  "status": "approved",             // Proposal approved
  "message": "Proposal applied successfully via HMR",
  "restart_required": false,        // HMR applied, no restart needed
  "proposal_id": "string"
}

Success response (HTTP 200 - HMR unavailable):

{
  "ok": true,
  "status": "approved",
  "message": "Proposal approved - HMR not available, OS restart required",
  "restart_required": true,         // Manual OS restart needed
  "proposal_id": "string"
}

Error response (HTTP 400):

{
  "ok": false,
  "error": "string",                // Error description
  "details": "string"               // Optional: Additional error context
}

Response codes:

  • 200 OK: Proposal approved (may require restart based on restart_required flag)
  • 400 Bad Request: Invalid request, proposal application failed, or HMR error

Restart required semantics:

HMR Status Applied restart_required HTTP Code UI Behavior
Enabled & available Yes false 200 Show success, no restart badge
Unavailable No true 200 Show "OS Restart Required" badge
Error during apply No true 400 Show error message
Disabled No true 200 Show "OS Restart Required" badge

POST /api/selfimprove/batch-apply

Apply multiple improvement proposals in a single operation.

Request body:

{
  "proposal_ids": ["string", ...],  // Required: Array of proposal IDs
  "force": false,                   // Optional: Skip safety checks (default: false)
  "user": "string"                  // Optional: User ID for audit trail
}

Success response (HTTP 200):

{
  "ok": true,
  "applied": 3,                     // Count of successfully applied proposals
  "failed": 1,                      // Count of failed proposals
  "restart_required": true,         // Any proposal requiring restart?
  "results": [
    {
      "proposal_id": "string",
      "ok": true,
      "status": "approved",
      "message": "Applied via HMR",
      "restart_required": false
    },
    {
      "proposal_id": "string",
      "ok": false,
      "error": "Application failed",
      "restart_required": true
    }
  ]
}

Response codes:

  • 200 OK: Batch operation completed (check individual results for per-proposal status)
  • 400 Bad Request: Invalid request format or critical error

Batch semantics:

  • Batch operation continues even if individual proposals fail
  • Global restart_required is true if any proposal requires restart
  • Individual results include per-proposal restart_required flags
  • Empty proposal_ids array returns 400 Bad Request

Status code harmonization

Prior to 2025-01-26, the Self-Improvement API used multiple HTTP status codes to signal different outcomes (503 for HMR unavailable, 502 for selfinc failure, 500 for HMR errors). This created complexity in client logic and violated REST conventions.

Current harmonized approach:

  1. HTTP 200: Proposal approved (check restart_required flag to determine if OS restart needed)
  2. HTTP 400: Request invalid or proposal application failed

Benefits:

  • Simplified client logic: Check body.ok and restart_required flag only
  • RESTful semantics: 2xx for success, 4xx for client errors
  • Single source of truth: restart_required flag drives UI behavior

Migration note: Clients previously checking res.status === 503 should now check body.restart_required === true.

Hot Module Reload (HMR) integration

HMR enables runtime application of approved proposals without OS restart. When HMR is enabled and available, the Self-Improvement API will attempt to apply proposals via the HMR Controller.

Enabling HMR

Set these environment variables before launching Aetherra OS:

export AETHERRA_HMR_ENABLED=1          # Enable HMR system
export AETHERRA_HMR_MODE=safe          # Use safe reload mode
export AETHERRA_HMR_AUTO_RELOAD=1      # Auto-reload on file changes

Or in PowerShell:

$env:AETHERRA_HMR_ENABLED = "1"
$env:AETHERRA_HMR_MODE = "safe"
$env:AETHERRA_HMR_AUTO_RELOAD = "1"

HMR availability detection

The API checks HMR availability before applying proposals:

  1. HMR enabled: restart_required: false when successfully applied
  2. HMR unavailable: restart_required: true, user must manually restart OS
  3. HMR error: HTTP 400 with error details

HMR safety guarantees

  • Safe mode: Only applies proposals passing safety validation
  • Rollback: Automatic rollback on application errors
  • Audit trail: All HMR operations logged to kernel metrics
  • SLO monitoring: Homeostasis monitors post-application health

UI integration

The Lyrixa GUI Self-Improve tab integrates with this API to provide manual proposal review and approval.

Workflow

  1. Fetch proposals: UI calls GET /api/selfimprove/proposals to list pending proposals
  2. User review: Proposals displayed with title, description, and metrics
  3. Approval: User clicks "Approve" button on selected proposal
  4. Apply: UI calls POST /api/selfimprove/apply with proposal ID
  5. Check result:
    • If ok: true and restart_required: false: Show success (HMR applied)
    • If ok: true and restart_required: true: Show "OS Restart Required" badge
    • If ok: false: Show error message

React example (App.tsx)

const approveSuggestion = async (proposalId: string) => {
  try {
    const res = await fetch('/api/selfimprove/apply', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ proposal_id: proposalId })
    });

    const body = await res.json();

    if (body && body.ok === true) {
      // Proposal approved successfully
      if (body.restart_required) {
        // Show "OS Restart Required" badge
        showRestartBadge(proposalId);
      } else {
        // HMR applied, no restart needed
        showSuccess("Proposal applied successfully");
      }
    } else {
      // Application failed
      showError(body.error || "Application failed");
    }
  } catch (err) {
    showError("Network error: " + err.message);
  }
};

Batch approval example

const approveMultiple = async (proposalIds: string[]) => {
  const res = await fetch('/api/selfimprove/batch-apply', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ proposal_ids: proposalIds })
  });

  const body = await res.json();

  if (body.ok) {
    console.log(`Applied: ${body.applied}, Failed: ${body.failed}`);

    if (body.restart_required) {
      showRestartBadge("multiple");
    }

    // Process individual results
    body.results.forEach(result => {
      if (result.ok) {
        updateProposalStatus(result.proposal_id, "approved");
      } else {
        showProposalError(result.proposal_id, result.error);
      }
    });
  }
};

Error handling

Common error scenarios

Invalid proposal ID:

{
  "ok": false,
  "error": "Proposal not found",
  "details": "proposal_id 'invalid-id' does not exist"
}

HMR application error:

{
  "ok": false,
  "error": "HMR application failed",
  "details": "Module reload failed: ImportError in target module"
}

Self-Incorporation service unavailable:

{
  "ok": false,
  "error": "Self-Incorporation service not available",
  "details": "Cannot apply proposal without selfinc service"
}

Client retry strategy

  • 400 Bad Request: Do not retry (client error)
  • 500 Internal Server Error: Retry with exponential backoff
  • Network errors: Retry up to 3 times with exponential backoff

Security and audit

Authorization

  • Proposals require manual user approval via GUI
  • Batch operations limited to 10 proposals per request
  • force flag requires elevated privileges (planned)

Audit trail

All proposal applications are logged with:

  • Timestamp
  • User ID (if provided)
  • Proposal ID
  • Application outcome
  • HMR status
  • Restart required flag

Audit logs available via kernel metrics and Homeostasis reporting.

Configuration

Environment variables

  • AETHERRA_HMR_ENABLED: Enable HMR system (default: 0)
  • AETHERRA_HMR_MODE: HMR mode (safe/aggressive, default: safe)
  • AETHERRA_HMR_AUTO_RELOAD: Auto-reload on file changes (default: 0)
  • AETHERRA_SELFINC_STRICT: Require signed proposals (default: 0)

Runtime configuration

Configuration available via config.json:

{
  "self_improvement": {
    "enabled": true,
    "hmr_enabled": true,
    "hmr_mode": "safe",
    "batch_limit": 10,
    "require_approval": true
  }
}

Observability

Metrics

Self-Improvement API metrics exposed via /metrics endpoint:

  • aetherra_selfimprove_apply_total: Total apply attempts (labels: status, restart_required)
  • aetherra_selfimprove_apply_duration_seconds: Apply operation duration
  • aetherra_selfimprove_hmr_success_total: Successful HMR applications
  • aetherra_selfimprove_hmr_error_total: Failed HMR applications

Health checks

Check Self-Improvement Engine status:

GET /api/stats

Response includes:

{
  "self_improvement_engine": {
    "enabled": true,
    "status": "idle",
    "proposals_pending": 3
  }
}

Related documentation

Appendices

Complete response schema

ApplyResponse:

interface ApplyResponse {
  ok: boolean;              // Operation success
  status?: string;          // "approved" | "rejected" | "error"
  message: string;          // Human-readable outcome
  restart_required: boolean; // OS restart needed?
  proposal_id: string;      // Applied proposal ID
  error?: string;           // Error message if ok: false
  details?: string;         // Additional error context
}

BatchApplyResponse:

interface BatchApplyResponse {
  ok: boolean;              // Overall operation success
  applied: number;          // Count of successful applications
  failed: number;           // Count of failures
  restart_required: boolean; // Any proposal requiring restart?
  results: ApplyResponse[]; // Per-proposal results
}

Example curl commands

Apply single proposal:

curl -X POST http://localhost:3001/api/selfimprove/apply \
  -H "Content-Type: application/json" \
  -d '{"proposal_id": "prop-123", "user": "admin"}'

Batch apply:

curl -X POST http://localhost:3001/api/selfimprove/batch-apply \
  -H "Content-Type: application/json" \
  -d '{"proposal_ids": ["prop-123", "prop-456"], "user": "admin"}'

Status: ✅ Implemented (harmonized status codes, restart_required flag, HMR integration, batch operations)