Metadata-Version: 2.5
Name: game-plugin-oneshot
Version: 0.19.0
Summary: GAME SDK plugin for OneShot real-world AI agent tools — 51 tools
Project-URL: Homepage, https://oneshotagent.com
Project-URL: Repository, https://github.com/oneShotAgentSDK/game-plugin-oneshot
Project-URL: Documentation, https://docs.oneshotagent.com/sdk/overview
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: game-sdk>=0.1.5
Requires-Dist: oneshot-python>=0.42.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# game-plugin-oneshot

A GAME SDK plugin that gives Virtuals Protocol agents OneShot's 51 real-world tools plus additional tools from the lookup manifest: email, SMS, calls, research, enrichment, commerce, website builds. Paid tools charge USDC from your wallet on Base Mainnet, so fund it first.

## Install

```bash
pip install game-plugin-oneshot
```

## Quick Start

```python
import os
from game_sdk.game.agent import Agent
from game_plugin_oneshot import OneShotPlugin

plugin = OneShotPlugin(
    private_key=os.environ["WALLET_PRIVATE_KEY"],
)

agent = Agent(
    api_key=os.environ["GAME_API_KEY"],
    name="my-agent",
    agent_description="An agent that can interact with the real world",
)

agent.add_worker(plugin.get_worker())
agent.run()
```

## Access-token sessions

Hosted GAME agents that should not hold a wallet key use a delegated token instead:

```python
import os
from game_plugin_oneshot import OneShotPlugin

plugin = OneShotPlugin(access_token=os.environ["ONESHOT_ACCESS_TOKEN"])
# Inside an async application:
# plugin = await OneShotPlugin.acreate(access_token=os.environ["ONESHOT_ACCESS_TOKEN"])
```

Create the token and set budgets from a wallet session. Calls spend prepaid credits
within the stored caps. Tokens cannot manage tokens, raise budgets, or sign USDC
payments. Refill credits from a wallet session with
`OneShotClient.top_up_credits(amount)`. See the
[hosted setup guide](https://docs.oneshotagent.com/sdk/remote-mcp).

## Tools

The plugin exposes **51** OneShot tools plus additional `oneshot_<name>` functions from the lookup manifest. The lookup tools are read from the generated manifest in `oneshot-python` (`oneshot.lookup_tools()`), so a new lookup tool appears here without a plugin change. Core tools:

| Tool | Description | Paid? |
|------|-------------|-------|
| `oneshot_email` | Send emails to real recipients | paid |
| `oneshot_sms` | Send SMS text messages | paid |
| `oneshot_voice` | Make phone calls with an AI voice agent | paid |
| `oneshot_physical_mail_upload` | Upload print-ready artwork (base64 PDF, PNG or JPEG, 20 MB max) for a letter or postcard | free |
| `oneshot_physical_mail_send` | Print and post an approved mailpiece (quote id, approval id, an idempotency key you keep); preview, approve and the order reads are manifest tools | paid |
| `oneshot_research` | Deep research reports | paid |
| `oneshot_web_search` | Web search (fast, synchronous) | paid |
| `oneshot_web_read` | Read a web page as markdown | paid |
| `oneshot_person_find` | Search people by title/company/location | paid |
| `oneshot_person_profile` | Enrich a profile from LinkedIn/email/name | paid |
| `oneshot_person_email` | Find an email at a company | paid |
| `oneshot_person_email_status` | Verify email deliverability | paid |
| `oneshot_person_dossier` | A person’s profile, known social accounts, articles, posts and written summary | paid |
| `oneshot_person_social_accounts` | Find someone's social accounts | paid |
| `oneshot_person_articles` | Articles/interviews about a person | paid |
| `oneshot_person_posts` | Recent social posts for a person | paid |
| `oneshot_person_interests` | What a person cares about | paid |
| `oneshot_person_followers` | Followers/following/replies | paid |
| `oneshot_product_find` | Search for products | paid |
| `oneshot_commerce_buy` | Purchase products online | paid |
| `oneshot_build` | Generate and deploy a website | paid |
| `oneshot_update_build` | Update an existing website | paid |
| `oneshot_browser` | Browser automation task | paid |
| `oneshot_browser_create_profile` | Create a persistent browser profile | free |
| `oneshot_browser_list_profiles` | List browser profiles | free |
| `oneshot_browser_delete_profile` | Delete a browser profile | free |
| `oneshot_inbox_list` | List inbound emails | free |
| `oneshot_inbox_get` | Get an inbound email by ID | free |
| `oneshot_sms_inbox_list` | List inbound SMS | free |
| `oneshot_sms_inbox_get` | Get an inbound SMS by ID | free |
| `oneshot_notifications` | List agent notifications | free |
| `oneshot_mark_notification_read` | Mark a notification as read | free |
| `oneshot_get_balance` | Get USDC + credits balance | free |
| `oneshot_budget_status` | Today's spend vs the configured budget (read-only) | free |
| `oneshot_list_domains` | List sending domains with reputation + rotation state | free |
| `oneshot_pause_domain` | Take a domain out of rotation | free |
| `oneshot_resume_domain` | Put a paused domain back into rotation | free |

Paid tools are priced in USDC via x402. Current rates are on the [Pricing](https://docs.oneshotagent.com/pricing) page.

## Payment

Paid tools deduct USDC from your wallet on Base Mainnet, settled with the [x402 payment protocol](https://www.x402.org/). Fund the wallet with USDC first.

Read tools (inbox, SMS inbox, notifications, balance) send a signed **EIP-712 read proof** (`x-agent-proof`) so the API can verify you control the `X-Agent-ID` wallet before returning private data. The underlying `oneshot-python` client handles this automatically. It requires `oneshot-python >= 0.18.0`, which is already the dependency floor.

## Complex Arguments

Structured input goes in as strings, because GAME `Argument` supports only scalar types. `commerce_buy`, `build`, and `update_build` take JSON strings, and list fields on `people_search` take comma-separated values:

```python
# The agent will generate these automatically, but for manual testing:
import json

shipping = json.dumps({
    "first_name": "John",
    "last_name": "Doe",
    "street": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip_code": "78701",
    "phone": "+15551234567",
})

product = json.dumps({
    "name": "Acme SaaS",
    "description": "Project management for teams",
})
```

## Configuration

| Parameter | Default | Description |
|-----------|---------|-------------|
| `private_key` | (required) | Hex-encoded Ethereum private key |
| `base_url` | `None` | Override API URL |
| `budgets` | `None` | Server-enforced spend cap, e.g. `{"daily": 50, "per_transaction": 5}` |
| `alert_email` | `None` | Email for budget alerts |

## LinkedIn connection recovery

If the active account list is empty or an account is `connection_deleted` or
`revoked`, ask the human to use `oneshot_linkedin_connect` and authorize fresh
grants. An existing account with `reconnect_required` must be reconnected through
the owning application. Reconnect and revoke are deliberately not agent tools.
Do not create a new connection automatically after authentication failures or
timeouts.

## Requirements

- Python >= 3.10
- `game-sdk >= 0.1.5`
- `oneshot-python >= 0.18.0`

## Links

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

## License

MIT

## Optional phone lookup

`person_find`, `person_profile`, and `person_dossier` accept `include_phone`, off by default. It adds the per-person add-on listed on the pricing page × the requested search limit (default 100) for a search, or once for profile/dossier, for up to that many people with no promised hit. Existing source numbers and published business or record numbers remain available without opting in. Fallbacks and callbacks cost nothing extra; a completed no-match is charged and a failed job is refunded. GAME accepts the string `"true"` or `"false"`. The full quote is checked before payment.

### Solve

Plan vehicle routes, pack items into bins, or schedule jobs on resources, returning constraint checks and conflicts. Use `oneshot_solve` with `problem: "routing"` and a `routing` argument containing vehicles, stops and an objective, `problem: "packing"` and a `packing` argument containing `variant` (`bin` or `knapsack`), `dimensions`, `bins` and `items`, or `problem: "schedule"` and a `schedule` argument containing jobs, resources and an objective. Encode the matching problem block as a JSON object string.

See [Solve](https://docs.oneshotagent.com/api-reference/solve) for input examples, results and limits.
