Robotic Task Planner

Lightweight Python helper that uses an OpenAI chat model to turn a short task + environment description into a step-by-step plan for simple robotic tasks. The library is tiny (only depends on requests) and ships with a small CLI and an environment-grounding verifier pass.

Features

• Minimal footprint: plain requests, no heavy frameworks.
• Structured plans: consistent JSON schema that includes assumptions, constraints, steps, and fallbacks.
• CLI or Python API: call from the terminal or import into your own controller stack.
• Configurable: choose model, base URL (for proxies/Azure), temperature, and max steps.

Quickstart

1. Create and activate the conda env (runs an editable install via pip):

   cd task-plannerapi
   conda env create -f environment.yml
   conda activate robotic-task-planner

2. Set your API key:

   export OPENAI_API_KEY=sk-...

3. (Optional) If you already had a conda env and skipped step 1, install the package:

   pip install -e .

CLI usage

Generate a plan directly from the terminal:

robot-plan \
  --task "Sort red and blue blocks into bins" \
  --environment "Tabletop sorter with depth camera and 2-finger gripper" \
  --input "RGB-D camera feed" \
  --input "Force/torque at wrist" \
  --constraint "Avoid crushing force >10N" \
  --tool "perception stack" \
  --warning "Human may enter from left aisle" \
  --max-steps 8

Flags of note:

• --json prints the parsed plan as JSON (good for piping).
• --show-raw prints the raw model message if you want to debug prompting.
• --base-url lets you point to any OpenAI-compatible chat completions endpoint.
• --skip-verifier disables the grounding/verifier pass.
• --show-verifier-raw prints the raw verifier output.

Python API

from robotic_task_planner import PlanRequest, TaskPlanner, format_plan

planner = TaskPlanner(model="gpt-4o-mini")
request = PlanRequest(
    task="Move the spare battery from shelf A to the cart.",
    environment="Warehouse aisle, RGB camera, mobile base, 1.5kg payload limit.",
    inputs=["camera stream", "wheel odometry"],
    constraints=["Stay within marked aisle", "No dynamic obstacles in forbidden zone"],
    preferred_tools=["cart base", "camera"],
    safety_warnings=["Humans may cross from the right"],
    max_steps=10,
)
plan, raw, verification = planner.generate(request, verify=True)
print(format_plan(plan))
if verification and (verification.issues or verification.adjustments):
    print("Verifier notes:", verification.issues or verification.adjustments)

Plan schema (model output)

The model is asked to return JSON with this shape:

{
  "task": "...",
  "environment": "...",
  "assumptions": ["..."],
  "constraints": ["..."],
  "steps": [
    {
      "id": 1,
      "action": "Small, concrete action",
      "rationale": "Why this step",
      "inputs": ["camera feed", "state estimates"],
      "dependencies": [],
      "checks": ["what success looks like"],
      "risks": ["possible failures"],
      "tools": ["skills or tools used"],
      "expected_result": "observable outcome",
      "notes": "optional"
    }
  ],
  "fallbacks": ["reset or safe fallback"],
  "metrics": ["how to measure success"],
  "notes": "extra operator reminders"
}

Example script

examples/demo.py shows a minimal end-to-end call. Run it after setting OPENAI_API_KEY:

python examples/demo.py

Customization ideas

• Tweak the system prompt in robotic_task_planner/planner.py to match your hardware semantics.
• Swap base_url to point at an OpenAI-compatible proxy or Azure endpoint.
• Parse/validate the returned JSON against your own schema before dispatching to a controller.