Merge pull request #10 from Papr-ai/release/v0.3.0-oss-launch

feat: v0.3.0 - Temporal Document Ingestion, Memory Policies & OMO Safety, Messages API

Author: shawkatkabbara

.env.example

@@ -1,9 +1,35 @@
 # ============================================
 # Papr Memory - Open Source Configuration
 # ============================================
-# Copy this file to .env and fill in your values
-# Required variables are marked with [REQUIRED]
-# Optional variables have sensible defaults
+#
+# SETUP INSTRUCTIONS:
+#
+#   1. Copy this file:
+#        cp .env.example .env.opensource
+#
+#   2. Edit .env.opensource with your REAL API keys:
+#        - OPENAI_API_KEY       (required for LLM operations)
+#        - GROQ_API_KEY         (optional, for fast LLM)
+#        - DEEPINFRA_TOKEN      (only if USE_LOCAL_EMBEDDINGS=false)
+#
+#   3. Start services:
+#        docker compose up -d
+#
+#   4. On first startup, the system auto-creates:
+#        - Parse schemas
+#        - Default user + workspace
+#        - API key  →  saved to .env.generated
+#        - Test credentials (TEST_* vars)  →  appended to .env.opensource
+#
+#   5. Your API key is in .env.generated (or docker logs papr-memory)
+#
+# FILES:
+#   .env.example     →  Template (committed to git). DO NOT put secrets here.
+#   .env.opensource   →  Your real config (gitignored). Used by docker-compose.
+#   .env             →  Alternative config name (gitignored). Also works.
+#   .env.generated   →  Auto-created on first run with your API key (gitignored).
+#
+# ============================================
 
 # ============================================
 # Edition Configuration
@@ -15,10 +41,9 @@ PAPR_EDITION=opensource
 # ============================================
 # API Key (For Testing)
 # ============================================
-# Generate your API key after starting services:
+# Auto-generated on first startup. Check .env.generated after docker compose up.
+# Or generate manually:
 #   python scripts/generate_api_key.py --email your@email.com --name "My Project"
-#
-# For quick testing, you can use this default key (change in production!)
 PAPR_API_KEY=pmem_oss_default_testing_key_CHANGE_ME
 
 # ============================================
@@ -42,9 +67,9 @@ OPENAI_API_KEY=sk-your-openai-api-key
 OPENAI_ORGANIZATION=org-your-org-id
 
 # LLM Model Configuration
-LLM_MODEL=gpt-4o-mini
-LLM_MODEL_MINI=gpt-4o-mini
-LLM_MODEL_NANO=gpt-4o-mini
+LLM_MODEL=gpt-5-nano
+LLM_MODEL_MINI=gpt-5-mini
+LLM_MODEL_NANO=gpt-5-nano
 
 # ============================================
 # MongoDB Configuration [REQUIRED]
@@ -85,17 +110,21 @@ QDRANT_URL=http://qdrant:6333
 # Leave empty for self-hosted Qdrant without auth
 QDRANT_API_KEY=
 
-# Qdrant collection names
-QDRANT_COLLECTION_QWEN0pt6B4B=Qwen0pt6B
+# Qdrant collection names (auto-selected based on embedding dimensions)
+# - Qwen0pt6B: 1024 dimensions (used with Qwen3-Embedding-0.6B)
+# - Qwen4B: 2560 dimensions (used with Qwen3-Embedding-4B)
+# The system automatically uses the correct collection based on LOCAL_EMBEDDING_DIMENSIONS
+QDRANT_COLLECTION_QWEN0pt6B=Qwen0pt6B
 QDRANT_COLLECTION_QWEN4B=Qwen4B
 
 # ============================================
 # Parse Server Configuration [REQUIRED]
 # ============================================
 # Parse Server is used for user management and ACL
-# For Docker: http://parse-server:1337/parse
-# For local: http://localhost:1337/parse
-PARSE_SERVER_URL=http://parse-server:1337/parse
+# For Docker: http://parse-server:1337
+# For local: http://localhost:1337
+# NOTE: Do NOT include /parse in the URL - the code appends /parse to all API paths
+PARSE_SERVER_URL=http://parse-server:1337
 
 # Parse credentials (generate random UUIDs for security in production)
 PARSE_APPLICATION_ID=papr-oss-app-id
@@ -107,6 +136,7 @@ PARSE_SERVER_APPLICATION_ID=papr-oss-app-id
 PARSE_SERVER_MASTER_KEY=papr-oss-master-key
 
 # Parse Dashboard credentials (optional, for development only)
+# Dashboard URL: http://localhost:4040
 PARSE_DASHBOARD_USER=admin
 PARSE_DASHBOARD_PASSWORD=password
 PARSE_DASHBOARD_SESSION_SECRET=your-dashboard-secret
@@ -139,12 +169,44 @@ POSTHOG_HOST=https://app.posthog.com
 AMPLITUDE_API_KEY=
 
 # ============================================
-# Embedding Configuration (Optional)
+# Embedding Configuration
 # ============================================
+# Local Embeddings (RECOMMENDED for Open Source)
+# By default, we use local Qwen3-Embedding-0.6B model for embeddings
+# This runs entirely on your device without external API calls
+# 
+# Set to "true" to use local embedding models (default for open source)
+# Set to "false" to use cloud embedding APIs (requires API tokens below)
+USE_LOCAL_EMBEDDINGS=true
+
+# Local embedding model configuration
+# ⚠️ IMPORTANT: Choose ONE of the following models:
+#
+# Option 1: Qwen3-Embedding-0.6B (RECOMMENDED for most users)
+#   - Smaller, faster model (~1.2GB download)
+#   - 1024 dimensions, 32k context
+#   - Good balance of speed and quality
+LOCAL_EMBEDDING_MODEL=Qwen/Qwen3-Embedding-0.6B
+LOCAL_EMBEDDING_DIMENSIONS=1024
+#
+# Option 2: Qwen3-Embedding-4B (for higher quality)
+#   - Larger, more accurate model (~8GB download)
+#   - 2560 dimensions, 32k context
+#   - Better embedding quality but slower
+# LOCAL_EMBEDDING_MODEL=Qwen/Qwen3-Embedding-4B
+# LOCAL_EMBEDDING_DIMENSIONS=2560
+#
+# ⚠️ NOTE: Qdrant collections are created per dimension size.
+# If you change models, you may need to:
+#   1. Delete old collection: curl -X DELETE http://localhost:6333/collections/Qwen0pt6B
+#   2. Restart services: docker compose restart
+#   3. Or use: docker compose down -v && docker compose up -d (clears all data)
+
+# Cloud Embedding APIs (Optional - only needed if USE_LOCAL_EMBEDDINGS=false)
 # Hugging Face for alternative embeddings
 HUGGING_FACE_ACCESS_TOKEN=
 
-# DeepInfra for additional embedding models
+# DeepInfra for cloud-based Qwen embeddings (faster but requires API key)
 DEEPINFRA_TOKEN=
 DEEPINFRA_API_URL=https://api.deepinfra.com/v1/openai/embeddings
 
@@ -164,7 +226,7 @@ MAX_TOTAL_BATCH_TOKENS=100000
 # Logging Configuration
 # ============================================
 LOGGING_ENV=development
-LoggingtoFile=false
+LoggingtoFile=true
 
 # ============================================
 # Docker Image Configuration
@@ -190,18 +252,77 @@ IMAGE_TAG=latest
 
 # Enable schema selection via LLM
 ENABLE_LLM_SCHEMA_SELECTION=true
-OPENAI_SCHEMA_SELECTOR_MODEL=gpt-4o-mini
+OPENAI_SCHEMA_SELECTOR_MODEL=gpt-5-nano
 
 # Enable hierarchical document chunking
 FEATURE_HIERARCHICAL_CHUNKING=true
 
+# ============================================
+# Temporal Configuration (Durable Workflows)
+# ============================================
+# Temporal enables durable workflows for batch memory processing and
+# document ingestion. For self-hosted deployments, use the Docker Temporal.
+#
+# For Docker (self-hosted Temporal):
+TEMPORAL_ADDRESS=temporal:7233
+TEMPORAL_NAMESPACE=default
+TEMPORAL_TASK_QUEUE=memory-processing
+
+# For Temporal Cloud (optional - if using Temporal Cloud instead):
+# TEMPORAL_ADDRESS=your-namespace.tmprl.cloud:7233
+# TEMPORAL_NAMESPACE=your-namespace
+# TEMPORAL_API_KEY=your-temporal-cloud-api-key
+
+# Enable/disable Temporal (set to false to use simple background tasks instead)
+TEMPORAL_ENABLED=true
+
+# ============================================
+# Document Processing Configuration (Optional)
+# ============================================
+# These providers are optional - configure as needed for document ingestion.
+# Leave as placeholders if you don't need document processing.
+
+# TensorLake - AI document parsing
+TENSORLAKE_API_KEY=your-tensorlake-api-key-here
+TENSORLAKE_BASE_URL=https://api.tensorlake.ai
+
+# Reducto - Document structure extraction
+REDUCTO_API_KEY=your-reducto-api-key-here
+REDUCTO_ENVIRONMENT=production
+REDUCTO_PIPELINE_ID=your-reducto-pipeline-id-here
+
+# Google Gemini - Vision/PDF processing
+GOOGLE_API_KEY=your-google-api-key-here
+
+# Groq - Fast LLM for document analysis
+GROQ_API_KEY=your-groq-api-key-here
+GROQ_NEO_CYPHER=1
+GROQ_FALLBACK_MODEL=openai/gpt-oss-20b
+
+# Cohere - Reranking (optional)
+COHERE_API_KEY=your-cohere-api-key-here
+
+# ============================================
+# Test Credentials (Auto-Generated)
+# ============================================
+# These are auto-populated on first startup by the bootstrap script.
+# After running `docker compose up -d`, check .env.opensource for real values.
+# Do NOT set these manually - they are created from Parse Server data.
+#
+# TEST_SESSION_TOKEN=r:auto-generated-on-first-run
+# TEST_X_USER_API_KEY=pmem_oss_auto-generated-on-first-run
+# TEST_USER_ID=auto-generated
+# TEST_TENANT_ID=auto-generated
+# TEST_WORKSPACE_ID=auto-generated
+# TEST_NAMESPACE_ID=auto-generated
+# TEST_ORGANIZATION_ID=auto-generated
+
 # ============================================
 # CLOUD-ONLY FEATURES (Not needed for OSS)
 # ============================================
 # The following are only used in cloud edition:
 # - AUTH0_* (OAuth authentication)
 # - STRIPE_* (Payment processing)
 # - AMPLITUDE_* (Cloud analytics)
-# - TEMPORAL_* (Durable workflows)
 # - AZURE_* (Azure services)
 # - NEO4J_GRAPHQL_ENDPOINT (Neo4j Aura GraphQL)

.gitignore

@@ -20,3 +20,8 @@ __pycache__/main.cpython-311.pyc
 .env.development
 .env.production
 keys/jwt-private.pem
+.env
+.env
+.env
+.env.mongodb_optimized
+.env