Agent Documentation Index

Agent Registry

Agent ID	Module	Type	Phase
manager	app/agents/manager.py	Hybrid (LLM + deterministic)	P6
product_intake	app/agents/product_intake.py	Hybrid	P1
product_enrichment	app/agents/product_enrichment.py	LLM	P1
reference_intelligence	app/agents/reference_intelligence.py	LLM	P1
scriptwriter	app/agents/scriptwriter.py	LLM	P1
caption_seo	app/agents/caption_seo.py	LLM	P1
orchestrator	app/agents/orchestrator.py	Deterministic	P1

---

Supporting Modules (Phase 2–5)

Module	Path	Purpose	Phase
Copy Writer	app/content_generation/copy_writer.py	Generate ad copy with disclosure	P5
Image Gen	app/content_generation/image_gen.py	Generate product images via AI	P5
Video Gen	app/content_generation/video_gen.py	Generate video storyboards/clips	P5
Calendar Planner	app/content_generation/calendar_planner.py	Growth calendar + scheduling	P4
Trend Hooks	app/content_generation/trend_hooks.py	Trending hooks + viral patterns	P4
SEO Auditor	app/analyzers/seo_auditor.py	SEO scoring + keyword analysis	P4
Performance Learner	app/analytics/performance_learner.py	Learn from past metrics	P5
Chat Engine	app/analytics/chat_engine.py	AI chat for analytics queries	P5
Approval Gate	app/approval/__init__.py	Human-in-the-loop with audit	P5
Publisher	app/publishers/__init__.py	Multi-platform publish + dedup	P5
Token Vault	app/publishers/token_vault.py	AES-256 OAuth token storage	P6
Scheduler	app/scheduling/__init__.py	Post scheduling engine	P5
LLM Client	app/services/llm_client.py	OpenAI wrapper + dry-run mode	P6
Script Templates	app/agents/script_templates.py	Extracted script angle templates	P6
Rights Checks	app/services/rights_checks.py	Per-type rights verification funcs	P6
Rights Data	app/services/rights_data.py	Trademark pattern registry	P6
Pipeline State	app/flows/pipeline_state.py	PipelineStatus enum + PipelineState model	P6
Pipeline Steps	app/flows/pipeline_steps.py	Heavy step method mixin	P6

---

Agent: product_intake

Attribute	Value
ID	product_intake
Module	app/agents/product_intake.py
Role	Ingest Amazon product data from API, CSV, or manual input
Inputs	source, asin, title, price, category, csv_data
Outputs	products (list of ProductRecord)
Tools	AmazonLookupTool (future)
Guardrails	ASIN format validation, no web scraping, audit logged
Fail Condition	Invalid ASIN → ValueError

---

Agent: product_enrichment

Attribute	Value
ID	product_enrichment
Module	app/agents/product_enrichment.py
Role	Enrich products with category taxonomy, persona, use cases
Inputs	product (ProductRecord dict)
Outputs	enriched_product (EnrichedProduct dict)
Guardrails	Input validation, output secret check
KPI	Persona relevance accuracy

---

Agent: reference_intelligence

Attribute	Value
ID	reference_intelligence
Module	app/agents/reference_intelligence.py
Role	Map products to culturally resonant references
Inputs	product_id, category, primary_persona, use_cases
Outputs	reference_bundle (ReferenceBundle dict)
Guardrails	Default to style_only, never suggest character likenesses without license
Fail Condition	No matches → returns safe fallback references

---

Agent: scriptwriter

Attribute	Value
ID	scriptwriter
Module	app/agents/scriptwriter.py
Role	Generate short-form video scripts
Inputs	brief, product_title, product_category, use_cases, reference_style
Outputs	script (Script dict with hook, scenes, CTA)
Angles	comparison, top_3, story, problem_solution, aesthetic, meme_style
Guardrails	No unverifiable claims, no fake testimonials, CTA includes {{AFFILIATE_DISCLOSURE}}

---

Agent: caption_seo

Attribute	Value
ID	caption_seo
Module	app/agents/caption_seo.py
Role	Generate platform-optimized captions with affiliate disclosure
Inputs	hook, value_prop, category, affiliate_link, target_platforms
Outputs	caption_bundle (CaptionBundle dict)
CRITICAL	Every caption MUST pass validate_disclosure()
Auto-fix	Missing disclosure → add_disclosure() applied automatically

---

Agent: orchestrator

Attribute	Value
ID	orchestrator
Module	app/agents/orchestrator.py
Role	Manage pipeline flow, route decisions, enforce retry limits
Inputs	action, compliance_status, qa_status
Outputs	next_step, should_continue, reason
Max Retries	3 rewrite loops before forced REJECT
Guardrails	Deterministic — no LLM involved in routing decisions

---

Agent: manager (Phase 6)

Attribute	Value
ID	manager
Module	app/agents/manager.py
Role	Supervises all worker agents; routes decisions; LLM quality review
Type	Hybrid — deterministic routing + LLM content review
Inputs	action (route_rights / route_qa / review_content / track_agent / get_status)
Outputs	next_step, should_continue, reason, quality_score
Max Retries	3 rewrite loops per scope before forced REJECT
LLM Usage	review_content action uses LLM to score quality (0–100) and check brand safety
Guardrails	All routing is deterministic; LLM only used for quality scoring

Actions

Action	Purpose	LLM?
route_rights	Route APPROVE/REWRITE/REJECT from rights check	No
route_qa	Route APPROVE/REWRITE/REJECT from QA check	No
review_content	Score content quality, check disclosure/brand safety	Yes
track_agent	Record agent run metrics (duration, failures)	No
get_status	Return supervision status + health metrics	No

---

Base Agent Contract

All agents extend BaseAgent which enforces:

1. Pre-execution: AgentConstitution.validate_input() on all string inputs
2. Post-execution: AgentConstitution.validate_no_secret_exposure() on all outputs
3. Audit logging: Start, complete, violation, and error events logged
4. Error handling: Exceptions caught, logged, and re-raised