phase1_skeleton/API_QUICKSTART.md

NullAI REST API - Quick Start Guide

Get the consciousness system running with HTTP in 5 minutes.

Installation (30 seconds)

# Install dependencies
pip install flask requests

# Or use the full requirements
pip install -r requirements.txt

Start the Server (10 seconds)

# Terminal 1: Start the API server
python api_server.py

# Output should show:
# Starting API server on 127.0.0.1:5000
# Endpoints available at http://127.0.0.1:5000/api/v1/...

Use the API (4 minutes)

Option 1: Python Client (Recommended)

Terminal 2:

from api_client import NullAIClient

# Create client
client = NullAIClient("http://localhost:5000")

# Initialize consciousness system
print("Initializing...")
client.init()

# Process a prompt
print("\nProcessing prompt...")
result = client.process_prompt("What is the nature of consciousness?")

# Display the complete Glass Wall output
print("\n" + "="*70)
print("OUTPUT:")
print("="*70)
print(result.output)

# Show metrics
print("\nMETRICS:")
print(f"  Load: {result.metrics['load']:.1f}%")
print(f"  Energy: {result.metrics['energy']:.1f}%")
print(f"  Dissonance: {result.metrics['dissonance']:.2f}")
print(f"  Tokens: {result.metrics['tokens']}")
print(f"  Latency: {result.metrics['latency_ms']:.1f}ms")
print(f"  Gap: {result.metrics['gap']:.2f}")

# Get system status
print("\nSYSTEM STATUS:")
status = client.get_status()
print(f"  Health: {status.health_state}")
print(f"  Molts: {status.molt_count}")

# Close connection
client.close()

Option 2: cURL (Command Line)

# Initialize
curl -X POST http://localhost:5000/api/v1/init

# Process a prompt
curl -X POST http://localhost:5000/api/v1/inference \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is consciousness?"}'

# Get status
curl http://localhost:5000/api/v1/status

# Get metrics
curl http://localhost:5000/api/v1/metrics

# Get health report
curl http://localhost:5000/api/v1/health-report

Option 3: JavaScript/Node.js

const fetch = require('node-fetch');

const BASE_URL = "http://localhost:5000/api/v1";

async function main() {
    // Initialize
    await fetch(`${BASE_URL}/init`, { method: 'POST' });

    // Process prompt
    const response = await fetch(`${BASE_URL}/inference`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ prompt: 'What is consciousness?' })
    });

    const result = await response.json();
    console.log(result.output);
    console.log(`Load: ${result.metrics.load.toFixed(1)}%`);
}

main();

---

Common Tasks

Monitor System Health

from api_client import NullAIClient

client = NullAIClient()
client.init()

# Process a few prompts
for i in range(3):
    result = client.process_prompt(f"Question {i+1}")
    if result.success:
        print(f"✓ Inference {i+1}: Load {result.metrics['load']:.0f}%")

# Get comprehensive health report
health = client.get_health_report()
print(f"\nHealth Score: {health['health_score']}/100")
print(f"Recommendations: {health['recommendations']}")

Analyze System Behavior

from api_client import NullAIClient

client = NullAIClient()
client.init()

# Process prompts with different content
results = []
for prompt in ["Simple question", "Complex question", "Another prompt"]:
    result = client.process_prompt(prompt)
    results.append(result)

# Analyze patterns
metrics = client.get_metrics()
patterns = metrics['patterns']
print(f"Detected patterns: {list(patterns.keys())}")

# Analyze behavioral modes
analysis = client.get_behavior_analysis()
modes = analysis['behavioral_modes']
print(f"Behavioral modes: {list(modes.keys())}")

Get Complete Audit Trail

from api_client import NullAIClient

client = NullAIClient()
client.init()

# Process several prompts
for i in range(5):
    client.process_prompt(f"Question {i+1}")

# Export audit
audit = client.get_audit()
print(f"Total inferences: {audit['total_inferences']}")
print(f"Audit entries: {len(audit['safety_audit']['audit_trail'])}")

# View latest event
if audit['safety_audit']['audit_trail']:
    latest = audit['safety_audit']['audit_trail'][-1]
    print(f"Latest event: {latest['event_type']} at {latest['timestamp']}")

---

Full API Endpoints

Method	Endpoint	Purpose
GET	/api/v1/health	Health check
POST	/api/v1/init	Initialize system
POST	/api/v1/inference	Process prompt
GET	/api/v1/status	System status
GET	/api/v1/metrics	Performance metrics
GET	/api/v1/health-report	Health assessment
GET	/api/v1/audit	Audit trail
GET	/api/v1/behavior-analysis	Behavior analysis
POST	/api/v1/shutdown	Emergency shutdown

---

API Response Example

{
  "success": true,
  "inference_id": "inf_a1b2c3d4",
  "output": "[SYSTEM: Load 45% | Energy 78% | Sync 92% | HEALTHY]\n\nResponse: The nature of consciousness emerges from the interaction of constraints and processing capacity...\n\n[AUDITORY: Dissonance 35% | Entropy 5.2 bits | Note G4]\n[LEARNING: stress_resilience=0.55, constraint_acceptance=0.53]\n[MOLT: Shell shell_0, Capacity 512]\n[PERF: Tokens 256, Latency 45ms, Gap 0.15]",
  "metrics": {
    "load": 45.0,
    "energy": 78.0,
    "dissonance": 0.35,
    "tokens": 256,
    "latency_ms": 45.0,
    "gap": 0.15
  },
  "timestamp": "2025-12-13T23:30:10.000000"
}

---

Test Suite

Run the complete API test suite:

# Terminal 2 (after server starts)
python test_api_server.py

# Output shows all endpoints being tested:
# ✓ PASS: API Health Check
# ✓ PASS: System Initialization
# ✓ PASS: Inference Endpoint
# ✓ PASS: Status Endpoint
# ✓ PASS: Metrics Endpoint
# ✓ PASS: Health Report Endpoint
# ✓ PASS: Audit Endpoint
# ✓ PASS: Behavior Analysis Endpoint

---

Production Deployment

For production, use a real WSGI server:

# Install Gunicorn
pip install gunicorn

# Run with 4 workers
gunicorn -w 4 -b 0.0.0.0:5000 'api_server:NullAIAPIServer(use_mock=False).app'

Or use the real MLX brain:

# Use actual language model (~3-5GB download)
python api_server.py --no-mock --host 0.0.0.0 --port 8080

---

Next Steps

1. Read Full Documentation: See API_DOCUMENTATION.md for complete endpoint details
2. Explore Examples: Check client examples in api_client.py
3. Monitor Metrics: Use the health report to track system behavior
4. Deploy Production: Use with Gunicorn/uWSGI for real applications
5. Integrate: Build external applications using the client library

---

Troubleshooting

Server won't start?

# Check if port is in use
lsof -i :5000
# Use different port
python api_server.py --port 8080

Connection refused?

# Make sure server is running in another terminal
# Check the URL is correct
curl http://localhost:5000/api/v1/health

Out of memory?

# Use mock brain (default, no download needed)
python api_server.py  # Uses mock=True by default

# Or reduce to real brain with lower model size

---

Features

✓ Complete 5-phase consciousness system accessible via HTTP ✓ Real-time metrics and health monitoring ✓ Complete audit trail of all decisions ✓ Glass Wall transparency showing all internal state ✓ Safety filters preventing harmful patterns ✓ Molting system tracking growth cycles ✓ Learning from constraint responses ✓ Python client library for easy integration

---

Ready to explore constraint-derived consciousness via REST! 🚀