Accept instruction and schema positionally in Python observe and extract

[miguelg719]

Summary

• move instruction (and schema) ahead of the bare * in Stagehand.observe and Stagehand.extract, matching act and the TypeScript and Go SDKs
• update the 61 Python call sites in the examples, README, and v4 docs to the positional form
• correct the AI-rules line that told assistants observe and extract take keyword-only arguments
• add a signature test so act/observe/extract cannot drift back to keyword-only

Backward compatible: callers already passing these as keywords are unaffected.

Validation

• ruff format --check, ruff check, ty check
• pytest (211 passed)
• vitest run rules/ast-grep packages/docs/tests (42 passed)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7daa322

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

No issues found across 16 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Caller as Python SDK Caller
    participant Stagehand as Stagehand Class
    participant Test as Signature Test (pytest)

    Note over Caller,Stagehand: NEW: Positional calling convention

    Caller->>Stagehand: observe("Find the button")  NEW: positional instruction
    Stagehand->>Stagehand: process observe
    Stagehand-->>Caller: ObserveResult

    Caller->>Stagehand: extract("Get title", PageInfo)  NEW: pos instruction+schema
    Stagehand->>Stagehand: execute extraction
    Stagehand-->>Caller: ExtractResult

    alt Keyword‑only (unchanged)
        Caller->>Stagehand: observe(instruction="...", selector="...")
    end

    Note over Test: Enforces POSITIONAL_OR_KEYWORD before *

    Test->>Stagehand: inspect.signature(observe)
    Test-->>Test: assert 1st param is positional (instruction)
    Test->>Stagehand: inspect.signature(extract)
    Test-->>Test: assert 1st & 2nd params are positional (instruction, schema)
    Test->>Stagehand: inspect.signature(act)
    Test-->>Test: assert first param is positional (instruction)

    Note over Test: All remaining params must be KEYWORD_ONLY

Loading

_{Re-trigger cubic}