paqr helps research teams move from loose files, notes, tables, and metadata into a reproducible data package that can be inspected from the command line, served over an API, and explored in a small UI.

MVP Scope

Discovery scans raw dataset folders and builds an inventory of candidate files.
Sanitization normalizes filenames, paths, and tabular data where safe.
Metadata extraction captures dataset context, schema hints, and provenance.
HDF5 packaging stores cleaned data and metadata in a portable package format.
Inventory output makes generated packages searchable and auditable.
REST API endpoints expose package status and dataset records for integrations.
CLI commands support scanning, packaging, and serving local demos.
UI exploration uses Streamlit for a lightweight package browser.
CI checks keep the foundation runnable as features land.
Docs record installation, demo commands, and operating assumptions.

Install

git clone <repo-url> paqr
cd paqr
python -m pip install -e ".[dev]"

Demo

The default AI backend is AI_MODE=mock, which requires no API key. This keeps local demos deterministic and runnable without external services.

# Start from a clean demo output file if you have run this before.
rm -f data/sample_output/sample.h5

# Inspect the bundled sample dataset.
AI_MODE=mock rpack scan data/sample_raw

# Profile tabular files in the sample dataset.
AI_MODE=mock rpack profile data/sample_raw

# Build an HDF5 package from the sample dataset.
AI_MODE=mock rpack package data/sample_raw --output data/sample_output/sample.h5

# Search the local inventory created by the package command.
AI_MODE=mock rpack search research

# Serve the local REST API for package inspection.
AI_MODE=mock rpack serve --host 127.0.0.1 --port 8000

In another terminal, you can check the API:

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/datasets

Run the React frontend shell in another terminal:

cd frontend
npm install
npm run dev

The React app runs at http://127.0.0.1:5173 and calls the API at http://127.0.0.1:8000 by default. Set VITE_PAQR_API_URL before npm run dev to point it at a different API URL. Dataset detail includes an explanatory provenance graph and a UI-only RBAC mockup for researcher, reviewer, and admin states.

Docker Compose

Run the API with PostgreSQL for local containerized development:

docker compose up --build

The Compose app service uses AI_MODE=mock, exposes the API at http://127.0.0.1:8000, and mounts the project directory so bundled sample data is available in the container. The db service starts PostgreSQL with local development credentials and database name paqr.

Launch the Streamlit browser from the project root:

AI_MODE=mock streamlit run app/ui/streamlit_app.py

The demo writes data/sample_output/sample.h5 and indexes it in the default SQLite inventory at data/inventory.db. Delete those files to reset the local demo.

The access-control displays are mockups only. They do not authenticate users, authorize API calls, protect local files, or restrict downloads.

For detailed CLI, API, UI, AI mode, cleanup, importer support, and troubleshooting instructions, see docs/user-guide.md and docs/importers.md.