Imported from onllm-dev/4DPocket (AGENTS.md). Install upstream with npx skills add onllm-dev/4DPocket. Copyright stays with the author.

4DPocket - Setup & Testing Guide

Quick Start

Prerequisites

• Python 3.12+ with uv
• Node.js 18+ with pnpm
• Optional: Ollama (local AI), Docker (full stack)

1. Backend Setup

git clone https://github.com/onllm-dev/4DPocket.git
cd 4DPocket
uv sync --all-extras

2. Start Backend

# Single-user mode (no login)
uv run uvicorn fourdpocket.main:app --port 4040

# Multi-user mode (with auth)
FDP_AUTH__MODE=multi uv run uvicorn fourdpocket.main:app --port 4040

3. Frontend Setup

cd frontend
pnpm install
pnpm dev

App runs at http://localhost:5173, API at http://localhost:4040/docs

4. First User (Multi-User Mode)

First registered user auto-becomes admin:

curl -X POST http://localhost:4040/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","email":"admin@local","password":"admin1234","display_name":"Admin"}'

Login at http://localhost:5173/login with admin@local / admin1234

Running Tests

# Backend (304 tests, in-memory SQLite)
uv run pytest tests/ -x -q

# Frontend type check
cd frontend && pnpm build

# Lint
make lint

Configuration

All via env vars with FDP_ prefix. Key settings:

FDP_AUTH__MODE=single           # single (no login) or multi (JWT auth)
FDP_AI__CHAT_PROVIDER=ollama    # ollama, groq, or nvidia
FDP_SEARCH__BACKEND=sqlite      # sqlite (FTS5) or meilisearch
FDP_DATABASE__URL=sqlite:///data/4dpocket.db

See .env.example for full reference.

Docker (Full Stack)

cp .env.example .env
docker compose up

Includes: app, worker, PostgreSQL, Meilisearch, ChromaDB, Ollama.

MCP Server (Agent Integration)

The server mounts a FastMCP streamable-HTTP endpoint at /mcp. Mint a PAT in Settings → API Tokens & MCP, point Claude Desktop / Cursor / Claude Code at http://localhost:4040/mcp with Authorization: Bearer fdp_pat_..., and you get 10 tools: save_knowledge, search_knowledge, get_knowledge, update_knowledge, refresh_knowledge, delete_knowledge, list_collections, add_to_collection, get_entity, get_related_entities. See README for client config snippets.

Architecture Notes

• 17 content processors auto-detect platform from URL
• AI enrichment runs as Huey background task (sync fallback if worker unavailable)
• Search: section-aware chunk-level hybrid — FTS5/Meilisearch (with section metadata) + ChromaDB/pgvector + RRF + optional cross-encoder reranking
• PATs (fdp_pat_*) authenticate MCP clients with per-token collection ACL + role (viewer/editor) + optional allow_deletion / admin_scope
• Entity synthesis: per-entity structured JSON wiki pages regenerated on threshold (default 3 new mentions, 24h throttle)
• All user data is scoped per-user. Sharing creates references, not copies.
• Rules engine executes on item creation (condition-action pattern)
• PWA with share target: share URLs from phone directly to 4DPocket