README.md

metadata

title: Trace Your Digital Footprint
emoji: 🕵️
colorFrom: purple
colorTo: indigo
sdk: docker
app_port: 8000
pinned: false

🕵️ Trace — "Your Digital Footprint"

Meta OpenEnv Hackathon 2026 | Team Submission

Trace is a privacy-centric, multi-agent RL environment that builds a dynamic Semantic World Model of a user's fragmented digital life — without centralizing data.

---

Themes Addressed

Theme	Coverage
Theme #2 – Long-Horizon Planning & Instruction Following	Primary — federated multi-step retrieval across years of data
Theme #1 – Multi-Agent Interactions	Secondary — planner, retriever, verifier, memory agents
Theme #4 – Self-Improvement	Tertiary — agents learn from past executions, refine strategies
Sub-theme: Scale AI	Non-code long-horizon business/personal workflows
Sub-theme: Patronus AI	Consumer workflows with schema drift (Gmail/Drive APIs change)

---

Architecture Overview

User Query (e.g., "Audit all receipts from 2022-2024 and flag anomalies")
       │
       ▼
┌─────────────────────────────────────────────────────────┐
│                   PLANNER AGENT                          │
│  plan-act-verify framework | goal decomposition          │
└────────────────────────┬────────────────────────────────┘
                         │ sub-tasks
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
   RETRIEVER AGENT   MEMORY AGENT  VERIFIER AGENT
   (federated fetch) (episodic KV) (reward scorer)
          │              │              │
          └──────────────┴──────────────┘
                         │ observations
                         ▼
              OpenEnv Environment Loop
              (reset / step / reward)
                         │
                         ▼
              TRL + Unsloth RL Training

---

Quick Start

# 1. Install dependencies
pip install -r requirements.txt

# 2. Bootstrap OpenEnv environment
cd environments/trace_env
openenv init   # or run: uvicorn app:app --reload

# 3. Run training script (Google Colab friendly)
cd training
python train_grpo.py --config ../configs/grpo_config.yaml

# 4. Evaluate
python scripts/evaluate.py --env-url http://localhost:8000

---

Project Structure

trace/
├── environments/
│   └── trace_env/          # OpenEnv-compatible RL environment
│       ├── app.py           # FastAPI server (OpenEnv interface)
│       ├── core/
│       │   ├── env.py       # TraceEnv: reset(), step(), state()
│       │   ├── world_model.py  # Semantic World Model (SWM)
│       │   └── schemas.py   # Action / Observation dataclasses
│       ├── agents/
│       │   ├── planner.py   # Long-horizon goal decomposer
│       │   ├── retriever.py # Federated data fetcher (Gmail, Drive)
│       │   ├── memory.py    # Episodic + semantic memory store
│       │   └── verifier.py  # Plan verification agent
│       ├── tools/
│       │   ├── gmail_tool.py
│       │   ├── drive_tool.py
│       │   └── timeline_tool.py
│       └── rewards/
│           ├── reward_fn.py # Multi-component reward functions
│           └── anti_hack.py # Anti-reward-hacking guards
├── training/
│   ├── train_grpo.py        # Main RL training script (TRL + Unsloth)
│   ├── dataset.py           # Task curriculum generator
│   └── callbacks.py         # Training monitors
├── configs/
│   ├── grpo_config.yaml     # GRPO hyperparameters
│   └── env_config.yaml      # Environment settings
├── scripts/
│   ├── evaluate.py          # Reward curve evaluation
│   └── sample_outputs.py    # Anti-hacking output inspector
├── notebooks/
│   └── trace_colab.ipynb    # Colab-ready training notebook
├── docs/
│   └── blog_post.md         # HuggingFace mini-blog
├── requirements.txt
└── README.md

---

HuggingFace Deployment

Required Secrets

Set these in your HF Space settings → Repository secrets:

Secret Name	Source File	Description
GCP_CREDENTIALS_B64	credentials.json	Google Cloud OAuth client credentials
GMAIL_TOKEN_B64	token_gmail.pkl	Gmail API OAuth token (base64-encoded pickle)
SHEETS_TOKEN_B64	token_sheets.pkl	Sheets API OAuth token (base64-encoded pickle)
SHEETS_LEDGER_ID	.ledger_id	(Optional) Google Sheet ID for the financial ledger

Generate all base64 secrets at once:

python3 generate_secrets.py   # → creates hf_secrets.txt with all values

Live Dashboard

Visit /dashboard on your deployed Space to see a live financial transaction dashboard populated from Gmail. The endpoint:

1. Searches Gmail for financial emails (last 180 days)
2. Parses transactions (vendor, category, amounts)
3. Renders an interactive HTML dashboard

Results are cached for 10 minutes. Force refresh with /dashboard?refresh=true.

---

Judging Criteria Alignment

Criterion	Implementation
Environment Innovation (40%)	Federated multi-source retrieval + zero-knowledge SWM; novel schema-drift curriculum
Storytelling (30%)	Privacy narrative + before/after timeline demo
Showing Reward Improvement (20%)	Reward curves across 3 difficulty tiers; plan-quality scoring
Training Script Setup (10%)	OpenEnv + TRL GRPO + Unsloth Colab notebook