Knowledger

Knowledger is a FastAPI + Next.js application for grounded, knowledge-based answers to questions.

Stack

Component	Technology
Backend	FastAPI + Pydantic v2
Database	PostgreSQL (async)
Auth	JWT + API key + refresh tokens
Cache / Broker	Redis
AI Framework	pydantic_ai (OpenAI)
RAG	pgvector
Tasks	Celery
Frontend	Next.js 15 + React 19 + Tailwind v4

Local Setup

Prerequisites:

• Python/uv for the backend
• Bun for the frontend
• PostgreSQL and Redis running locally or reachable via DATABASE_URL and REDIS_URL

# Install backend dependencies
make install

# Apply migrations
make db-upgrade

# Create an admin user
make create-admin

# Start the backend
make run

# Start the frontend in another terminal
cd frontend
bun install
bun dev

Commands

Run make help for the full list. Common commands:

Command	Description
make install	Install backend dependencies and hooks
make quickstart	Install deps, apply migrations, and create an admin user
make run	Start the backend dev server
make test	Run backend tests
make lint	Run linting and type checks
make format	Auto-format backend code
make db-upgrade	Apply migrations
make create-admin	Create an admin user

AI Agent

Using pydantic_ai with the OpenAI provider.

Chat with the agent at http://localhost:3000/chat.

Customize

• System prompt: app/agents/prompts.py
• Add tools: See docs/howto/add-agent-tool.md
• Agent config: .env → AI_MODEL, AI_TEMPERATURE

Message Ratings

Users can rate AI responses with 👍/👎 and optional feedback comments.

Administrators can view analytics and export rating data.

• Rate messages at http://localhost:3000/chat
• Admin dashboard at http://localhost:8000/admin/ratings

See docs/howto/use-ratings.md for full documentation.

RAG (Knowledge Base)

Using pgvector as vector store.

Ingest documents

# Local files
uv run my_project rag-ingest /path/to/docs/ --collection documents --recursive

# Google Drive
uv run my_project rag-sync-gdrive --collection documents --folder-id <id>

# S3/MinIO
uv run my_project rag-sync-s3 --collection documents --prefix docs/

Search

uv run my_project rag-search "your query" --collection documents

Manage collections

uv run my_project rag-collections   # List all
uv run my_project rag-stats          # Show stats
uv run my_project rag-drop <name>    # Delete collection

Sync sources

Sync sources let you configure recurring document ingestion from external systems (Google Drive, S3, etc.) via the API or CLI.

uv run my_project cmd rag-sources          # List configured sources
uv run my_project cmd rag-source-add       # Add a new source
uv run my_project cmd rag-source-sync      # Trigger sync for a source
uv run my_project cmd rag-source-remove    # Remove a source

See docs/howto/add-sync-connector.md for how to add custom connectors.

Project Structure

backend/app/
├── api/routes/v1/        # API endpoints
├── core/config.py        # Settings (from .env)
├── services/             # Business logic
├── repositories/         # Data access
├── schemas/              # Pydantic models
├── db/models/            # Database models
├── agents/               # AI agents & tools
├── rag/                  # RAG pipeline (embeddings, vector store, ingestion)
│   └── connectors/       # Sync source connectors
├── commands/             # CLI commands (auto-discovered)
└── worker/               # Background tasks

Guides

Guide	Description
docs/howto/add-api-endpoint.md	Add a new API endpoint
docs/howto/add-agent-tool.md	Create a new agent tool
docs/howto/customize-agent-prompt.md	Customize agent behavior
docs/howto/add-background-task.md	Add background tasks
docs/howto/add-rag-source.md	Add a new RAG document source
docs/howto/add-sync-connector.md	Create a new sync connector

Environment Variables

All config is in backend/.env. Key variables:

POSTGRES_HOST=localhost
POSTGRES_PASSWORD=postgres
OPENAI_API_KEY=sk-...
RAG_CHUNKING_STRATEGY=recursive  # recursive, markdown, fixed
RAG_HYBRID_SEARCH=false

See backend/.env.example for all available variables.

For deployment:

• backend/.env.example covers backend defaults and managed-service overrides
• frontend/.env.example covers the frontend runtime variables
• .env.prod.example lists the production values you will want to set in Render

Deployment

Deploy the backend and frontend as separate Render services.

Use these repo files together:

1. render.yaml for the Render blueprint
2. .env.prod.example for the production variable checklist
3. docs/howto/deploy-to-render.md for the service-by-service guide

Recommended high-level setup:

1. Create PostgreSQL and Redis in Render.
2. Review the sync: false values in render.yaml and replace them with your real URLs and secrets.
3. Deploy backend as a Python web service.
4. Deploy frontend as a Node web service.
5. Add Celery worker services only if you need background jobs.

If you want Render to provision from the repository directly, import the root render.yaml as a Blueprint.