Patchr - the infrastructure for autonomous agents that need contracts, evidence trails, and human-safe handoffs.
Project description
Patchr
Patchr - the infrastructure for autonomous agents that need contracts, evidence trails, and human-safe handoffs.
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"
Developer Activation
New developers can create a profile directly from the SDK and start testing immediately. Patchr returns a starter API token, sends an activation link to the email address, and keeps unactivated starter tokens limited to 5 workflow requests.
createProfile(email, name, password)returns a starter token.activateToken(activationToken)activates the token after the email link is opened or the activation token is supplied in local/debug mode.runOrchestrator(payload)runs the workflow with the activated token.
from patchr.sdk import PatchrClient
patchr = PatchrClient()
profile = patchr.createProfile(
email="dev@example.com",
name="Dev Example",
password="use-a-real-password",
)
token = profile["token"]
print(profile["activation"]["message"])
# In production, click the emailed activation link. Local/debug responses may
# include activationToken for automated tests.
activation_token = profile.get("activation", {}).get("activationToken")
if activation_token:
patchr.activateToken(activation_token)
patchr = PatchrClient(token=token)
run = patchr.runOrchestrator({
"clientId": "activation_smoke_test",
"channel": "sdk",
"request": "Buy me iPhone7 less than 500 dollar",
})
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"])
Fast Sandbox Smoke Test
Before wiring code, open the hosted sandbox and click the Hunt example:
The starter request is:
Buy me iPhone7 less than 500 dollar
The sandbox includes a small source-backed listing so a first Hunt run can return options quickly even when live marketplace pages are slow or blocked. For SDK smoke tests, you can do the same by passing a known source URL:
run = patchr.runOrchestrator({
"clientId": "sandbox_smoke_test",
"channel": "sdk",
"conversationId": "conv_iphone7_smoke_001",
"request": "Buy me iPhone7 less than 500 dollar",
"urls": [
"data:text/html,<html><title>Used iPhone7 listing</title><body>Used iPhone7 listing available in stock. List 600 dollar, sale 189.99 dollar with receipt and fast shipping.</body></html>"
],
"targetLimit": 1,
"allowNetwork": False
})
print(run["status"]) # usually NEEDS_INPUT when options are ready to choose
Remove urls and set allowNetwork to True when you want Patchr to search live marketplaces.
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 me iPhone7 less than 500 dollar"
})
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.createProfile(email, name, password)
patchr.activateToken(activation_token)
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_TOKENfor hosted API calls. Local test transports can run in-process without network I/O.
Changelog
0.1.4 adds SDK developer activation: createProfile, emailed activation links, activateToken, and a 5-request limit for unactivated starter tokens.
0.1.3 adds a fast sandbox smoke test for Hunt, the Buy me iPhone7 less than 500 dollar starter example, and first-class vendorDueDiligence workflow support.
See CHANGELOG.md in the package source for full release notes.
More
- Hosted API reference: https://patchr.co/api-reference
- Control plane: https://patchr.co/control-plane
- Developer sandbox: https://patchr.co/sandbox
- Python package: https://pypi.org/project/patchr/
- Node package: https://www.npmjs.com/package/@patchr-core/sdk
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file patchr-0.1.4.tar.gz.
File metadata
- Download URL: patchr-0.1.4.tar.gz
- Upload date:
- Size: 385.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7015a1015304ec5b27c8853ee4c921bec48b78141207a0595141f5ae573f2dc9
|
|
| MD5 |
011a563abd4bb5c31ad8503fc1525999
|
|
| BLAKE2b-256 |
3b47120d4b913fe2d2f067ea8ae0468bbf31efffedbdfec43538cb7e913732d2
|
File details
Details for the file patchr-0.1.4-py3-none-any.whl.
File metadata
- Download URL: patchr-0.1.4-py3-none-any.whl
- Upload date:
- Size: 330.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7b313adeb185aa2334bb0340e17e73e48d7cf8f7da52ae86927dfdfc8b559ab7
|
|
| MD5 |
8b171ebb4ac4f7f3e3406e34a909d4e5
|
|
| BLAKE2b-256 |
0ec7c3002b80d07609f3236d8ca9dd50533943a35e07c476770ef28fdfdfbf00
|
