Humindx Docs

Appearance

Geliştirme Ortamı Kurulum Rehberi (Environment Setup) ​

Bu rehber, Humindx projesine yeni katılan bir mühendisin lokal bilgisayarında (localhost) "Hot Path" (Etkileşim) ve "Cold Path" (Psikometrik) servislerini ayağa kaldırması için gereken adımları içerir.

1. Ön Koşullar (Prerequisites) ​

Bilgisayarınızda aşağıdaki araçların kurulu olması gerekmektedir:

  • Docker & Docker Compose: Veritabanı ve kuyruk servisleri için.
  • Node.js (v20+): API Gateway ve Hot Path (NestJS) için.
  • Python (3.11+): Psikometrik Motor (FastAPI) için.
  • (Opsiyonel) Flutter / React Native: Mobil B2C istemcisini lokalde çalıştırmak istiyorsanız.

2. Altyapı Servislerini Ayağa Kaldırma ​

Humindx lokal geliştirme ortamı, karmaşık veritabanı kurulumlarını önlemek için tamamen Dockerize edilmiştir.

  1. Projeyi klonlayın ve kök dizine gidin:

    bash
    git clone https://github.com/humindx/core.git
cd core

  2. Çevresel değişkenleri (ENV) ayarlayın:

    bash
    cp .env.example .env
# .env dosyasını açarak OPENAI_API_KEY veya ANTHROPIC_API_KEY değerlerinizi girin.

  3. Docker servislerini başlatın:

    bash
    docker-compose up -d

    Bu komut şunları ayağa kaldıracaktır:

    • postgres-db: İçerisinde pgvector eklentisi aktif edilmiş PostgreSQL 16.
    • redis-broker: Event Bus ve asenkron görev kuyruğu (Celery) için.

3. Servisleri Çalıştırma ​

Sistem asenkron iki parçadan oluştuğu için iki ayrı terminal kullanmanız gerekmektedir.

Terminal 1: Hot Path (API Gateway & Chat Engine) ​

Bu servis WebSocket bağlantılarını yönetir ve B2C/B2B istemcilerine API sunar.

bash
cd services/api-gateway
npm install
npm run start:dev

Servis http://localhost:3000 portunda çalışmaya başlayacaktır.

Terminal 2: Cold Path (Psikometrik Motor) ​

Bu servis, Redis'e düşen sohbet olaylarını alır, LLM üzerinden analiz eder ve genom skorlarını günceller. Şu an sadece /api/v1/health ayakta; Celery worker ve scoring/sanitization endpoint'leri sonraki commit'lerde eklenecek.

bash
cd services/psychometric-engine
python -m venv venv
source venv/bin/activate  # Windows için: venv\Scripts\activate
pip install -e ".[dev]"

# FastAPI sunucusunu başlatın
uvicorn psychometric_engine.main:app --reload --port 8000

Celery worker (celery -A psychometric_engine.worker worker --loglevel=info) eventing katmanı eklenince aktif olacak — docs/architecture/data-flow-diagrams.md.

4. Test ve İlk Etkileşim ​

Kurulumun başarılı olduğunu doğrulamak için API üzerinden test kullanıcısı oluşturup ilk "Sisli Sohbet" olayını tetikleyebilirsiniz:

bash
curl -X POST http://localhost:3000/api/v1/b2c/chat/init \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test-user-1", "agent_type": "SHADOW"}'

Eğer Celery terminalinde [Task SCENARIO_COMPLETED] Processing trait shifts... logunu görüyorsanız, sisteminiz uçtan uca çalışıyor demektir. Hoş geldiniz!

Mimari kararların gerekçeleri için bkz. architecture-decisions/

Simetri tarafından inşa ediliyor.