bel-download-file-from-crm-db

name	bel-download-file-from-crm-db
description	This skill should be used when the user wants to download or retrieve a file from the CRM database and save it to the filesystem. Triggers on requests like "download the contract from CRM", "save the database file to disk", "get the PDF from the database", or "retrieve the attachment from CRM". Uses the bel-crm-db skill for schema knowledge.

Download File from CRM Database

Download files stored in the CRM PostgreSQL database and save them to the filesystem in _RESULTS_FROM_AGENT/.

When to Use This Skill

Use this skill when the user wants to:

• Download a file from the CRM database to disk
• Retrieve a document/image/PDF stored in the database
• Save a database attachment to the filesystem
• Export file data from the CRM

Trigger phrases:

• "Download the contract from the database"
• "Save the file from CRM to disk"
• "Get me the PDF from database ID 123"
• "Retrieve the attachment for company X"
• "Export the image from the database"

Do NOT use this skill if:

• The user only wants to view/open a file (use bel-open-file instead)
• The user wants to see a file from the database (use bel-show-crm-file instead)
• The file is already on disk (no download needed)

How to Use This Skill

Step 1: Use the CRM Database Skill for Schema Knowledge

To understand the database structure and query files, invoke the bel-crm-db skill first to get access to table schemas and connection details.

Step 2: Identify the File to Download

Determine the file_id from the database. This may require querying tables that link to files:

Common junction tables:

• Files linked to companies: company_site_file table
• Files linked to people: person_file table
• Files linked to events: event_file table
• Files linked to opportunities: sales_opportunity_file table

Example query to find files:

-- Find all files for a company
SELECT f.file_id, f.file_name, f.mime_type, f.file_size
FROM file f
JOIN company_site_file csf ON f.file_id = csf.file_id
WHERE csf.company_site_id = 123;

Step 3: Download the File

Execute the download script with the file_id:

python scripts/download_file_from_db.py <file_id>

Options:

# Download with custom output directory
python scripts/download_file_from_db.py 456 --output-dir /custom/path

# Quiet mode (only output file path)
python scripts/download_file_from_db.py 456 --quiet

Step 4: Report Results to User

Inform the user where the file was saved:

✅ File downloaded successfully!
   File path: _RESULTS_FROM_AGENT/contract.pdf
   Original name: contract.pdf
   MIME type: application/pdf
   Size: 245,832 bytes

Technical Details

Database Schema

The script queries the file table with this structure:

CREATE TABLE file (
    file_id SERIAL PRIMARY KEY,
    file_hash VARCHAR(64) UNIQUE NOT NULL,
    file_name VARCHAR(255) NOT NULL,
    mime_type VARCHAR(127),
    file_data BYTEA NOT NULL,
    file_size INTEGER,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

File Storage

• Default location: _RESULTS_FROM_AGENT/
• Filename collision handling: Appends _1, _2, etc. if file exists
• Path traversal protection: Sanitizes filenames before saving

Database Connection

The script uses environment variables for database connection:

• POSTGRES_URL (preferred): Full connection string
• Or individual variables: POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD

Error Handling

Common errors:

• File not found: file_id doesn't exist in database
• Connection error: Database credentials incorrect or server unavailable
• Permission error: Insufficient write permissions for output directory
• Disk space: Insufficient space for large files

Integration with Other Skills

This skill integrates with:

• bel-crm-db: For schema knowledge and querying file metadata
• bel-open-file: To open the downloaded file after saving
• bel-show-crm-file: Orchestration skill that uses both download and open

Example Workflows

Workflow 1: Download a specific file by ID

User: "Download file ID 789 from the database"

1. Use bel-crm-db to understand schema
2. Run: python scripts/download_file_from_db.py 789
3. Report the saved file path to user

Workflow 2: Find and download a company's contract

User: "Download the contract for Acme Corp"

1. Use bel-crm-db to query:
   - Find company_site_id for "Acme Corp"
   - Find file_id via company_site_file junction table
2. Run: python scripts/download_file_from_db.py <file_id>
3. Report results to user

Workflow 3: Download multiple files

User: "Download all images for event ID 5"

1. Query event_file junction table for all file_ids
2. Loop through each file_id:
   - python scripts/download_file_from_db.py <file_id>
3. Report all downloaded file paths