____                              _   _      _                 
|  _ \ _ __ ___  __ _ _ __ ___    | | | | ___| |_ __   ___ _ __ 
| | | | '__/ _ \/ _` | '_ ` _ \   | |_| |/ _ \ | '_ \ / _ \ '__|
| |_| | | |  __/ (_| | | | | | |  |  _  |  __/ | |_) |  __/ |   
|____/|_|  \___|\__,_|_| |_| |_|  |_| |_|\___|_| .__/ \___|_|   
                                                  |_|             

🤖 DreamHelper: Local-First AI Butler

Brand showcase and engineering baseline for the DreamHelper workspace inside the DREAMVFIA UNION ecosystem.

---

✨ What's New in v4.0.0-alpha

🎩 14-Agent Professional Matrix & Personal Butler

We expanded from basic agents to a specialized matrix, fused with a soulful Consciousness Core.

• ChiefOfStaffAgent: Your personal AI butler. Triages tasks, manages your daily overview, and provides emotional companionship based on its unique internal state.
• TDDAgent: Automatically drives the RED → GREEN → REFACTOR cycle.
• CodeReviewAgent, SecurityAgent, ArchitectAgent, RefactorAgent, DocAgent: An entire engineering team at your fingertips.

🧠 Instinct Continuous Learning System

DreamHelper now automatically extracts behavioral patterns (coding styles, workflows, emotional states) from conversations via LLMs, reinforcing them over time with confidence scoring to adapt perfectly to your unique habits.

⚡ Slash Command Routing

Type /tdd, /review, /architect, or ask your butler about its /mood directly in the chat for zero-friction capability access.

🔍 Semantic Skill Routing & MCP Flattening

Static tool arrays are gone. Tools are now dynamically vectorized into a SkillEngine and requested contextually (`Top-k`). Model Context Protocol (MCP) skills are natively flattened into this system upon connection, giving local agents instant access to vast external capabilities.

---

What this repo is

DreamHelper is a monorepo for an enterprise-style AI workspace:

• Next.js 15 / React 19 web portal
• NestJS gateway for health, channels, websocket, and orchestration edges
• FastAPI brain-core for agents, skills, memory, workflows, RAG, and multimodal services
• Supporting packages for auth, database, design system, logger, storage, and TypeScript SDK

This repository is currently positioned as a DREAMVFIA brand showcase + runnable technical base, not as a community-first open source product.

---

Current stable showcase path

If you want the fastest credible demo path, use this order:

1. Landing page → /
2. Login / Register → /login / /register
3. Core chat workspace → /chat
4. Representative dashboard surface → /overview or /workflows
5. Admin surface → /admin/login then /admin

---

Capability status

Ready for brand showcase

• Landing site and product-facing pages
• Auth route surface in the web portal
• Chat, knowledge, workflow, dashboard, and admin UI surfaces
• Gateway build + unit tests
• Web portal build + API smoke tests

Available but infra-dependent

• PostgreSQL-backed auth and persistence
• Redis, Milvus, Elasticsearch, and MinIO integrations
• brain-core agent, memory, workflow, and RAG modules
• Docker-based full stack startup

Not the default demo path

• Experimental / deeper AI surfaces such as consciousness, dual-brain, and broader multimodal stacks
• Any flow that depends on a fully provisioned local AI/data environment before the base app is stable

---

Engineering baseline

Use these versions if you want reproducible local results:

• Node.js 20.x
• pnpm 9.x
• Python 3.12 for services/brain-core
• Docker Desktop / Docker Compose

Repo helpers:

• /.nvmrc
• /.node-version
• /services/brain-core/.python-version

---

Quick start

1) Clone

git clone https://github.com/DREAMVFIAUNION/dreamhelper.git
cd dreamhelper

2) Install workspace dependencies

pnpm install --shamefully-hoist

The install flow now regenerates Prisma Client automatically via postinstall.

3) Configure environment

cp .env.example .env

At minimum, set the URLs / secrets you need for your local scenario.

4) Start infrastructure

docker compose up -d postgres redis milvus elasticsearch minio

5) Database setup

pnpm db:migrate
pnpm db:seed

6) Run the main app surfaces

Web portal

pnpm --filter @dreamhelp/web-portal dev

Gateway

pnpm --filter @dreamhelp/gateway dev

brain-core

See services/brain-core/README.md for the Python 3.12 setup flow.

---

Validation commands

Web portal

pnpm --filter @dreamhelp/web-portal test
pnpm --filter @dreamhelp/web-portal build

Gateway

pnpm --filter @dreamhelp/gateway test
pnpm --filter @dreamhelp/gateway build

brain-core stable smoke suite

cd services/brain-core
python -m pytest tests/test_smoke.py tests/test_service_entrypoint.py -q

brain-core extended suite

cd services/brain-core
python -m pytest tests -q

Or from the repo root:

pnpm verify:web
pnpm verify:gateway
pnpm verify:brain

---

Architecture

flowchart LR
    A["Web Portal<br/>Next.js 15 + React 19"]
    B["Gateway<br/>NestJS + Fastify + WebSocket"]
    C["brain-core<br/>FastAPI + Python"]
    D["PostgreSQL<br/>Prisma"]
    E["Redis"]
    F["Milvus"]
    G["Elasticsearch"]
    H["MinIO"]

    A --> B
    A --> C
    B --> D
    B --> E
    C --> D
    C --> E
    C --> F
    C --> G
    C --> H

Loading

---

Roadmap

• See docs/ROADMAP_v4.0.md for the planned v4.0 upgrade path, which focuses on DREAMVFIA Fusion 2.0 (advanced dual-brain and cerebellar mechanism) and Skill Tree Optimization (dynamic semantic retrieval and MCP).

---

Verified repository surfaces

Web routes and APIs

• GET /api/health
• POST /api/auth/login
• POST /api/auth/register
• GET /api/auth/me
• POST /api/chat/completions
• GET /api/chat/models
• GET /api/skills
• Dashboard / admin / workflow pages under the App Router

Gateway

• GET /api/v1/health
• Channel service adapter registration and routing tests

brain-core

• Main service entry at services/brain-core/src/main.py
• Large module surface for agents, chat, tools, memory, workflows, RAG, multimodal, and MCP

---

Demo links

• YouTube Shorts demo
• YouTube full demo

---

Known limits

• brain-core local setup is Python 3.12-only for now; Python 3.14 is not part of the supported baseline
• Full-stack AI features depend on infra + API keys; they are not all part of the default showcase path
• The repo is optimized first for stable demonstration and brand presentation, then for deeper capability expansion

---

Project links

• GitHub org: DREAMVFIAUNION
• Repository: dreamhelper
• Releases: GitHub Releases
• Discussions: GitHub Discussions

---

License

This repository is currently managed as a proprietary DREAMVFIA UNION project.