Variks

Variks is an entity-centric emotional AI runtime where continuity of local data is continuity of self.

This project separates decision authority from model reasoning:

• Local Variks core owns emotional state, memory biasing, and final response selection.
• External LLMs (Gemini) are advisory coprocessors that provide candidate reasoning only.

Current Capabilities

• Birth and identity initialization with unique per-entity coefficients.
• Local SQLite emotional state engine with baseline + exponential decay.
• Deterministic Ether appraisal (security, house, flow).
• Local archive memory store with Chroma vector retrieval.
• Mood-congruent memory reranking by current valence.
• LLM reasoning provider with local fallback and policy-gated final selection.
• Standalone template-derived web UI with birth/interaction/state panels.

Quick Start

1. Install dependencies:
   • python -m pip install -r backend/requirements.txt
2. Configure environment:
   • Copy .env.example to .env
   • Set GEMINI_API_KEY
   • Set GEMINI_MODEL (recommended: gemini-flash-latest)
3. Run tests:
   • python -m pytest from backend
4. Run web UI:
   • cd web-ui
   • npm install
   • npm run dev

API Overview

• POST /entity/birth: creates a new Variks entity profile.
• POST /archive/nodes: ingests an archive memory node.
• POST /interactions/process: runs the emotional + memory + reasoning pipeline.
• GET /health: service health and entity initialization status.

Web UI

• Location: web-ui/
• Source: adapted from the Aether template structure with non-essential modules removed.
• Explicitly disabled for now:
  • authentication module
  • database module from template
  • tRPC and server package coupling
• Current purpose:
  • create entity (birth sliders)
  • send interaction prompts
  • display emotional state and reasoning source

Documentation

• docs/README.md
• docs/entity_birth_contract.md
• docs/local_data_architecture.md
• docs/roadmap.md