velt

---

Core Library: Lucia

lucia is a Python library packaging the core AI functionalities originally developed for the velt service. It provides modular components for:

• Personal Information & Keyword Extraction: Using LLMs (like OpenAI models) to identify key information and topics from text.
• Embeddings Generation: Creating vector representations of text using OpenAI's embedding models, with optional Redis caching.
• Data Storage: Persisting extracted information into graph databases (Neo4j) and vector embeddings into vector stores (Milvus).
• Pipelines: Pre-built workflows (KnowledgePipeline, SearchPipeline) for common tasks like processing new knowledge or searching existing information.
• Customization: Pluggable architecture allowing replacement of extractors, embedding clients, and storage backends.

For more details on lucia, see its dedicated README.

delos-lucia는 velt서비스의 기능을 재구성해 구현한 파이썬 패키지입니다.

---

velt is a FastAPI-based backend application that integrates a ReAct language agent (via LangGraph), a Neo4j knowledge graph, a Milvus vector store, PostgreSQL, and Redis to deliver a personalized, retrieval-augmented conversational chatbot experience.

---

Demo Service: https://delosplatform.com

Contact: sungmin.na330@gmail.com

Directory: https://my.surfit.io/w/528136765

---

🚀 Project Overview

!image

• LLM과 대화를 통해 개인화된 정보를 수집한다. 추후에 수집된 정보를 기반으로 개인화된 답변을 제공한다.
• 개인화된(취향, 상태, 등..)에 대한 정보는 그래프 DB에 저장한다. 유저 질의와 유사한 키워드를 찾기 위해 벡터 DB도 활용한다.
• 그래프 형태 및 구성
  • 유저) 나는 햄버거를 좋아해
  • LLM) 그렇구나!!
  • 유저 질의에서 LLM을 활용해 관계를 추출한다
  • Knowledge Graph: (유저) --좋아한다-- (햄버거) --포함한다-- (음식)
  • 위와 같은 형태로 저장된다. 상위의 개념도 같이 그래프에 넣어 현실 대화를 대응할 수 있다. ex)나는 어떤 음식을 좋아해? or 오늘 저녁에 먹을 음식 추천해줘
• 그래프 탐색
  • Q) 나 미술 좋아하니?
  • LLM) 너가 미술을 좋아한다고 말한적이 있네...
  • 유저 질의에서 LLM을 활용해 키워드를 추출한다
  • 그래프에서 1홉 및 2홉의 노드(객체)와 직접적인 엣지(관계)를 모두 검색한다.
  • 추가로 그래프와 연결된 하위 개념도 검색한다. ex) 키워드가 음식인 경우 햄버거와의 관계도 추가한다
  • 관계를 LLM의 프롬프트에 추가해 증강된 답변을 유저에게 제공한다
• 검증 결과
  • 노드와 엣지 각각 적절한 탐색을 수행하고 관련된 정보를 기반으로 LLM이 답변을 해 준다
  • DB접근에 병목이 있는 것으로 추정(최적화 필요)
  • 적절한 데이터로 LLM이 증강되고 있지만, Relevent한 답변을 제공하고 있는지는 추가 파악 필요(성능 향상 필요)
  • 동적으로 Graph를 구축하고, 이를 기반으로 초개인화된 LLM을 구축할 수 있다
• 추가 사항
  • 유저와 유저간의 관계를 분석할 것이 아니라면, 단순 RDB기반으로 구축 가능하다.(성능이나 용량 면에서 추가 교차 검증 필요)
  • 실시간 대규모 환경에서의 GraphDB(Neo.4j)의 성능 검증이 필요하다
  • 프롬프트의 개선이 필요하다. 엣지 케이스에 대한 처리를 해 주었음에도 불구하고 Instruction을 따르지 않는 경우가 드물게 있다. (모델 성능 이슈?)
  • 현재는 DB쿼리를 하드코딩하여 사용하고 있다. Text to Cypher(SQL)을 활용해 MCP로 사용 가능할 것으로 보인다. (성능 검증 필요)
  • RAG의 한계? 컨텍스트를 증강하게 되면 오히려 컨텍스트에 치중한 답변을 제시한다. 즉, 그라운딩 없이 대화하는 것에 비해 부자연스러운 답변을 제시한다. (해결 필요)

---

• Personalized Chatbot: Leverages user profile data, preferences, and relationships stored in Neo4j to provide context-aware responses.
• Retrieval-Augmented Generation: Uses Milvus to store and search OpenAI embeddings of user data and chatbot context, enriching prompts for the REACT agent.
• Structured Personal Information: Extracts user statements, preferences, and attributes as structured JSON, then persists them into Neo4j nodes and relationships.
• Asynchronous & Scalable: Built on FastAPI with async SQLAlchemy, async Neo4j driver, and async Redis/Milvus clients for high throughput.
• Secure & Rate-Limited: JWT-based authentication, bcrypt password hashing, and per-endpoint rate limiting with slowapi.

---

📚 Features

• User Management: Signup, login, and profile endpoints with JWT authentication.
• Graph Storage: Save and update user information as nodes and relationships in Neo4j.
• Vector Embeddings: Generate OpenAI embeddings with Redis caching, store vectors in Milvus, and perform similarity search.
• Chat Sessions: Create and retrieve chat sessions and messages from PostgreSQL.
• REACT Agent: Orchestrate LangChain's REACT agent for dynamic question answering and task execution.
• Tool Integration: Example external tool servers (weather, math) to demonstrate agent tool usage.
• Rate Limiting: Control request throughput per endpoint (e.g., chat, login, register).

---

🛠️ Tech Stack

Component	Library / Tool
Framework	FastAPI, Uvicorn
HTTP & ASGI Server	Uvicorn
Knowledge Graph	Neo4j (neo4j-driver)
Vector Store	Milvus (pymilvus)
Embedding Model	OpenAI embeddings (text-embedding-3-small)
Database	PostgreSQL (asyncpg), SQLAlchemy AsyncSession
Caching	Redis (aioredis)
Authentication	JWT (python-jose), bcrypt (passlib[bcrypt])
Rate Limiting	slowapi
LLM Agent	LangChain, langgraph, langchain-openai
Logging & Tracing	Python logging, Langfuse
Packaging & Deploy	Poetry, Docker

---

📐 Architecture & Workflow

1. Application Startup (lifespan hook in main.py):
   • Create PostgreSQL tables via SQLAlchemy migrations.
   • Connect to Neo4j, verify connectivity, and create unique constraints.
   • Connect to Milvus and ensure the collection and index exist.
2. User Flow:
   • Signup: Save user to PostgreSQL and create a corresponding User node in Neo4j.
   • Login: Issue JWT access tokens upon valid credentials.
3. Chat Flow:
   • Session Management: Store chat sessions and messages in PostgreSQL.
   • Message Handling:
     • Extract personal information (key, value, relationship) from user messages.
     • Persist structured data into Neo4j as Information nodes and RELATES_TO edges.
     • Generate or retrieve embeddings for data points and store/search in Milvus.
     • Extract keywords from user input and perform vector similarity search in Milvus to retrieve relevant concepts.
     • Fetch related graph data from Neo4j (direct relations and 1-hop children) for context.
     • Combine context and call the LangChain REACT agent to generate a response.
     • Save the agent's response back to PostgreSQL.
4. Background & Tooling:
   • External Tools: weather_server.py and math_server.py simulate tool APIs for the REACT agent.
   • Rate Limiting: Enforce per-endpoint limits (e.g., chat, login) using slowapi.
   • Tracing & Logging: Log requests and LLM callbacks via Python logging and Langfuse.

---

📂 Directory Structure

react_mcp/
├── main.py
├── database.py
├── core/
│   ├── config.py
│   └── security.py
├── routers/
│   ├── auth.py
│   ├── users.py
│   ├── general.py
│   └── ask.py
├── services/
│   ├── neo4j_service.py
│   ├── milvus_service.py
│   └── llm_service.py
├── crud/
│   ├── user.py
│   └── chat.py
├── models/
├── prompts.py
├── client.py
├── weather_server.py
├── math_server.py
├── pyproject.toml
├── poetry.lock
├── Dockerfile
└── README.md

Additionally, the velt/ directory at the repository root contains the SvelteKit frontend application.

---

⚙️ Installation

1. Prerequisites:

   • Python 3.13+
   • Poetry
   • Docker (optional)
   • Node.js & npm (for frontend)

2. Clone & Setup Backend:

   git clone <repository_url>
   cd <repository_root>/react_mcp
   poetry install
   

3. Configure Environment Variables: Create a .env file in react_mcp/ with the following keys:

   SECRET_KEY=
   DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/dbname
   NEO4J_URI=bolt://localhost:7687
   NEO4J_USER=neo4j
   NEO4J_PASSWORD=password
   MILVUS_HOST=localhost
   MILVUS_PORT=19530
   REDIS_URL=redis://localhost:6379
   LANGFUSE_SECRET_KEY=
   LANGFUSE_PUBLIC_KEY=
   LANGFUSE_HOST=http://localhost:3000
   RATE_LIMIT_CHAT=30/minute
   RATE_LIMIT_LOGIN=10/minute
   RATE_LIMIT_REGISTER=5/hour
   CORS_ALLOW_ORIGINS=*
   

4. Run the Backend:

   poetry run uvicorn main:app --reload --host 0.0.0.0 --port 8000
   

5. Run the Frontend (Optional):

   cd ../velt
   npm install
   npm run dev
   

---

📡 API Endpoints

Authentication

• POST /api/v1/auth/token — Obtain JWT access token

Users

• POST /api/v1/users/ — Register a new user
• GET /api/v1/users/me — Get profile of current user
• GET /api/v1/users/{user_id} — Get user by ID
• GET /api/v1/users/ — List all users (requires auth)

Chat

• POST /api/v1/chat/ — Send a chat message → Agent response
• GET /api/v1/chat/sessions — List chat sessions
• GET /api/v1/chat/{session_id}/messages — Get messages in a session
• DELETE /api/v1/chat/{session_id} — Delete session and messages

General

• GET / — Health check / Hello world
• GET /items/{item_id} — Sample test endpoint

---

🏗️ Frontend (velt)

The velt folder contains a SvelteKit application that consumes this backend API.

cd velt
npm install
npm run dev

Build & preview:

npm run build
npm run preview

---

✨ Contributing

Contributions are welcome! Please open issues or pull requests.

---

📄 License

This project is licensed under the MIT License.