Have You Met Ted

Ted is a friendly, professional AI agent that evaluates visual assets (images and videos) against brand guidelines to ensure compliance and stylistic alignment. Ted is powered by Hugging Face models and runs entirely without Google Cloud.

The evaluation methodology uses a rubric-based approach (inspired by Rubric-Based Evaluation for On-Brand Generative Media):

• DSG (Davidsonian Scene Graph) — checks prompt fidelity and general quality
• BAS (Brand Alignment Scorecard) — checks compliance with your brand guidelines

Architecture & Workflow

Ted uses a sequential Python pipeline (no external agent framework):

1. Ted (Planner) — understands your request, categorises uploaded files, confirms the plan
2. Ted Processor — extracts structured brand criteria from guideline documents (PDF, MD, TXT)
3. Ted Evaluator — evaluates each visual asset against the extracted criteria using a vision LLM
4. Ted Summariser — aggregates scores and presents a final brand-alignment report

Tech stack:

• LLM / Vision: Hugging Face Inference API — meta-llama/Llama-3.2-11B-Vision-Instruct by default
• Web UI: Gradio
• Storage: Local filesystem (~/.ted/)
• No Google Cloud account required

Getting Started

1. Prerequisites

• Python 3.13+
• uv package manager
• A Hugging Face account with an access token

2. Configure environment

cp .env.template .env

Open .env and set your Hugging Face token:

HF_TOKEN="hf_your_token_here"

Get a token at huggingface.co/settings/tokens. The free tier is sufficient for meta-llama/Llama-3.2-11B-Vision-Instruct.

3. Install dependencies

uv sync

4. Run Ted

uv run python -m ted.app

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

5. Using Ted

1. Upload your brand guideline files (PDF, Markdown, or text) using the file panel
2. Upload your visual assets (PNG, JPG, MP4, etc.)
3. Type "proceed" (or any evaluation-related message) to start
4. Ted will process your guidelines, evaluate each asset, and deliver a full report

Running Tests

uv run pytest -v

Unit tests use mocks and do not require an HF token. Integration tests mock the HF API by default.

Configuration Reference

All configuration lives in .env:

Variable	Default	Description
HF_TOKEN	(required)	Your Hugging Face access token
MODEL_NAME	meta-llama/Llama-3.2-11B-Vision-Instruct	Vision model for all LLM calls
TED_STORAGE_DIR	~/.ted	Local directory for session files and reports

File Support

Type	Extensions	Used as
Brand guidelines	.pdf, .md, .txt	Extracted for evaluation criteria
Visual assets (images)	.png, .jpg, .jpeg, .gif, .webp	Evaluated visually against criteria
Visual assets (video)	.mp4, .mov, .avi	Evaluated via rubric (frame extraction not required)

Project Structure

ted/
├── agent.py      — Async pipeline orchestration (Ted's "brain")
├── app.py        — Gradio web interface
├── services.py   — HF InferenceClient: guideline extraction + vision evaluation
├── tools.py      — Local filesystem operations + formatting helpers
├── models.py     — Pydantic data models (framework-agnostic)
├── utils.py      — Radar chart generation, progress bar
└── auth.py       — HF token helper