para-files Documentation

Welcome to para-files! This documentation is organized by how you want to use it.

I want to

Get Started

• Installation - Install para-files and verify it works
• Quick Setup - Configure in 5 minutes
• Classify My First File - Run your first classification

Use para-files

• CLI Overview - What commands are available
• Task Guides - How-to guides for common tasks:
  • Set up PARA folder
  • Classify files
  • Move files to categories
  • Manage issuers & routes
  • Learn from your files

Configure para-files

• Configuration Overview - How configuration works
• Environment Variables - Set via .env file
• YAML Config - Configure in personal_file_tree.yaml

Understand How It Works

• Architecture Overview - The big picture
• 6-Signal Pipeline - How files are classified
• Reference Tree - YAML structure explained
• MLX Embeddings - Semantic matching details

Troubleshoot Issues

• Files going to Inbox - Wrong classifications
• Low confidence scores - Adjusting thresholds
• Model download issues - Caching & performance

Develop & Extend

• Developer Guide - Building & contributing (in CLAUDE.md)
• Python API - Use para-files in your code

Quick Commands Reference

# Classify
uv run para-files classify document.pdf

# Move to PARA folders
uv run para-files move *.pdf --dry-run

# Add a bank
uv run para-files add-issuer "My Bank" -c banques

# Interactive learning
uv run para-files learn document.pdf

Full CLI Reference →

Key Features

• 6-Signal Pipeline: Validated DB → Rules → Book Detection → Domain KB → Semantic Router → LLM
• MLX Embeddings: Fast local semantic matching on Apple Neural Engine
• PARA Method: Organize into Projects, Areas, Resources, Archives
• Extensible: Add custom routes, issuers, and utterances via YAML
• Photo/Video Geotagging: GPS-aware organization by location
• Book Detection: Technical book identification via ISBN/metadata

System Requirements

• macOS with Apple Silicon (M1/M2/M3/M4)
• Python 3.12+
• uv package manager