CoMaGraph is a context management system that uses graph database (Neo4j) to store conversational data and OpenAI's embeddings to enable semantic search and context retrieval. The system maintains conversation threads, analyzes message patterns, and provides insights into conversation dynamics.
-
Thread Management
- Create and manage conversation threads
- Track thread status and metadata
- Retrieve thread context
-
Message Management
- Store messages with OpenAI embeddings
- Link messages to threads
- Support for user and assistant roles
-
Semantic Search
- Find similar messages using embeddings
- Context-aware message retrieval
- Topic-based search
-
Analytics
- Thread statistics
- Conversation pattern analysis
- Topic evolution tracking
- FastAPI: Modern, fast web framework for building APIs
- Neo4j: Graph database for storing conversational data
- OpenAI: NLP capabilities and embeddings
- Python 3.11+: Core programming language
- Docker: Container support for Neo4j
- Python 3.11 or higher
- Docker and Docker Compose
- OpenAI API key
- Git
- Clone the repository:
git clone https://github.com/bhaskoro-muthohar/comagraph.git
cd comagraph- Set up the environment:
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt- Configure environment variables:
cp .env.example .env
# Edit .env with your OpenAI API key and other settings- Start Neo4j:
docker-compose up -d- Start the API server:
uvicorn src.main:app --reload- Access the API:
- API Documentation: http://localhost:8000/docs
- Neo4j Browser: http://localhost:7474
curl -X POST http://localhost:8000/api/v1/threads/ \
-H "Content-Type: application/json" \
-d '{"metadata": {"source": "example"}}'curl -X POST http://localhost:8000/api/v1/messages/ \
-H "Content-Type: application/json" \
-d '{
"content": "Hello, world!",
"role": "user",
"thread_id": "",
"metadata": {}
}'curl http://localhost:8000/api/v1/analysis/thread//statssrc/
├── api/ # API routes and dependencies
├── core/ # Core configurations and constants
├── db/ # Database operations
├── models/ # Pydantic models
├── services/ # Business logic
└── main.py # Application entry point
POST /api/v1/messages/- Create messageGET /api/v1/messages/{id}- Get messageGET /api/v1/messages/similar/- Find similar messages
POST /api/v1/threads/- Create threadGET /api/v1/threads/{id}- Get threadGET /api/v1/threads/{id}/context- Get thread context
GET /api/v1/analysis/thread/{id}/stats- Get thread statisticsGET /api/v1/analysis/thread/{id}/patterns- Analyze conversation patternsGET /api/v1/analysis/thread/{id}/topics- Track topic evolution
The project includes Docker support for both the API and Neo4j. To run the entire stack in containers:
# Build and start all services
docker-compose up -d --build
# View logs
docker-compose logs -f
# Stop services
docker-compose downRequired environment variables in .env:
# API Settings
API_V1_STR="/api/v1"
PROJECT_NAME="CoMaGraph"
# Neo4j Settings
NEO4J_URI="bolt://localhost:7687"
NEO4J_USER="neo4j"
NEO4J_PASSWORD="your_password"
# OpenAI Settings
OPENAI_API_KEY="your-openai-api-key"
# Performance Settings
SIMILARITY_THRESHOLD=0.8
CONTEXT_WINDOW_SIZE=10
To set up the development environment:
- Install dependencies:
pip install -r requirements.txt- Run tests:
pytest tests/- Start the development server:
uvicorn src.main:app --reload- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.