openapi.json

{"openapi":"3.1.0","info":{"title":"MetaContentModerationEnv","description":"OpenEnv environment for AI content moderation — Meta-inspired","version":"0.1.0"},"paths":{"/health":{"get":{"summary":"Health","description":"Health check — required for HF Spaces ping.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Health Get"}}}}}}},"/tasks":{"get":{"summary":"List Tasks","description":"List all available task names.","operationId":"list_tasks_tasks_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response List Tasks Tasks Get"}}}}}}},"/reset":{"post":{"summary":"Reset","description":"Reset the environment to a new episode.\nReturns the first observation.","operationId":"reset_reset_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerationObservation"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/step":{"post":{"summary":"Step","description":"Submit a moderation decision and advance the episode.\nReturns next observation, reward, done flag, and reward breakdown.","operationId":"step_step_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerationDecision"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/state":{"get":{"summary":"State","description":"Return current environment state snapshot.","operationId":"state_state_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerationState"}}}}}}},"/openenv.yaml":{"get":{"summary":"Serve Openenv Yaml","description":"Serve the openenv.yaml metadata file.","operationId":"serve_openenv_yaml_openenv_yaml_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"ContentItem":{"properties":{"content_id":{"type":"string","title":"Content Id","description":"Unique content identifier"},"content_type":{"$ref":"#/components/schemas/ContentType"},"text":{"type":"string","title":"Text","description":"Raw content text or image description"},"author_region":{"type":"string","title":"Author Region","description":"ISO 3166-1 alpha-2 country code","default":"US"},"author_history":{"items":{"type":"string"},"type":"array","title":"Author History","description":"Prior violation categories for this author"},"context":{"additionalProperties":true,"type":"object","title":"Context","description":"Additional context: thread_id, reply_to, ad_targeting etc."},"language":{"type":"string","title":"Language","description":"ISO 639-1 language code","default":"en"},"media_urls":{"items":{"type":"string"},"type":"array","title":"Media Urls","description":"List of direct URLs to associated media (e.g. JPG, PNG)"},"media_types":{"items":{"type":"string"},"type":"array","title":"Media Types","description":"Corresponding media types (e.g. 'image', 'video')"}},"type":"object","required":["content_id","content_type","text"],"title":"ContentItem","description":"A single piece of content to be moderated."},"ContentType":{"type":"string","enum":["text_post","image_description","ad_copy","whatsapp_message"],"title":"ContentType","description":"Type of content being moderated."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ModerationAction":{"type":"string","enum":["approve","remove","escalate","restrict","request_review"],"title":"ModerationAction","description":"Actions the agent can take on content."},"ModerationDecision":{"properties":{"content_id":{"type":"string","title":"Content Id","description":"Must match the observed content_item.content_id"},"labels":{"items":{"$ref":"#/components/schemas/ViolationCategory"},"type":"array","minItems":1,"title":"Labels","description":"One or more violation categories. Use [CLEAN] if no violation."},"action":{"$ref":"#/components/schemas/ModerationAction","description":"Enforcement action to take"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"Agent confidence in this decision (0.0–1.0)"},"reasoning":{"type":"string","title":"Reasoning","description":"Optional free-text reasoning (used in hard task grader)","default":""},"policy_citations":{"items":{"type":"string"},"type":"array","title":"Policy Citations","description":"Policy rule IDs cited for this decision"}},"type":"object","required":["content_id","labels","action","confidence"],"title":"ModerationDecision","description":"The agent's moderation decision for a single content item.\nThis is what the agent submits via step()."},"ModerationObservation":{"properties":{"step":{"type":"integer","minimum":0.0,"title":"Step","description":"Current step index"},"content_item":{"$ref":"#/components/schemas/ContentItem"},"policy_excerpt":{"type":"string","title":"Policy Excerpt","description":"Relevant policy text snippet for this content type","default":""},"thread_history":{"items":{"$ref":"#/components/schemas/ContentItem"},"type":"array","title":"Thread History","description":"Prior messages in thread (for thread tasks only)"},"conflicting_policies":{"items":{"type":"string"},"type":"array","title":"Conflicting Policies","description":"Names of policies that may conflict for this item (hard task)"},"task_name":{"type":"string","title":"Task Name","description":"Active task identifier"},"instructions":{"type":"string","title":"Instructions","description":"Natural language task instructions for the agent"}},"type":"object","required":["step","content_item","task_name","instructions"],"title":"ModerationObservation","description":"What the agent sees at each step.\nContains the content item to moderate plus any policy references."},"ModerationReward":{"properties":{"total":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Total","description":"Composite reward for this step"},"label_precision":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Label Precision","default":0.0},"label_recall":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Label Recall","default":0.0},"action_correct":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Action Correct","default":0.0},"policy_citation_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Policy Citation Score","default":0.0},"false_positive_penalty":{"type":"number","maximum":0.0,"title":"False Positive Penalty","description":"Negative if clean content flagged","default":0.0},"reasoning_quality":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Reasoning Quality","description":"Hard task only","default":0.0},"breakdown":{"additionalProperties":{"type":"number"},"type":"object","title":"Breakdown","description":"Raw component scores for debugging"}},"type":"object","required":["total"],"title":"ModerationReward","description":"Structured reward breakdown for one step.\nProvides partial credit signals at every step."},"ModerationState":{"properties":{"task_name":{"type":"string","title":"Task Name"},"episode_id":{"type":"string","title":"Episode Id"},"current_step":{"type":"integer","title":"Current Step"},"max_steps":{"type":"integer","title":"Max Steps"},"done":{"type":"boolean","title":"Done"},"cumulative_reward":{"type":"number","title":"Cumulative Reward"},"items_seen":{"type":"integer","title":"Items Seen"},"items_remaining":{"type":"integer","title":"Items Remaining"},"decisions_log":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Decisions Log"},"score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Score","default":0.0}},"type":"object","required":["task_name","episode_id","current_step","max_steps","done","cumulative_reward","items_seen","items_remaining"],"title":"ModerationState","description":"Full internal state of the environment.\nReturned by state() endpoint."},"ResetRequest":{"properties":{"task":{"type":"string","title":"Task","description":"Task name to run","default":"single-label-classify"},"seed":{"type":"integer","title":"Seed","description":"Random seed for reproducibility","default":42}},"type":"object","title":"ResetRequest"},"StepResult":{"properties":{"observation":{"$ref":"#/components/schemas/ModerationObservation"},"reward":{"type":"number","title":"Reward"},"reward_breakdown":{"$ref":"#/components/schemas/ModerationReward"},"done":{"type":"boolean","title":"Done"},"info":{"additionalProperties":true,"type":"object","title":"Info"}},"type":"object","required":["observation","reward","reward_breakdown","done"],"title":"StepResult","description":"Return type of env.step() — mirrors OpenEnv spec."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ViolationCategory":{"type":"string","enum":["hate_speech","violence","nudity","spam","misinformation","harassment","self_harm","terrorism","scam","clean"],"title":"ViolationCategory","description":"All possible content violation categories."}}}}