A production-grade MVP for an AI-powered consulting system that ingests enterprise documents, indexes them for RAG (Retrieval-Augmented Generation), and runs coordinated agents to produce comprehensive consulting reports with source citations.
- Document Processing: Upload and parse PDF/DOCX files with automatic chunking and embedding
- Multi-Agent System: Coordinated Strategy and Research agents using LangGraph
- RAG-Powered Analysis: Semantic search across document chunks using pgvector
- Report Generation: Automated consulting reports in Markdown and PDF formats
- Blackboard Pattern: Shared knowledge base for agent coordination
- Source Citations: Automatic citation generation with document references
- Modern UI: Clean, responsive interface built with Next.js and shadcn/ui
- Frontend: Next.js 15 (App Router) + TypeScript + Tailwind CSS + shadcn/ui
- Backend: Next.js Route Handlers + Node.js 20
- Agents/Orchestration: LangGraph with blackboard pattern
- LLM Provider: OpenAI SDK (with provider abstraction)
- Database: PostgreSQL + Prisma + pgvector for embeddings
- Document Parsing: pdf-parse, docx libraries
- PDF Generation: md-to-pdf for server-side rendering
- Development: Docker + docker-compose, ESLint, Prettier, Vitest
- Node.js 20+
- pnpm (recommended) or npm
- Docker and Docker Compose
- OpenAI API key
git clone <repository-url>
cd renben-maci
cp env.example .envEdit .env with your configuration:
DATABASE_URL="postgres://postgres:postgres@localhost:5432/maci"
OPENAI_API_KEY="your_openai_api_key_here"
NEXTAUTH_SECRET="your_nextauth_secret_here"
NEXTAUTH_URL="http://localhost:3000"
NODE_ENV="development"docker-compose up -dThis starts:
- PostgreSQL 16 with pgvector extension
- pgAdmin on http://localhost:8080 (admin@maci.local / admin)
pnpm installpnpm prisma generate
pnpm prisma db push
pnpm db:seedpnpm devVisit http://localhost:3000 to access the application.
Run the end-to-end demo:
pnpm demoThis will:
- Use the seeded sample project
- Start an orchestrator run with a sample brief
- Generate a consulting report with citations
- Show progress in the web interface
/app
/api # Next.js API routes
/projects # Project management endpoints
/projects/[id] # Project-specific operations
/(dashboard) # Dashboard pages
/page.tsx # Projects list
/projects/[id] # Project workspace
/components # React components
/ui # shadcn/ui components
FileUploader.tsx # Document upload component
ProjectCard.tsx # Project display component
RunConsole.tsx # Agent run interface
ActivityFeed.tsx # Blackboard activity display
/lib # Core libraries
/agents # Strategy and Research agents
/graph # LangGraph orchestrator
db.ts # Database connection
embeddings.ts # OpenAI embeddings service
rag.ts # RAG search functionality
chunker.ts # Text chunking utilities
pdf.ts # PDF parsing
docx.ts # DOCX parsing
pdf-renderer.ts # Markdown to PDF conversion
blackboard.ts # Blackboard pattern implementation
citations.ts # Citation management
/prisma # Database schema and migrations
/scripts # Utility scripts
seed.ts # Database seeding
demo.ts # Demo scenario
init-pgvector.sql # PostgreSQL extension setup
GET /api/projects- List all projectsPOST /api/projects- Create new projectGET /api/projects/[id]- Get project detailsPUT /api/projects/[id]- Update projectDELETE /api/projects/[id]- Delete project
POST /api/projects/[id]/upload- Upload documents (multipart)
GET /api/projects/[id]/runs- List project runsPOST /api/projects/[id]/runs- Start new runGET /api/projects/[id]/runs/[runId]- Get run details
GET /api/projects/[id]/runs/[runId]/report.md- Download Markdown reportGET /api/projects/[id]/runs/[runId]/report.pdf- Download PDF report
- Performs RAG searches across document chunks
- Generates research summaries with confidence scores
- Creates structured findings for the blackboard
- Drafts report sections based on research findings
- Generates strategic hypotheses
- Assembles final reports with citations
- Coordinates agent activities using blackboard pattern
- Manages run lifecycle and error handling
- Generates progress updates and logging
User- System usersProject- Consulting projectsDocument- Uploaded files with processing statusDocumentChunk- Text chunks with embeddings (pgvector)Run- Agent execution runsBlackboardNote- Agent communication and findingsCitation- Source references in reports
Built with shadcn/ui for consistency and accessibility:
- Responsive design with Tailwind CSS
- Dark/light mode support
- Real-time progress indicators
- Drag-and-drop file uploads
- Interactive activity feeds
pnpm dev # Start development server
pnpm build # Build for production
pnpm start # Start production server
pnpm lint # Run ESLint
pnpm format # Format with Prettier
pnpm test # Run tests with Vitest
pnpm db:push # Push schema to database
pnpm db:studio # Open Prisma Studio
pnpm db:seed # Seed database with sample data
pnpm demo # Run end-to-end demo- ESLint for linting
- Prettier for formatting
- TypeScript for type safety
- Vitest for testing
docker build -t renben-maci .
docker run -p 3000:3000 renben-maciDATABASE_URL="postgres://user:pass@host:5432/maci"
OPENAI_API_KEY="your_production_key"
NEXTAUTH_SECRET="secure_random_string"
NEXTAUTH_URL="https://your-domain.com"
NODE_ENV="production"- Authentication: NextAuth with multiple providers
- File Storage: Azure Blob Storage integration
- Real-time Updates: WebSocket/SSE for live progress
- Advanced Parsing: Better DOCX support, image extraction
- Multi-language: Support for non-English documents
- Collaboration: Multi-user project sharing
- Analytics: Usage tracking and performance metrics
- Azure Container Apps: Serverless deployment
- Azure Database: Managed PostgreSQL with pgvector
- Azure Storage: Blob storage for documents
- Azure Monitor: Application insights and logging
-
Database Connection Failed
docker-compose down docker-compose up -d pnpm prisma db push
-
OpenAI API Errors
- Verify API key in
.env - Check API quota and billing
- Verify API key in
-
PDF Generation Fails
- Ensure
md-to-pdfdependencies are installed - Check file permissions in
/datadirectory
- Ensure
-
Embeddings Not Working
- Verify pgvector extension is installed
- Check OpenAI API key and quota
Check application logs:
pnpm dev # Shows logs in terminalDatabase logs:
docker-compose logs postgresThis project is licensed under the MIT License - see the LICENSE file for details.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
For questions or issues:
- Create an issue in the repository
- Check the troubleshooting section
- Review the API documentation
Renben MACs - Empowering consulting with AI-driven intelligence.