QUICKSTART.md

Quick Start Guide

Initial Setup (First Time)

1. Run the setup script:

   bash setup.sh
   

2. Configure your credentials: Edit .env file with your credentials:

   • Get HuggingFace token from: https://huggingface.co/settings/tokens
   • Get Anthropic API key from: https://console.anthropic.com/

3. Update space names: Edit config.yaml to set your HuggingFace space names

Using the Web Interface

streamlit run app.py

Then open your browser to the URL shown (usually http://localhost:8501)

Web Interface Features:

• Dashboard: Overview of your spaces and recent activity
• AI Agent: Chat with Claude to get help with code and file management
• File Manager: Browse, upload, and manage files
• Space Sync: Synchronize files to HuggingFace Spaces
• Audit & Archive: Create file inventories and compressed archives

Using the Command Line

Run File Audit

python automation.py audit

Creates inventory.json and genesis_archive_*.tar.gz

Sync All Configured Spaces

python automation.py sync

Uploads files to all spaces with auto_sync: true

Sync Specific Space

python automation.py sync-space --space vamguard-titan

Create Backup

python automation.py backup

Backs up everything to mapping-and-inventory space

Full Automation

python automation.py full

Runs: audit → sync all → backup

GitHub Actions Setup

For automated syncing via GitHub Actions:

1. Add secrets to your GitHub repository:

   • Go to Settings → Secrets and variables → Actions
   • Add: HF_TOKEN, HF_USERNAME, ANTHROPIC_API_KEY

2. Push to trigger:

   git add .
   git commit -m "Initial setup"
   git push
   

3. Manual trigger:

   • Go to Actions tab on GitHub
   • Select "HuggingFace Space Sync" workflow
   • Click "Run workflow"

Common Tasks

Create a New HuggingFace Space

Via Web UI:

1. Open app: streamlit run app.py
2. Navigate to "Space Sync" → "Create Space" tab
3. Enter space name and click "Create Space"

Via Python:

from hf_space_sync import HFSpaceSync

sync = HFSpaceSync()
sync.create_space("my-new-space", "streamlit", private=False)

Upload Files to a Space

from hf_space_sync import HFSpaceSync

sync = HFSpaceSync()
sync.upload_files("vamguard-titan", "app.py", commit_message="Update app")

Ask the AI Agent for Help

Via Web UI:

1. Open app: streamlit run app.py
2. Go to "AI Agent" page
3. Type your question: "How do I organize my Python files?"

Via Python:

from app import AIAgent

agent = AIAgent()
response = agent.process_request("Help me sync files to HuggingFace")
print(response)

Troubleshooting

"Module not found" errors:

source venv/bin/activate  # Activate virtual environment
pip install -r requirements.txt

HuggingFace authentication errors:

• Check .env file has correct HF_TOKEN
• Verify token at https://huggingface.co/settings/tokens
• Ensure token has write permissions

AI Agent not responding:

• Verify ANTHROPIC_API_KEY in .env
• Check API key at https://console.anthropic.com/
• Ensure you have API credits

File Locations

• Configuration: config.yaml
• Environment: .env
• Logs: automation_log_*.txt
• Reports: automation_report_*.json
• Inventories: inventory.json
• Archives: genesis_archive_*.tar.gz

Getting Help

• Check the full README.md for detailed documentation
• Review logs in automation_log_*.txt
• Open an issue on GitHub
• Use the AI Agent in the web interface

Next Steps

1. Customize config.yaml for your needs
2. Add more spaces to the configuration
3. Set up GitHub Actions for automation
4. Explore the AI Agent capabilities
5. Create scheduled backups

Happy coding! 🚀