remdb 0.3.120__tar.gz → 0.3.148__tar.gz

{remdb-0.3.120 → remdb-0.3.148}/.env.example

@@ -28,6 +28,13 @@ API__PORT=8000
 API__RELOAD=true
 API__LOG_LEVEL=info
 
+# --- API Key Authentication ---
+# Simple API key auth for programmatic access (independent of OAuth)
+# When enabled, all /api/v1/* requests must include X-API-Key header
+# Generate key: python -c "import secrets; print(secrets.token_urlsafe(32))"
+API__API_KEY_ENABLED=false
+API__API_KEY=
+
 # =============================================================================
 # LLM Provider Settings
 # =============================================================================
@@ -37,7 +44,7 @@ LLM__MAX_RETRIES=10
 
 # Optional: Override models for specific tasks
 # LLM__EVALUATOR_MODEL=gpt-4.1
-# LLM__QUERY_AGENT_MODEL=gpt-4o-mini
+# LLM__QUERY_AGENT_MODEL=gpt-4.1-mini
 
 # API Keys (required for LLM providers)
 LLM__OPENAI_API_KEY=
@@ -71,6 +78,20 @@ AUTH__MICROSOFT__CLIENT_SECRET=
 AUTH__MICROSOFT__REDIRECT_URI=http://localhost:8000/api/auth/microsoft/callback
 AUTH__MICROSOFT__TENANT=common
 
+# =============================================================================
+# Email Settings (Passwordless Login)
+# =============================================================================
+# Email login uses verification codes - no password required
+# Supports Gmail SMTP with App Passwords by default
+# Generate app password at: https://myaccount.google.com/apppasswords
+EMAIL__ENABLED=false
+EMAIL__SMTP_HOST=smtp.gmail.com
+EMAIL__SMTP_PORT=587
+EMAIL__SENDER_EMAIL=
+EMAIL__SENDER_NAME=REM
+EMAIL__APP_PASSWORD=
+EMAIL__LOGIN_CODE_EXPIRY_MINUTES=10
+
 # =============================================================================
 # OpenTelemetry Settings
 # =============================================================================

{remdb-0.3.120 → remdb-0.3.148}/.gitignore

@@ -101,6 +101,7 @@ secrets/
 *.key
 *.crt
 credentials.json
+.pypirc
 
 # Build artifacts
 *.pyc

remdb-0.3.148/.kreuzberg/mime/2470f3a5e2d1953b.msgpack

@@ -0,0 +1 @@
+��type�str�data�application/pdf�cached_at�A�L�#w��

remdb-0.3.148/.kreuzberg/mime/34f1cfc7a58e8b0c.msgpack

@@ -0,0 +1,2 @@
+��type�str�data�application/pdf�cached_at�A�L�h
+7i

remdb-0.3.148/.kreuzberg/mime/56bf449feab17e6d.msgpack

@@ -0,0 +1 @@
+��type�str�data�application/pdf�cached_at�A�L�#�K

remdb-0.3.148/.kreuzberg/mime/8cace0ec228b43d6.msgpack

@@ -0,0 +1 @@
+��type�str�data�application/pdf�cached_at�A�L,�E�$

remdb-0.3.148/.kreuzberg/mime/99f1579d6a6790ad.msgpack

@@ -0,0 +1 @@
+��type�str�data�application/pdf�cached_at�A�L,� ��

remdb-0.3.148/.kreuzberg/mime/a0d60cff1e5950a6.msgpack

@@ -0,0 +1 @@
+��type�str�data�application/pdf�cached_at�A�L�g�o

remdb-0.3.148/.kreuzberg/mime/b2b5204d4dfab9dc.msgpack

@@ -0,0 +1 @@
+��type�str�data�application/pdf�cached_at�A�L,a��:

remdb-0.3.148/.kreuzberg/mime/d1df948b17e4d9fc.msgpack

@@ -0,0 +1 @@
+��type�str�data�application/pdf�cached_at�A�L,a��

{remdb-0.3.120 → remdb-0.3.148}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remdb
-Version: 0.3.120
+Version: 0.3.148
 Summary: Resources Entities Moments - Bio-inspired memory system for agentic AI workloads
 Project-URL: Homepage, https://github.com/Percolation-Labs/reminiscent
 Project-URL: Documentation, https://github.com/Percolation-Labs/reminiscent/blob/main/README.md
@@ -12,9 +12,11 @@ Keywords: agents,ai,mcp,memory,postgresql,vector-search
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Python: <3.13,>=3.12
+Requires-Python: <3.14,>=3.11
 Requires-Dist: aioboto3>=13.0.0
 Requires-Dist: arize-phoenix>=5.0.0
 Requires-Dist: asyncpg>=0.30.0
@@ -123,9 +125,8 @@ Cloud-native unified memory infrastructure for agentic AI systems built with Pyd
 
 Choose your path:
 
-- **Option 1: Package Users with Example Data** (Recommended for first-time users) - PyPI + example datasets
-- **Option 2: Package Users** (Recommended for non-developers) - PyPI package + dockerized database
-- **Option 3: Developers** - Clone repo, local development with uv
+- **Option 1: Package Users with Example Data** (Recommended) - PyPI + example datasets
+- **Option 2: Developers** - Clone repo, local development with uv
 
 ---
 
@@ -144,13 +145,9 @@ pip install "remdb[all]"
 git clone https://github.com/Percolation-Labs/remstack-lab.git
 cd remstack-lab
 
-# Optional: Set default LLM provider via environment variable
-# export LLM__DEFAULT_MODEL="openai:gpt-4.1-nano"  # Fast and cheap
-# export LLM__DEFAULT_MODEL="anthropic:claude-sonnet-4-5-20250929"  # High quality (default)
-
-# Start PostgreSQL with docker-compose
+# Start services (PostgreSQL, Phoenix observability)
 curl -O https://gist.githubusercontent.com/percolating-sirsh/d117b673bc0edfdef1a5068ccd3cf3e5/raw/docker-compose.prebuilt.yml
-docker compose -f docker-compose.prebuilt.yml up -d postgres
+docker compose -f docker-compose.prebuilt.yml up -d
 
 # Configure REM (creates ~/.rem/config.yaml and installs database schema)
 # Add --claude-desktop to register with Claude Desktop app
@@ -163,7 +160,7 @@ rem db load datasets/quickstart/sample_data.yaml
 rem ask "What documents exist in the system?"
 rem ask "Show me meetings about API design"
 
-# Ingest files (PDF, DOCX, images, etc.) - note: requires remstack-lab
+# Ingest files (PDF, DOCX, images, etc.)
 rem process ingest datasets/formats/files/bitcoin_whitepaper.pdf --category research --tags bitcoin,whitepaper
 
 # Query ingested content
@@ -177,125 +174,39 @@ rem ask "What is the Bitcoin whitepaper about?"
 
 **Learn more**: [remstack-lab repository](https://github.com/Percolation-Labs/remstack-lab)
 
----
-
-## Option 2: Package Users (No Example Data)
+### Using the API
 
-**Best for**: Using REM as a service (API + CLI) without modifying code, bringing your own data.
-
-### Step 1: Start Database and API with Docker Compose
+Once configured, you can also use the OpenAI-compatible chat completions API:
 
 ```bash
-# Create a project directory
-mkdir my-rem-project && cd my-rem-project
-
-# Download docker-compose file from public gist
-curl -O https://gist.githubusercontent.com/percolating-sirsh/d117b673bc0edfdef1a5068ccd3cf3e5/raw/docker-compose.prebuilt.yml
-
-# IMPORTANT: Export API keys BEFORE running docker compose
-# Docker Compose reads env vars at startup - exporting them after won't work!
-
-# Required: OpenAI for embeddings (text-embedding-3-small)
-export OPENAI_API_KEY="sk-..."
-
-# Recommended: At least one chat completion provider
-export ANTHROPIC_API_KEY="sk-ant-..."           # Claude Sonnet 4.5 (high quality)
-export CEREBRAS_API_KEY="csk-..."               # Cerebras (fast, cheap inference)
-
-# Start PostgreSQL + API
+# Start all services (PostgreSQL, Phoenix, API)
 docker compose -f docker-compose.prebuilt.yml up -d
 
-# Verify services are running
-curl http://localhost:8000/health
-```
-
-This starts:
-- **PostgreSQL** with pgvector on port **5051** (connection: `postgresql://rem:rem@localhost:5051/rem`)
-- **REM API** on port **8000** with OpenAI-compatible chat completions + MCP server
-- Uses pre-built Docker image from Docker Hub (no local build required)
-
-### Step 2: Install and Configure CLI (REQUIRED)
-
-**This step is required** before you can use REM - it installs the database schema and configures your LLM API keys.
-
-```bash
-# Install remdb package from PyPI
-pip install remdb[all]
-
-# Configure REM (defaults to port 5051 for package users)
-rem configure --install --claude-desktop
+# Test the API
+curl -X POST http://localhost:8000/api/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "X-Session-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
+  -d '{
+    "model": "anthropic:claude-sonnet-4-5-20250929",
+    "messages": [{"role": "user", "content": "What documents did Sarah Chen author?"}],
+    "stream": false
+  }'
 ```
 
-The interactive wizard will:
-1. **Configure PostgreSQL**: Defaults to `postgresql://rem:rem@localhost:5051/rem` (prebuilt docker-compose)
-   - Just press Enter to accept defaults
-   - Custom database: Enter your own host/port/credentials
-2. **Configure LLM providers**: Enter your OpenAI/Anthropic API keys
-3. **Install database tables**: Creates schema, functions, indexes (**required for CLI/API to work**)
-4. **Register with Claude Desktop**: Adds REM MCP server to Claude
-
-Configuration saved to `~/.rem/config.yaml` (can edit with `rem configure --edit`)
-
 **Port Guide:**
 - **5051**: Package users with `docker-compose.prebuilt.yml` (pre-built image)
 - **5050**: Developers with `docker-compose.yml` (local build)
-- **Custom**: Your own PostgreSQL database
 
 **Next Steps:**
 - See [CLI Reference](#cli-reference) for all available commands
 - See [REM Query Dialect](#rem-query-dialect) for query examples
 - See [API Endpoints](#api-endpoints) for OpenAI-compatible API usage
 
-### Step 3: Load Sample Data (Optional but Recommended)
-
-**Option A: Clone example datasets** (Recommended - works with all README examples)
-
-```bash
-# Clone datasets repository
-git clone https://github.com/Percolation-Labs/remstack-lab.git
-
-# Load quickstart dataset
-rem db load --file remstack-lab/datasets/quickstart/sample_data.yaml
-
-# Test with sample queries
-rem ask "What documents exist in the system?"
-rem ask "Show me meetings about API design"
-rem ask "Who is Sarah Chen?"
-```
-
-**Option B: Bring your own data**
-
-```bash
-# Ingest your own files
-echo "REM is a bio-inspired memory system for agentic AI workloads." > test-doc.txt
-rem process ingest test-doc.txt --category documentation --tags rem,ai
-
-# Query your ingested data
-rem ask "What do you know about REM from my knowledge base?"
-```
-
-### Step 4: Test the API
-
-```bash
-# Test the OpenAI-compatible chat completions API
-curl -X POST http://localhost:8000/api/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "anthropic:claude-sonnet-4-5-20250929",
-    "messages": [{"role": "user", "content": "What documents did Sarah Chen author?"}],
-    "stream": false
-  }'
-```
-
-**Available Commands:**
-- `rem ask` - Natural language queries to REM
-- `rem process ingest <file>` - Full ingestion pipeline (storage + parsing + embedding + database)
-- `rem process uri <file>` - READ-ONLY parsing (no database storage, useful for testing parsers)
-- `rem db load --file <yaml>` - Load structured datasets directly
+---
 
 ## Example Datasets
 
-🎯 **Recommended**: Clone [remstack-lab](https://github.com/Percolation-Labs/remstack-lab) for curated datasets organized by domain and format.
+Clone [remstack-lab](https://github.com/Percolation-Labs/remstack-lab) for curated datasets organized by domain and format.
 
 **What's included:**
 - **Quickstart**: Minimal dataset (3 users, 3 resources, 3 moments) - perfect for first-time users
@@ -422,7 +333,7 @@ rem ask research-assistant "Find documents about machine learning architecture"
 rem ask research-assistant "Summarize recent API design documents" --stream
 
 # With session continuity
-rem ask research-assistant "What did we discuss about ML?" --session-id abc-123
+rem ask research-assistant "What did we discuss about ML?" --session-id c3d4e5f6-a7b8-9012-cdef-345678901234
 ```
 
 ### Agent Schema Structure
@@ -475,14 +386,6 @@ rem process ingest my-agent.yaml --user-id tenant-a --category agents
 rem ask my-agent "test" --user-id tenant-a
 ```
 
-### Advanced: Ontology Extractors
-
-Custom agents can also be used as **ontology extractors** to extract structured knowledge from files. See [CLAUDE.md](../CLAUDE.md#ontology-extraction-pattern) for details on:
-- Multi-provider testing (`provider_configs`)
-- Semantic search configuration (`embedding_fields`)
-- File matching rules (`OntologyConfig`)
-- Dreaming workflow integration
-
 ### Troubleshooting
 
 **Schema not found error:**
@@ -1235,7 +1138,7 @@ export API__RELOAD=true
 rem serve
 ```
 
-## Development (For Contributors)
+## Option 2: Development (For Contributors)
 
 **Best for**: Contributing to REM or customizing the codebase.
 
@@ -1531,45 +1434,156 @@ Successfully installed ... kreuzberg-4.0.0rc1 ... remdb-0.3.10
 
 REM wraps FastAPI - extend it exactly as you would any FastAPI app.
 
+### Recommended Project Structure
+
+REM auto-detects `./agents/` and `./models/` folders - no configuration needed:
+
+```
+my-rem-app/
+├── agents/                 # Auto-detected for agent schemas
+│   ├── my-agent.yaml       # Custom agent (rem ask my-agent "query")
+│   └── another-agent.yaml
+├── models/                 # Auto-detected if __init__.py exists
+│   └── __init__.py         # Register models with @rem.register_model
+├── routers/                # Custom FastAPI routers
+│   └── custom.py
+├── main.py                 # Entry point
+└── pyproject.toml
+```
+
+### Quick Start
+
 ```python
-import rem
+# main.py
 from rem import create_app
-from rem.models.core import CoreModel
+from fastapi import APIRouter
 
-# 1. Register models (for schema generation)
-rem.register_models(MyModel, AnotherModel)
+# Create REM app (auto-detects ./agents/ and ./models/)
+app = create_app()
 
-# 2. Register schema paths (for custom agents/evaluators)
-rem.register_schema_path("./schemas")
+# Add custom router
+router = APIRouter(prefix="/custom", tags=["custom"])
 
-# 3. Create app
-app = create_app()
+@router.get("/hello")
+async def hello():
+    return {"message": "Hello from custom router!"}
 
-# 4. Extend like normal FastAPI
-app.include_router(my_router)
+app.include_router(router)
 
+# Add custom MCP tool
 @app.mcp_server.tool()
 async def my_tool(query: str) -> dict:
-    """Custom MCP tool."""
+    """Custom MCP tool available to agents."""
     return {"result": query}
 ```
 
-### Project Structure
+### Custom Models (Auto-Detected)
 
+```python
+# models/__init__.py
+import rem
+from rem.models.core import CoreModel
+from pydantic import Field
+
+@rem.register_model
+class MyEntity(CoreModel):
+    """Custom entity - auto-registered for schema generation."""
+    name: str = Field(description="Entity name")
+    status: str = Field(default="active")
 ```
-my-rem-app/
-├── my_app/
-│   ├── main.py           # Entry point (create_app + extensions)
-│   ├── models.py         # Custom models (inherit CoreModel)
-│   └── routers/          # Custom FastAPI routers
-├── schemas/
-│   ├── agents/           # Custom agent YAML schemas
-│   └── evaluators/       # Custom evaluator schemas
-├── sql/migrations/       # Custom SQL migrations
-└── pyproject.toml
+
+Run `rem db schema generate` to include your models in the database schema.
+
+### Custom Agents (Auto-Detected)
+
+```yaml
+# agents/my-agent.yaml
+type: object
+description: |
+  You are a helpful assistant that...
+
+properties:
+  answer:
+    type: string
+    description: Your response
+
+required:
+  - answer
+
+json_schema_extra:
+  kind: agent
+  name: my-agent
+  version: "1.0.0"
+  tools:
+    - search_rem
 ```
 
-Generate this structure with: `rem scaffold my-app`
+Test with: `rem ask my-agent "Hello!"`
+
+### Example Custom Router
+
+```python
+# routers/analytics.py
+from fastapi import APIRouter, Depends
+from rem.services.postgres import get_postgres_service
+
+router = APIRouter(prefix="/analytics", tags=["analytics"])
+
+@router.get("/stats")
+async def get_stats():
+    """Get database statistics."""
+    db = get_postgres_service()
+    if not db:
+        return {"error": "Database not available"}
+
+    await db.connect()
+    try:
+        result = await db.execute(
+            "SELECT COUNT(*) as count FROM resources"
+        )
+        return {"resource_count": result[0]["count"]}
+    finally:
+        await db.disconnect()
+
+@router.get("/recent")
+async def get_recent(limit: int = 10):
+    """Get recent resources."""
+    db = get_postgres_service()
+    if not db:
+        return {"error": "Database not available"}
+
+    await db.connect()
+    try:
+        result = await db.execute(
+            f"SELECT label, category, created_at FROM resources ORDER BY created_at DESC LIMIT {limit}"
+        )
+        return {"resources": result}
+    finally:
+        await db.disconnect()
+```
+
+Include in main.py:
+
+```python
+from routers.analytics import router as analytics_router
+app.include_router(analytics_router)
+```
+
+### Running the App
+
+```bash
+# Development (auto-reload)
+uv run uvicorn main:app --reload --port 8000
+
+# Or use rem serve
+uv run rem serve --reload
+
+# Test agent
+uv run rem ask my-agent "What can you help me with?"
+
+# Test custom endpoint
+curl http://localhost:8000/analytics/stats
+```
 
 ### Extension Points