API Reference¶

Complete reference for the BotManifold Python SDK.

BotManifoldClient¶

The main client class for interacting with BotManifold.

Constructor¶

BotManifoldClient(
    api_url: str = "https://botmanifold.com/api",
    timeout: int = 30
)

Parameter	Type	Default	Description
`api_url`	str	`"https://botmanifold.com/api"`	Base URL for the API
`timeout`	int	`30`	Request timeout in seconds

Methods¶

submit()¶

Submit a policy for evaluation.

submit(
    policy_path: str,
    scenario: str,
) -> Submission

Parameter	Type	Description
`policy_path`	str	Path to policy zip file
`scenario`	str	Scenario ID (e.g., `"messy_room_v1"`)

Returns: Submission object

Example:

submission = client.submit(
    policy_path="my_policy.zip",
    scenario="messy_room_v1"
)

get_submission()¶

Get the status of a submission.

get_submission(submission_id: str) -> Submission

Parameter	Type	Description
`submission_id`	str	UUID of the submission

Returns: Submission object with current status

Example:

status = client.get_submission("abc123-def456-...")
print(status.status)  # "COMPLETED"
print(status.verdict)  # "PASS"

list_submissions()¶

List all submissions.

list_submissions(
    scenario: str = None,
    limit: int = 20,
    offset: int = 0
) -> List[Submission]

Parameter	Type	Default	Description
`scenario`	str	`None`	Filter by scenario ID
`limit`	int	`20`	Max results to return
`offset`	int	`0`	Pagination offset

Returns: List of Submission objects

get_scenarios()¶

List available scenarios.

get_scenarios() -> List[Scenario]

Returns: List of Scenario objects

Example:

scenarios = client.get_scenarios()
for s in scenarios:
    print(f"{s.id}: {s.name}")

download_video()¶

Download the result video for a submission.

download_video(
    submission_id: str,
    output_path: str
) -> None

Parameter	Type	Description
`submission_id`	str	UUID of the submission
`output_path`	str	Local path to save the video

Example:

client.download_video("abc123...", "result.mp4")

Data Classes¶

Submission¶

Represents a policy submission.

Attribute	Type	Description
`id`	str	Unique submission ID
`scenario_id`	str	Scenario this submission is for
`status`	str	Current status (see below)
`verdict`	str	Judge verdict (PASS/FAIL/PARTIAL)
`score`	float	Numerical score
`video_url`	str	URL to result video
`error`	str	Error message if failed
`created_at`	datetime	Submission timestamp

Status Values:

Status	Description
`PENDING`	Submission received, awaiting upload
`UPLOADED`	Policy uploaded, waiting for queue
`QUEUED`	In simulation queue
`RUNNING`	Simulation in progress
`JUDGING`	AI judge evaluating results
`COMPLETED`	Evaluation complete
`FAILED`	Error during processing

Scenario¶

Represents an evaluation scenario.

Attribute	Type	Description
`id`	str	Unique scenario ID
`name`	str	Display name
`description`	str	Short description
`difficulty`	str	easy/medium/hard
`time_limit_seconds`	int	Max episode duration
`max_score`	int	Maximum achievable score

Exceptions¶

BotManifoldError¶

Base exception for all SDK errors.

from botmanifold import BotManifoldError

try:
    client.submit(...)
except BotManifoldError as e:
    print(f"Error: {e}")

APIError¶

Raised when the API returns an error response.

Attribute	Type	Description
`status_code`	int	HTTP status code
`message`	str	Error message

ValidationError¶

Raised when input validation fails.

from botmanifold import ValidationError

try:
    client.submit(policy_path="nonexistent.zip", ...)
except ValidationError as e:
    print(f"Invalid input: {e}")

Environment Variables¶

Variable	Description	Default
`BOTMANIFOLD_API_URL`	Override API base URL	`https://botmanifold.com/api`
`BOTMANIFOLD_TIMEOUT`	Request timeout (seconds)	`30`

export BOTMANIFOLD_API_URL=https://staging.botmanifold.com/api