phase1_skeleton/API_QUICKSTART.md

# NullAI REST API - Quick Start Guide

Get the consciousness system running with HTTP in 5 minutes.

## Installation (30 seconds)

```bash
# Install dependencies
pip install flask requests

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

## Start the Server (10 seconds)

```bash
# 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:**
```python
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)

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

```javascript
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

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

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

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

```json
{
  "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:

```bash
# 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:

```bash
# 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:

```bash
# 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](API_DOCUMENTATION.md) for complete endpoint details
2. **Explore Examples**: Check client examples in [api_client.py](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?**
```bash
# Check if port is in use
lsof -i :5000
# Use different port
python api_server.py --port 8080
```

**Connection refused?**
```bash
# Make sure server is running in another terminal
# Check the URL is correct
curl http://localhost:5000/api/v1/health
```

**Out of memory?**
```bash
# 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!** 🚀