patchr 0.1.1

Patchr Protocol infrastructure for agentic orchestration and settlement.

Patchr

Patchr is an SDK and hosted API for running agent workflows that need source-bound search, claim preparation, customer-service handoff, human calls, and settlement coordination.

Use it when your app needs to turn a user request such as "find a mechanic in Lekki", "prepare a damage claim", or "dispute this ticket" into a routed workflow with auditable JSON results and streaming status messages.

Install

pip install patchr

export PATCHR_API_BASE_URL="https://api.patchr.co"
export PATCHR_API_TOKEN="your_patchr_api_token"

Quick Start

from patchr.sdk import PatchrClient

patchr = PatchrClient.fromEnv()

run = patchr.runOrchestrator({
    "clientId": "support_ops_demo",
    "channel": "sdk",
    "conversationId": "conv_damage_claim_001",
    "request": "My newly purchased TV was damaged in transit and the merchant has not followed up.",
    "attachments": [
        {
            "name": "damaged-tv-photo.jpg",
            "mime": "image/jpeg",
            "text": "Cracked TV panel and damaged transport packaging."
        }
    ],
})

print(run["status"])
print(run["route"])

Typical response shape:

{
  "ok": true,
  "status": "ready",
  "route": ["resolve", "bridge"],
  "results": {
    "resolve": {
      "claimDraft": {
        "summary": "Damaged goods claim with attachment evidence"
      }
    },
    "bridge": {
      "contactPlan": {
        "primary": { "type": "merchantSupport" }
      }
    }
  }
}

Streaming Status

Use streaming when the workflow may take more than a few seconds. Patchr sends human-readable progress events during quiet periods and handoff events when work moves into a human-facing step.

for event in patchr.streamOrchestrator({
    "clientId": "local_services_demo",
    "channel": "sdk",
    "conversationId": "conv_lekki_mechanic_001",
    "request": "Find me a mechanic in Lekki, Lagos",
    "country": "NG",
    "stream": True,
}):
    if event.get("type") in {"progress", "handoff"}:
        print(event["message"])
    if event.get("type") == "final":
        print(event["result"]["status"])

Example stream events:

{"type":"progress","status":"running","elapsedSec":10.0,"message":"I am still checking source-bound options and marketplace or map evidence."}
{"type":"handoff","phase":"proxy","name":"mission.callAvailability","status":"calling","message":"Contacting the mechanic for availability."}

Common Scenarios

Shopping:

patchr.runOrchestrator({
    "clientId": "storefront_demo",
    "channel": "sdk",
    "conversationId": "conv_shopping_001",
    "request": "Buy used iPhone 12 in Sweden under 350 dollar",
    "country": "SE"
})

Local service with proxy call handoff:

patchr.runOrchestrator({
    "clientId": "local_services_demo",
    "channel": "sdk",
    "conversationId": "conv_mechanic_001",
    "request": "Find me a mechanic in Lekki, Lagos",
    "country": "NG"
})

Ticket dispute:

patchr.runOrchestrator({
    "clientId": "support_ops_demo",
    "channel": "sdk",
    "conversationId": "conv_ticket_dispute_001",
    "request": "Dispute ticket ZD-44291: airline charged me twice after cancellation and closed the refund case."
})

Property lead discovery:

patchr.runOrchestrator({
    "clientId": "property_demo",
    "channel": "sdk",
    "conversationId": "conv_property_001",
    "request": "Find abandoned properties to sell around Partille, Goteborg",
    "country": "SE"
})

Useful Methods

patchr.health()
patchr.manifest()
patchr.protocolMap()
patchr.runOrchestrator(payload)
patchr.streamOrchestrator(payload)
patchr.resumeOrchestrator(conversation_id, item_id, action, payload)
patchr.mapTool(payload)
patchr.nlpTool(payload)

Runtime Notes

• Local-service searches such as mechanics, plumbers, clinics, and appointments route through map/place search and can trigger a PROXY handoff for availability calls.
• Long-running workflows emit user-facing progress text so your client does not appear stuck.
• Handoff events include plain messages such as "Contacting the mechanic for availability", "Calling the clinic to book your appointment", and "Preparing case documents".
• Set PATCHR_API_TOKEN for hosted API calls. Local test transports can run in-process without network I/O.

More

• Hosted API reference: https://patchr.co/api-reference
• Developer sandbox: https://patchr.co/sandbox
• Python package: https://pypi.org/project/patchr/
• Node package: https://www.npmjs.com/package/@patchr-core/sdk