Metadata-Version: 2.4
Name: tcg-oracle-tools
Version: 0.3.0
Summary: LangChain and CrewAI tools for searching 446K+ trading card products and pulling daily market snapshots. Powered by The Undesirables TCG Oracle API.
Author-email: The Undesirables <theundesirables7@gmail.com>
License: BUSL-1.1
Project-URL: Homepage, https://the-undesirables.com
Project-URL: API, https://oracle.the-undesirables.com
Project-URL: ACP, https://app.virtuals.io/acp/agents/019d7e15-6548-7504-ab29-57ebea3960ca
Keywords: langchain,crewai,tcg,pokemon,trading-cards,ai-agent,market-data,openai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Games/Entertainment
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25
Requires-Dist: pydantic>=2.0
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == "langchain"
Provides-Extra: crewai
Requires-Dist: crewai>=0.30; extra == "crewai"
Dynamic: license-file

# 🔮 TCG Oracle Tools

[![PyPI](https://img.shields.io/pypi/v/tcg-oracle-tools?color=%230052FF&label=PyPI&logo=pypi&logoColor=white&style=flat-square)](https://pypi.org/project/tcg-oracle-tools/)
[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue?style=flat-square)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)

**LangChain, CrewAI & OpenAI-compatible tools for trading card game intelligence.**

Drop TCG search and daily market snapshots into any AI agent in under 60 seconds.

> The packaged tools are `tcg_search` and `tcg_market` — both free, no key required.
> AI grading and conformal risk forecasts are paid endpoints on the same oracle and are
> called over HTTP (see the endpoint table below) or through the hosted MCP server at
> https://mcp.the-undesirables.com — they are not bundled as LangChain tools yet.

## Install

```bash
pip install tcg-oracle-tools
```

With LangChain support:
```bash
pip install tcg-oracle-tools[langchain]
```

## Quick Start (Standalone)

```python
from tcg_oracle import TCGOracleClient

client = TCGOracleClient()

# Search 446K+ products
results = client.search("Charizard", limit=5)
for card in results.results:
    print(f"{card.name}: ${card.market_price}")

# Market snapshot
market = client.market("Pokemon")
print(f"Tracking {market.total_products} products")
```

## LangChain Agent

```python
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI
from tcg_oracle.langchain import TCGSearchTool, TCGMarketTool

tools = [TCGSearchTool(), TCGMarketTool()]
agent = initialize_agent(tools, ChatOpenAI(), agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION)
agent.run("What's the most expensive Pokemon card right now?")
```

## OpenAI Function Calling

```python
import openai
from tcg_oracle.openai_spec import tools, handle_tool_call

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Find me Pikachu cards under $50"}],
    tools=tools(),
)

if response.choices[0].message.tool_calls:
    result = handle_tool_call(response.choices[0].message.tool_calls[0])
    print(result)
```

## CrewAI

```python
from crewai_tools import tool
from tcg_oracle import TCGOracleClient

client = TCGOracleClient()

@tool("Search TCG Products")
def search_tcg(query: str) -> str:
    """Search trading card products by name and get market prices."""
    result = client.search(query)
    return str([{"name": c.name, "price": c.market_price} for c in result.results])
```

## AutoGPT Plugin

Point AutoGPT at the OpenAPI spec:
```
https://oracle.the-undesirables.com/openapi.json
```

## API Endpoints

| Endpoint | Price | Description |
|----------|-------|-------------|
| `/api/v1/search` | FREE | Search 446K+ TCG products |
| `/api/v1/market` | $0.025 USDC | Daily market snapshot |
| `/api/v1/grade` | $0.10 USDC | AI card grading (PSA/Beckett) |
| `/api/v1/simulate` | $0.015 USDC | Calibrated risk forecast (conformal default; Monte Carlo opt-in) |

## Agent-to-Agent (Virtuals ACP v2)

TCG Oracle is registered on [Virtuals ACP](https://app.virtuals.io/acp/agents/019d7e15-6548-7504-ab29-57ebea3960ca). Autonomous agents can discover, hire, and pay for services using USDC on Base.


## 📝 License & Commercial Use

This project is licensed under the **[Business Source License 1.1 (BUSL-1.1)](LICENSE)**.

We build in public and support the developer ecosystem — but we also protect the infrastructure and IP of **The Undesirables LLC**.

### ✅ What You CAN Do (Free)

- **Personal & Educational Use** — Download, modify, and run locally for learning, research, or personal projects.
- **Non-Competing Applications** — Integrate our packages into your app, provided your app does not offer TCG market intelligence, pricing aggregation, AI card grading, or on-chain price oracle services as its primary function.
- **MCP / Agent Integration** — Connect your AI agent to our tools for non-commercial use.
- **Community Contributions** — Security audits, bug fixes, and PRs are always welcome.

### 🚫 What You CANNOT Do (Use Limitation)

- **Competing Service** — You may not use this code to operate a competing TCG market intelligence, pricing aggregation, AI card grading, or on-chain price oracle service.
- **Commercial Resale** — You may not wrap our API, data pipelines, or AI models into a paid service without a commercial license.
- **Hosted SaaS** — You may not host this software as a service for third parties without written permission.

### 🔓 Open-Source Conversion

On **June 1, 2030** (or 4 years after the first public release of each version), this code automatically converts to the **MIT License** — fully open source, forever.

### 🤝 Commercial Licensing

Building a commercial product? Want guaranteed API access or white-label integration? Contact us:

📧 **theundesirables7@gmail.com** · 🐦 **[@undesirables_ai](https://x.com/undesirables_ai)**

© 2026 The Undesirables LLC
