Metadata-Version: 2.4
Name: patchr
Version: 0.1.1
Summary: Patchr Protocol infrastructure for agentic orchestration and settlement.
Author: Patchr Core Team
License-Expression: Apache-2.0
Project-URL: Homepage, https://patchr.co
Project-URL: Documentation, https://patchr.co/api-reference
Project-URL: Sandbox, https://patchr.co/sandbox
Project-URL: Source, https://github.com/orepos/Patchr
Keywords: patchr,sdk,mcp,a2a,workflow,agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: api
Requires-Dist: fastapi>=0.111; extra == "api"
Requires-Dist: uvicorn>=0.30; extra == "api"
Provides-Extra: worker
Requires-Dist: redis>=5.0; extra == "worker"
Requires-Dist: rq>=1.16; extra == "worker"
Provides-Extra: db
Requires-Dist: psycopg[binary]>=3.2; extra == "db"
Requires-Dist: psycopg_pool>=3.2; extra == "db"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install patchr
```

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

## Quick Start

```python
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:

```json
{
  "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.

```python
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:

```json
{"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:

```python
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:

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

Ticket dispute:

```python
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:

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

## Useful Methods

```python
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
