Skip to content

AGENTS.md

Latest commit

 

History

History
99 lines (69 loc) · 2.94 KB

AGENTS.md

File metadata and controls

99 lines (69 loc) · 2.94 KB

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