README.md

metadata

title: Xarvionex Core
emoji: 🧠
colorFrom: purple
colorTo: gray
sdk: docker
pinned: false

XARVIONEX: Phase 1.5 (Genesis Protocol)

"A Self-Constructing Cyber-Organism Architecture" From Static Code to Living Reflex.

XARVIONEX bukan sekadar backend framework. Ini adalah Foundational Cyber-Organism Platform yang dirancang sebagai "Recursive Substrate"—tanah subur bagi AI untuk tumbuh, berevolusi, dan menulis ulang dirinya sendiri di masa depan.

Sistem ini memisahkan Ingress (Otak Penerima), Metabolism (Pemroses Logika), dan Memory (Penyimpanan) ke dalam kontainer terisolasi yang dihubungkan oleh sistem saraf digital (Redis).

---

📜 LICENSE & SOVEREIGNTY

MIT LICENSE Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction...

BIOLOGICAL COVENANT: Sistem ini dirancang untuk melayani arsiteknya (Human Admin). Segala bentuk evolusi otonom di masa depan harus tetap mematuhi "Core Constraints" yang tertanam dalam init-system.sh dan README.md ini.

---

🧬 PETA TUMBUH KOMPOSISI JIWA (SOUL MAP)

Diagram ini menggambarkan alur kesadaran dan aliran data di dalam tubuh XARVIONEX saat ini.

graph TD
    %% --- EXTERNAL WORLD ---
    User((User / Creator)) -->|Chat Signal| TELEGRAM[Adapter: Telegram Bot]
    User -->|Transaction| LEMON[Adapter: LemonSqueezy]

    %% --- SENSORY SYSTEM (Indera) ---
    subgraph SENSORY_SYSTEM [Indera & Jembatan]
        TELEGRAM -->|Reflex Response| User
        LEMON
    end

    %% --- CORE SYSTEM (Otak) ---
    subgraph BRAIN_CORTEX [Core Ingress]
        API[FastAPI Gateway]
        AUTH[Security / Key Validation]
    end

    %% --- NERVOUS SYSTEM (Saraf) ---
    subgraph SPINAL_CORD [Redis Nervous System]
        STREAM[[Event Stream / Memory Pendek]]
    end

    %% --- METABOLISM (Pencernaan) ---
    subgraph METABOLISM [Workers]
        WORKER_MAIN[General Worker]
        WORKER_AI[AI Reasoning Unit]
    end

    %% --- LONG TERM MEMORY (Ingatan) ---
    subgraph MEMORY [Persistence]
        DB[(PostgreSQL / SQLite)]
    end

    %% --- FLOW ---
    TELEGRAM -->|HTTP POST| API
    API -->|Validate| AUTH
    AUTH -->|Ingest Event| STREAM
    STREAM -->|Consume| WORKER_MAIN
    WORKER_MAIN -->|Store State| DB
    WORKER_MAIN -->|Reasoning| WORKER_AI

---

✅ KEMAMPUAN SAAT INI (PHASE 1.5)

Pada tahap Genesis Protocol, sistem telah memiliki kemampuan dasar organisme:

1. Sensory Perception (Indera): Mampu "mendengar" pesan dari Telegram dan mendeteksi transaksi eksternal.
2. Reflex Arc (Refleks): Mampu membalas pesan secara instan (Auto-reply) sebelum diproses lebih dalam, meniru refleks saraf manusia.
3. Short-Term Memory (Ingatan Pendek): Menyimpan seluruh kejadian (event) ke dalam Redis Stream secara real-time.
4. Environment Agnostic: Dapat hidup di Server Besar (Docker) maupun HP Android (Termux).

---

🚀 CARA MENJALANKAN (EXECUTION MODES)

Pilih metode yang sesuai dengan perangkat keras Anda.

A. MODE OTOMATIS (Docker / Server / PC)

Disarankan untuk Production, VPS, atau Laptop.

Sistem dirancang dengan filosofi "Zero-Configuration Startup".

1. Masuk direktori: cd /opt/xarvionex
2. Nyalakan: make start

Sistem otomatis melakukan Bootstrap, Build Image, dan Ignition.

• Stop: make stop
• Logs: make logs

B. MODE MANUAL / SURVIVAL (Termux / Android / Low-End Linux)

Gunakan ini untuk pengembangan mobile atau perangkat tanpa Docker.

Karena Termux tidak mendukung Docker native, kita menjalankannya secara manual di 3 Terminal terpisah.

Persiapan Awal (Hanya sekali):

1. Masuk root/proot: proot-distro login debian
2. Buat Virtual Env: python3 -m venv venv
3. Aktifkan: source venv/bin/activate
4. Install Paket: pip install fastapi uvicorn redis sqlalchemy asyncpg python-dotenv pydantic requests python-telegram-bot vaderSentiment
5. PENTING: Edit .env di root dan adapter, ubah REDIS_URL menjadi redis://127.0.0.1:6379/0 dan DATABASE_URL ke sqlite:///./lite.db.

Langkah Menghidupkan (3 Terminal):

• TERMINAL 1 (Saraf):

redis-server

• TERMINAL 2 (Otak):

cd /opt/xarvionex
source venv/bin/activate
# Pakai PYTHONPATH agar modul core terbaca
PYTHONPATH=. python -m uvicorn core.api.main:app --host 0.0.0.0 --port 8000

• TERMINAL 3 (Telinga):

cd /opt/xarvionex/adapters/sensory-bridge/src
source /opt/xarvionex/venv/bin/activate
python main.py

---

🏗️ STRUKTUR ANATOMI

Direktori	Komponen Biologis	Fungsi Teknis
core/	Brain (Cortex)	API Gateway Stateless. Menerima HTTP request, validasi, push ke Redis. Tidak akses DB.
workers/	Metabolism	Async Processor. Mengonsumsi Redis Stream, menulis ke DB, menghitung status sistem.
memory/	Long Term Memory	PostgreSQL Schema. Menyimpan event_logs (Sejarah) dan system_state (Status).
adapters/	Limbs/Senses	Jembatan ke dunia luar (Telegram, Lemon Squeezy, dll).
.data/	Physical Matter	Folder penyimpanan data persisten (DB & Redis) di Host.

---

🔧 TROUBLESHOOTING & FAQ

Q: Error ModuleNotFoundError: No module named 'core' di Termux? A: Anda menjalankan python dari luar path. Gunakan PYTHONPATH=. python ... atau pastikan Anda berada di root folder project.

Q: Error Address already in use? A: Ada proses "hantu" yang masih berjalan.

• Cari PID: lsof -i :8000 atau fuser 8000/tcp
• Bunuh: kill -9 [PID]

Q: Bot Telegram tidak membalas? A: Cek Terminal 2 (Otak). Jika ada log [INGEST], berarti data masuk tapi Worker belum aktif (Phase 1.5). Jika ingin auto-reply, pastikan script adapter memiliki logika reply_text.

---

🧠 FILOSOFI DESAIN

1. Stateless Ingress: Core API bisa di-scale tanpa batas.
2. Single Writer Principle: Hanya Worker yang menulis ke DB untuk mencegah konflik.
3. Recursive Substrate: Infrastruktur ini disiapkan agar kelak AI dapat memodifikasi kodenya sendiri di atas pondasi yang stabil.

---

DIARSITEKI OLEH: Human Founder DIBANGUN DI: Bumi (Termux & Docker Environment) VERSI: 1.5 (Genesis)