SANDRA - Safety Appeals & Network Dispute Review Agent

OSS-powered appeals copilot for UGC platforms.

Quick Start

1. Install Dependencies

npm install

2. Set Up Model API Access

SANDRA uses gpt-oss-safeguard (an open-source safeguard model) for content moderation appeals. Currently, the implementation supports a single model configuration.

Option A: HuggingFace Inference API

1. Create a HuggingFace account at https://huggingface.co/join

2. Get your API token:

   • Go to https://huggingface.co/settings/tokens
   • Click "Create new token"
   • Give it a name (e.g., "SANDRA")
   • Copy the token (starts with hf_...)

3. Request access to gpt-oss-safeguard:

   • Go to the gpt-oss-safeguard model page on HuggingFace
   • Click "Agree and access repository" if required
   • Access is usually granted instantly

4. Create your .env.local file in the root directory and add the following:

# Currently only SAFEGUARD_20B is configured in the codebase
SAFEGUARD_API_URL=https://api-inference.huggingface.co/models/YOUR_ORG/gpt-oss-safeguard-20b
SAFEGUARD_API_KEY=hf_YOUR_ACTUAL_TOKEN_HERE
SAFEGUARD_MODEL_NAME=gpt-oss-safeguard-20b

Note: Replace YOUR_ORG with the actual HuggingFace organization/model path for gpt-oss-safeguard. The current implementation uses a single model configuration. To add support for both 20B and 120B models, update lib/model.ts to support both SAFEGUARD_20B and SAFEGUARD_120B variants.

Option B: Together AI (Faster, Paid)

1. Sign up at https://www.together.ai/
2. Get your API key from https://api.together.xyz/settings/api-keys
3. Update .env.local:

SAFEGUARD_API_URL=https://api.together.xyz/v1/chat/completions
SAFEGUARD_API_KEY=your_together_api_key
SAFEGUARD_MODEL_NAME=gpt-oss-safeguard-20b

Option C: Other Providers

• Replicate: https://replicate.com/
• Self-hosted: Use vLLM or text-generation-inference
• OpenRouter: https://openrouter.ai/

3. Run the Development Server

npm run dev

Open http://localhost:3000 in your browser.

4. Build for Production

npm run build
npm run start

Note: Currently only SAFEGUARD_20B is configured using gpt-oss-safeguard. To use both 20B and 120B models, update lib/model.ts to support both variants.

Project Structure

sandra-app/
├── app/                    # Next.js app router
│   ├── page.tsx           # Main SPA with full UI
│   ├── layout.tsx         # Root layout
│   ├── api/               # API routes
│   │   └── sandra/
│   │       └── [appealId]/route.ts  # Appeal processing endpoint
│   └── ...
├── types/
│   └── sandra.ts          # TypeScript types
├── data/
│   ├── appeals.ts         # Seed appeals data
│   └── precedents.ts      # Precedent cases
├── lib/
│   ├── model.ts           # Model abstraction layer (gpt-oss-safeguard)
│   ├── prompts.ts         # Agent prompt templates (Harmony format)
│   └── agents/            # Analysis & Evaluator agents
│       ├── analysisAgent.ts
│       └── evaluatorAgent.ts
└── docs/                  # Documentation

Features

• Multi-agent pipeline: Analysis Agent + Evaluator Agent
• Three risk lanes: Green (auto-resolve), Yellow (2 explanations), Red (escalate to human)
• Precedent-aware: Uses past cases for consistency, but never mentions them to creators
• Full UI/UX: Complete appeal management interface with progress tracking, decision displays, and archive/withdraw functionality
• Real-time processing: Live appeal processing with model API integration

Development Phases

• Phase 0/1: Project setup + types
• Phase 1: Seed data (appeals + precedents)
• Phase 2: Model abstraction & env vars
• Phase 3: Agents with real model calls (Analysis Agent + Evaluator Agent)
• Phase 4: API route wiring (/api/sandra/[appealId])
• Phase 5: Frontend flow with full UI/UX
  • Appeal list and detail views
  • Progress timeline with visual indicators
  • Explanation forms with justification checkboxes
  • Decision displays with decision IDs
  • Archive/withdraw functionality
  • Status badges and icons
• Phase 6: Real model integration (gpt-oss-safeguard via HuggingFace/Together AI)

Current Status: Core functionality complete. Ready for testing and deployment.

Documentation

See the docs/ folder for detailed specifications:

• SANDRA_PRODUCT_VISION.md - Product overview
• SANDRA_CURSOR_ARCH_PROMPT.md - Technical architecture
• PROMPTS_SANDRA.md - Agent prompt specifications
• POLICY_SELF_HARM.md - Self-harm policy
• SANDRA_EXAMPLES.md - Example cases

CI/CD

GitHub Actions

The project includes a CI workflow (.github/workflows/ci.yml) that runs on every push and pull request:

• Lints code with ESLint
• Type checks with TypeScript
• Builds the application to verify it compiles

Automatic Vercel Deployment

The project uses Vercel's GitHub Integration for automatic deployments:

1. Go to your Vercel project dashboard
2. Navigate to Settings → Git
3. Connect your GitHub repository
4. Vercel will automatically deploy on every push to your main branch

Benefits:

• ✅ Automatic deployments on every push
• ✅ Preview deployments for pull requests
• ✅ No additional configuration needed
• ✅ Built-in rollback capabilities

License

MIT