Skip to content

QUICKSTART.md

Latest commit

 

History

History
198 lines (156 loc) · 4.8 KB

QUICKSTART.md

File metadata and controls

198 lines (156 loc) · 4.8 KB

🚀 KnowledgeOps AI - Quick Start Guide

What We Built

A complete end-to-end document intelligence platform with:

✅ FastAPI Application with structured logging and Prometheus metrics
✅ Pydantic v2 Models for request/response validation
✅ Async SQLAlchemy database integration with PostgreSQL
✅ Health Check & Monitoring endpoints
✅ Docker & Docker Compose setup
✅ Environment-based Configuration
✅ Global Exception Handling and CORS middleware

🎯 Core Features

API Endpoints

  • GET /health - Health check with version info
  • GET /metrics - Prometheus metrics for monitoring
  • POST /ingest - Document ingestion (async job creation)
  • POST /query - RAG-based document querying
  • GET /docs - Interactive API documentation

Architecture Components

  • FastAPI - Modern, fast web framework
  • PostgreSQL + pgvector - Vector database for embeddings
  • Redis - Message queue and caching
  • Celery - Async task processing
  • Prometheus + Grafana - Monitoring and visualization

🚀 Get Started in 3 Steps

1. Quick Test (No Dependencies)

python test_setup.py

2. Run with Docker (Recommended)

# Start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f app

3. Run Locally

# Install dependencies
pip install -r requirements.txt

# Set up environment
cp env.example .env

# Start the application
python run.py

📊 Test the API

Health Check

curl http://localhost:8000/health

View Metrics

curl http://localhost:8000/metrics

Ingest a Document

curl -X POST http://localhost:8000/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/sample.pdf",
    "metadata": {"title": "Sample Doc"},
    "chunk_size": 800
  }'

Query Documents

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the main topic?",
    "top_k": 5
  }'

Run Full Demo

python demo.py

🔧 Configuration

Key environment variables in .env:

Variable Purpose Default
DATABASE_URL PostgreSQL connection postgresql+asyncpg://user:password@localhost/knowledgeops
REDIS_URL Redis connection redis://localhost:6379/0
OPENAI_API_KEY LLM API key None
DEBUG Debug mode false
LOG_LEVEL Logging level INFO

📈 Monitoring

Prometheus Metrics

  • HTTP Requests: Count and duration by endpoint
  • Business Metrics: Ingestion jobs, query requests
  • System Metrics: Database connections, document counts

Grafana Dashboard

  • Access at http://localhost:3000 (admin/admin)
  • Pre-configured dashboards for application metrics

Health Checks

  • Application health: GET /health
  • Database connectivity
  • External service status

🏗️ Next Steps

Phase 1: Core RAG Implementation

  • Document text extraction (PDF, DOC, HTML)
  • Text chunking and embedding generation
  • Vector database integration
  • LLM integration for answer generation

Phase 2: Advanced Features

  • Authentication and authorization
  • Multi-tenant support
  • Admin UI
  • Advanced query filters

Phase 3: Production Ready

  • Performance optimization
  • Security hardening
  • Backup and recovery
  • CI/CD pipeline

🛠️ Development

Project Structure

knowledgeops-ai/
├── app/                    # Main application
│   ├── main.py            # FastAPI app
│   ├── config.py          # Configuration
│   ├── database.py        # Database setup
│   ├── models.py          # Pydantic models
│   ├── logging.py         # Structured logging
│   └── metrics.py         # Prometheus metrics
├── docker-compose.yml     # Multi-service setup
├── Dockerfile            # Application container
├── requirements.txt      # Python dependencies
├── run.py               # Startup script
├── demo.py              # API demo
└── test_setup.py        # Setup verification

Useful Commands

# Start development
python run.py

# Run tests
python test_setup.py

# Demo API
python demo.py

# Docker development
docker-compose up -d
docker-compose logs -f

# View API docs
open http://localhost:8000/docs

🎉 Success!

You now have a production-ready foundation for a document intelligence platform with:

  • ✅ Modern FastAPI architecture
  • ✅ Structured logging and monitoring
  • ✅ Docker containerization
  • ✅ Database integration
  • ✅ API documentation
  • ✅ Health checks and metrics

The platform is ready for implementing the core RAG functionality and can scale to handle real document processing workloads!