Metadata-Version: 2.4
Name: pinelabs-agent-toolkit
Version: 0.1.1
Summary: Pine Labs Agent Toolkit — Pine Labs payment APIs as tools for AI agent frameworks (OpenAI, LangChain, Pydantic AI, CrewAI, Anthropic Claude).
Project-URL: Homepage, https://github.com/plural-pinelabs/Pinelabs-Agentic-SDK
Project-URL: Repository, https://github.com/plural-pinelabs/Pinelabs-Agentic-SDK
Project-URL: Documentation, https://docs.pluralonline.com/docs/agentic-sdks-python
Project-URL: Bug Tracker, https://github.com/plural-pinelabs/Pinelabs-Agentic-SDK/issues
Author: Pine Labs
License: MIT
License-File: LICENSE
Keywords: agents,ai,anthropic,claude,crewai,langchain,llm,openai,payments,pinelabs,plural,pydantic-ai,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: pinelabs-python>=0.1.1
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: anthropic>=0.30; extra == 'all'
Requires-Dist: crewai>=0.30; extra == 'all'
Requires-Dist: langchain-core>=0.3; extra == 'all'
Requires-Dist: openai-agents>=0.1; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: pydantic-ai>=0.0.13; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == 'anthropic'
Provides-Extra: crewai
Requires-Dist: crewai>=0.30; extra == 'crewai'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Provides-Extra: openai
Requires-Dist: openai-agents>=0.1; extra == 'openai'
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai>=0.0.13; extra == 'pydantic-ai'
Description-Content-Type: text/markdown

# pinelabs-agent-toolkit (Python)

[![PyPI](https://img.shields.io/pypi/v/pinelabs-agent-toolkit.svg)](https://pypi.org/project/pinelabs-agent-toolkit/)
[![Python](https://img.shields.io/pypi/pyversions/pinelabs-agent-toolkit.svg)](https://pypi.org/project/pinelabs-agent-toolkit/)
[![License](https://img.shields.io/pypi/l/pinelabs-agent-toolkit.svg)](#license)

Pine Labs payment APIs as **tools for AI agent frameworks** — OpenAI (Chat Completions + Agents SDK), LangChain, Pydantic AI, CrewAI, and Anthropic Claude. Built on top of [`pinelabs-python`](https://pypi.org/project/pinelabs-python/).

74 Pine Labs operations (orders, refunds, payouts, payment links, settlements, subscriptions, …) become typed, schema-validated tools your agent can call.

The npm equivalent is [`pinelabs-agent-toolkit`](https://www.npmjs.com/package/pinelabs-agent-toolkit). Both packages are generated from the same OpenAPI spec and use the same operation names.

## Install

```bash
pip install pinelabs-agent-toolkit
```

Then install only the framework adapter(s) you need:

| Framework | Extra | Peer dependency |
| --- | --- | --- |
| OpenAI Chat Completions + Agents SDK | `[openai]` | `openai`, `openai-agents` |
| LangChain | `[langchain]` | `langchain-core` |
| Pydantic AI | `[pydantic-ai]` | `pydantic-ai` |
| CrewAI | `[crewai]` | `crewai` |
| Anthropic Messages API | `[anthropic]` | `anthropic` |
| Everything | `[all]` | all of the above |

```bash
pip install 'pinelabs-agent-toolkit[openai,langchain]'
```

Requires **Python ≥ 3.9**.

## Authenticate

The toolkit takes your Pine Labs OAuth credentials and handles `client_credentials` token refresh automatically (with a thread-safe cache and a separate bootstrap auth client so the supplier callback can never recurse):

```python
from pinelabs_agent_toolkit.shared import pinelabs_environment

opts = dict(
    environment=pinelabs_environment["UAT"],  # or pinelabs_environment["PROD"]
    client_id="<client-id>",
    client_secret="<client-secret>",
)
```

| Constant | Base URL |
| --- | --- |
| `pinelabs_environment["UAT"]` | `https://pluraluat.v2.pinepg.in` |
| `pinelabs_environment["PROD"]` | `https://api.pluralpay.in` |

Or pass any URL string directly to `environment`.

> **Never** commit your `client_id` / `client_secret`. Load them from environment variables or a secret manager.

## Quickstart by framework

### OpenAI Chat Completions

```python
import json
import openai
from pinelabs_agent_toolkit.openai import PinelabsAgentToolkit
from pinelabs_agent_toolkit.shared import pinelabs_environment

toolkit = PinelabsAgentToolkit(
    environment=pinelabs_environment["UAT"],
    client_id="<client-id>",
    client_secret="<client-secret>",
)

client = openai.OpenAI()
messages = [{"role": "user", "content": "Create a 500 INR order with reference ord-1."}]

while True:
    resp = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=toolkit.get_tools(),
    )
    msg = resp.choices[0].message
    messages.append(msg)
    if not msg.tool_calls:
        break
    for call in msg.tool_calls:
        out = toolkit.handle_tool_call(call.function.name, call.function.arguments)
        messages.append({"role": "tool", "tool_call_id": call.id, "content": out})
```

### OpenAI Agents SDK

```python
from agents import Agent, Runner
from pinelabs_agent_toolkit.openai import PinelabsAgentToolkit

toolkit = PinelabsAgentToolkit(
    environment="https://pluraluat.v2.pinepg.in",
    client_id="<client-id>",
    client_secret="<client-secret>",
)

agent = Agent(
    name="Payments Agent",
    instructions="Help the user manage Pine Labs payments.",
    model="gpt-4o",
    tools=toolkit.get_agent_tools(),
)
result = Runner.run_sync(agent, "Create a 500 INR order for ord-1.")
print(result.final_output)
```

### LangChain

```python
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from pinelabs_agent_toolkit.langchain import PinelabsAgentToolkit

toolkit = PinelabsAgentToolkit(
    environment="https://pluraluat.v2.pinepg.in",
    client_id="<client-id>",
    client_secret="<client-secret>",
)

llm = ChatOpenAI(model="gpt-4o")
agent = create_react_agent(llm, toolkit.get_tools())
result = agent.invoke({"messages": [("user", "Create a 500 INR order.")]})
```

### Pydantic AI

```python
from pydantic_ai import Agent
from pinelabs_agent_toolkit.pydantic_ai import PinelabsAgentToolkit

toolkit = PinelabsAgentToolkit(
    environment="https://pluraluat.v2.pinepg.in",
    client_id="<client-id>",
    client_secret="<client-secret>",
)

agent = Agent("openai:gpt-4o", tools=toolkit.get_tools())
result = agent.run_sync("Create a 500 INR order with reference ord-1.")
print(result.output)
```

### CrewAI

```python
from crewai import Agent, Crew, Task
from pinelabs_agent_toolkit.crewai import PinelabsAgentToolkit

toolkit = PinelabsAgentToolkit(
    environment="https://pluraluat.v2.pinepg.in",
    client_id="<client-id>",
    client_secret="<client-secret>",
)

payments = Agent(
    role="Payments Specialist",
    goal="Manage Pine Labs payment links and orders.",
    backstory="You are an expert at the Pine Labs payment APIs.",
    tools=toolkit.get_tools(),
)

task = Task(
    description="Create a payment link for 500 INR.",
    expected_output="The payment link URL.",
    agent=payments,
)
Crew(agents=[payments], tasks=[task]).kickoff()
```

### Anthropic Claude (Messages API)

```python
import anthropic
from pinelabs_agent_toolkit.anthropic import PinelabsAgentToolkit

toolkit = PinelabsAgentToolkit(
    environment="https://pluraluat.v2.pinepg.in",
    client_id="<client-id>",
    client_secret="<client-secret>",
)

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Create a 500 INR order."}]

while True:
    resp = client.messages.create(
        model="claude-3-5-sonnet-latest",
        max_tokens=1024,
        tools=toolkit.get_tools(),
        messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})
    tool_uses = [b for b in resp.content if b.type == "tool_use"]
    if not tool_uses:
        break
    results = [
        {
            "type": "tool_result",
            "tool_use_id": b.id,
            "content": toolkit.handle_tool_use(b.name, b.input),
        }
        for b in tool_uses
    ]
    messages.append({"role": "user", "content": results})
```

## Available tools

The toolkit exposes **74 operations** spanning every Pine Labs Online product:

* **Authentication** — generate access tokens
* **Orders** — create, capture, fetch, cancel
* **Refunds** — create, fetch
* **Payment Links** — create, fetch, cancel, resend, list
* **Card / UPI / NetBanking / Wallet** — direct payment methods
* **Apple Pay / International Payments** — alternate rails
* **Pay by Points / E-Challans / Affordability Suite / BNPL / Convenience Fee**
* **Customers / Tokenization** — vault and customer management
* **Payouts** — create, update, cancel, list
* **Settlements / Split Settlements** — settlement search and reconciliation
* **Subscriptions** — plans, subscriptions, presentations, debits, retries

Inspect the full list:

```python
from pinelabs_agent_toolkit import ALL_TOOLS

for td in ALL_TOOLS:
    print(td.name, td.method, td.path)
```

Each tool's input schema is a strict pydantic model — extra fields raise a validation error so the LLM cannot smuggle arbitrary data into the SDK.

## Direct SDK access

The toolkit's `Pinelabs` client is a drop-in replacement for `pinelabs.PinelabsApi` with token refresh built in. Use it directly when you want to call the SDK outside an agent loop:

```python
from pinelabs_agent_toolkit.shared import Pinelabs

client = Pinelabs(
    environment="https://pluraluat.v2.pinepg.in",
    client_id="<client-id>",
    client_secret="<client-secret>",
)
client.orders.get_order_by_id(order_id="ord_123")
```

## Environments

| Environment | Base URL |
| --- | --- |
| UAT | `https://pluraluat.v2.pinepg.in` |
| Production | `https://api.pluralpay.in` |

## Versioning

Pre-1.0; expect occasional small breaking changes between minor versions. Operation names and signatures stay in lock-step with the [npm `pinelabs-agent-toolkit`](https://www.npmjs.com/package/pinelabs-agent-toolkit).

## License

MIT
