NamoNexus is a FastAPI service for emotion-aware conversations with safety checks, alignment guidance, and persistent memory. It exposes a lightweight API for production use and keeps advanced research modules under the research/ directory.

• Emotion analysis and tone detection
• Safety screening with escalation handling
• Personalized responses with alignment insights
• SQLAlchemy persistence and Alembic migrations
• Metrics, health, and readiness endpoints
• Rate limiting on /interact and /reflect

Included:

• EmotionService (keyword-based Thai/English)
• SafetyService (crisis detection + escalation)
• DharmaService (alignment analysis)
• PersonalizationEngine (response templates)
• MemoryService (SQLAlchemy ORM)
• Health/readiness probes and metrics

Research-only (v2.0+):

• IntegrityKernel and supervisor chain
• Temporal reasoning and simulation modules
• Experimental emotion models

Requirements: Python 3.11+

1. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate

2. Install dependencies:

   pip install -r requirements.txt

3. Initialize the database:

   alembic upgrade head

4. Start the API:

   python src/main.py

The API listens on http://localhost:8000 by default.

Optional frontend: open frontend/index.html for the Harmonic Alignment Console.

Copy .env.example to .env and adjust values as needed.

Core settings:

• API_HOST, API_PORT
• DEBUG, LOG_LEVEL
• DATABASE_URL
• AUTO_CREATE_DB
• MAX_MEMORY_ITEMS, MEMORY_RETENTION_DAYS

Advanced stack settings live under NAMO_* variables (see .env.example).

Set AUTO_CREATE_DB=true only for local dev convenience; production should use Alembic migrations.

• GET /health - Health and version
• GET /healthz - Liveness probe
• GET /readyz - Readiness probe with latency metrics
• GET /metrics - Prometheus metrics or JSON summary
• GET /api/status - Service status
• POST /interact - Main interaction endpoint (rate limited)
• POST /reflect - Alias for /interact (rate limited)

Example request:

curl -X POST http://localhost:8000/interact \
  -H "Content-Type: application/json" \
  -d '{"user_id":"user_123","message":"I feel anxious about tomorrow"}'

Example response:

{
  "user_id": "user_123",
  "response": "...",
  "reflection_text": "...",
  "tone": "anxiety",
  "risk_level": "low",
  "risk_score": 0.25,
  "coherence": 0.85,
  "moral_index": 0.9,
  "ethical_score": 0.88,
  "decision_consistency": 0.82,
  "recommendations": ["..."]
}

The request body accepts message or text.

alembic revision --autogenerate -m "Describe change"
alembic upgrade head
alembic current
alembic history

Default (SQLite): sqlite:///./namonexus.db

For PostgreSQL, set DATABASE_URL to:

postgresql://namonexus:password@db:5432/namonexus

pytest src/tests/ -v
pytest src/tests/ --cov=src --cov-report=html

Live API check (Windows):

powershell -ExecutionPolicy Bypass -File test_api_live.ps1

Diagnostics:

• Windows: diagnostic.ps1
• Linux/Mac: diagnostic.sh

Build:

docker build -t namonexus:1.0.1 .

Run:

docker run -p 8000:8080 -e PORT=8080 namonexus:1.0.1

docker compose up --build

To use PostgreSQL, update DATABASE_URL in .env and run:

docker compose --profile postgres up --build

namonexus/
├── src/
│   ├── api/
│   ├── database/
│   ├── models/
│   ├── services/
│   ├── utils/
│   └── main.py
├── research/
│   └── README.md
├── app/
│   └── README.md
├── migrations/
├── frontend/
├── requirements.txt
├── alembic.ini
├── Dockerfile
├── docker-compose.yml
└── README.md

Production services live under src/services/. Legacy modules under src/*_service.py remain for backward compatibility and are not wired to the API.

Port already in use:

# Linux/Mac
lsof -i :8000
# Windows
netstat -ano | findstr :8000

Reset local SQLite database:

rm namonexus.db
alembic upgrade head

Run a single test:

pytest src/tests/test_api.py::test_health_endpoint -v

Licensed under the MIT License. See LICENSE.