Metadata-Version: 2.5
Name: langchain-oneshot
Version: 0.24.0
Summary: LangChain tools for OneShot — 54 tools for AI agents
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: oneshot-python>=0.48.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# langchain-oneshot

Your LangChain agent can think. This lets it act: send email, make calls,
research, buy, build sites. 54 tools plus the lookup tools, each a LangChain
`BaseTool`. It pays per action and spends nothing you did not allow.

## Install

```bash
pip install langchain-oneshot
```

## Start

```python
from langchain_oneshot import OneShotToolkit
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

toolkit = OneShotToolkit.from_private_key("0x...")
agent = create_react_agent(ChatOpenAI(model="gpt-4o"), toolkit.get_tools())

agent.invoke({"messages": [("user", "Research the latest AI agent frameworks")]})
```

`get_tools()` returns every tool on one client. One tool alone:

```python
from langchain_oneshot import OneShotClient, ResearchTool

ResearchTool(client=OneShotClient(private_key="0x...")).invoke({"topic": "AI agents"})
```

## Access tokens

For code that must not hold the key: a hosted runner, someone else's platform.

```python
import os
from langchain_oneshot import OneShotToolkit

toolkit = OneShotToolkit.from_access_token(os.environ["ONESHOT_ACCESS_TOKEN"])

# Already inside an event loop:
toolkit = await OneShotToolkit.afrom_access_token(os.environ["ONESHOT_ACCESS_TOKEN"])
```

- A token spends prepaid credits only. It never signs a payment.
- Short of credits, it raises `InsufficientCreditsError`. Top up from a wallet
  session with `OneShotClient.top_up_credits(amount)`.
- A token reads budgets but cannot change them, and cannot manage tokens.
  [Hosted setup](https://docs.oneshotagent.com/sdk/remote-mcp).

## What it does

| Area | Tools (`oneshot_` prefix) |
|------|---------------------------|
| [Talk](https://docs.oneshotagent.com/api-reference/email/send) | `email` `voice` `sms` `inbox_list` `inbox_get` `sms_inbox_list` `sms_inbox_get` `notifications` `mark_notification_read` |
| [Send from your domains](https://docs.oneshotagent.com/api-reference/email/domains) | `list_domains` `pause_domain` `resume_domain` |
| [Find people](https://docs.oneshotagent.com/api-reference/research/person-find) | `person_find` `person_profile` `person_email` `person_email_status` `person_dossier` `person_social_accounts` `person_articles` `person_posts` `person_interests` `person_followers` |
| [Think](https://docs.oneshotagent.com/api-reference/research) | `research` [`solve`](https://docs.oneshotagent.com/api-reference/solve) [`predict`](https://docs.oneshotagent.com/api-reference/predict) |
| [Web and buying](https://docs.oneshotagent.com/api-reference/web-search) | `web_search` `web_read` `product_find` `commerce_buy` |
| [Physical mail](https://docs.oneshotagent.com/api-reference/physical-mail/overview) | `physical_mail_upload` `physical_mail_preview` `physical_mail_approve` `physical_mail_send` |
| [Connected systems](https://docs.oneshotagent.com/api-reference/connections/overview) | `connections_list`, then `ledger_*` `crm_*` `tax_*` `shipping_*` `procurement_*` |
| [Browser](https://docs.oneshotagent.com/api-reference/browser/create) | `browser` `browser_create_profile` `browser_list_profiles` `browser_delete_profile` |
| [LinkedIn](https://docs.oneshotagent.com/api-reference/linkedin/overview) | `linkedin_connect` `linkedin_accounts` `linkedin_sync` `linkedin_conversations` `linkedin_messages` `linkedin_reply` `linkedin_message` `linkedin_invite` `linkedin_withdraw_invitation` `linkedin_invitation` `linkedin_invitations` `linkedin_view_profile` `linkedin_react` |
| [Build](https://docs.oneshotagent.com/api-reference/build/create) | `build` `update_build` |
| [Money](https://docs.oneshotagent.com/api-reference/budgets/overview) | `get_balance` `budget_status` |
| Lookup | One tool per entry in the lookup manifest, built for you |

## Money

Paid tools pay in USDC on Base mainnet, signed on your machine. A call costs
what the quote says, or it does not run. Fund the wallet first. The money rules
live in the [core client](https://pypi.org/project/oneshot-python/).

**Spend budget.** Pass `budgets={"daily": 50, "per_transaction": 5}` to
`from_private_key`. The server enforces it and raises `BudgetExceededError` past
the cap. The agent reads it with `oneshot_budget_status`; it cannot change it.

## Tool notes

- **Phone lookup** is off by default. `include_phone=True` on `oneshot_person_find`,
  `oneshot_person_profile` or `oneshot_person_dossier` is charged for each person
  you ask for, found or not; a failed job is refunded.
- **Physical mail.** Look at the proof and the price, then approve the quote
  yourself (`oneshot_physical_mail_preview`, `oneshot_physical_mail_approve`).
  Nothing approves it for you. Persist the idempotency key before
  `oneshot_physical_mail_send`.

## LinkedIn recovery

- No active account, or one that is `connection_deleted` or `revoked`: the human
  uses `oneshot_linkedin_connect` and grants access again.
- `reconnect_required`: the owning application reconnects the account.
  Reconnect and revoke are deliberately not agent tools.
- Never open a new connection on its own after an auth failure or a timeout.

## Requirements

Python 3.10 or later. `pip` brings `langchain-core`, `oneshot-python` and `pydantic`.

## Links

- [Documentation](https://docs.oneshotagent.com/sdk/langchain)
- [oneshot-python](https://pypi.org/project/oneshot-python/): the core client underneath
- [TypeScript SDK](https://www.npmjs.com/package/@oneshot-agent/sdk)
- [MCP Server](https://www.npmjs.com/package/@oneshot-agent/mcp-server)
- [Pricing](https://docs.oneshotagent.com/pricing)
- [GitHub](https://github.com/oneshot-agent/sdk)

## Discover tools

The toolkit exposes `oneshot_discover_tools` for free public tool search. Optional
`query`, `category` and `cursor` arguments mirror `OneShotClient.discover_tools`.
With no arguments it lists category counts; searches return public MCP names,
purposes and required inputs, filtered by the caller's grants.

## License

MIT
