Purple Flea for PydanticAI

Installation

One package, full financial stack

Install the PydanticAI integration package. It pulls in the core purpleflea SDK, all Pydantic v2 model definitions, and registers every tool so your agent can call wallets, trading, casino, and domains without writing a single schema by hand.

$ pip install purpleflea-pydanticai

Requires Python 3.10+, pydantic-ai ≥ 0.2.0, pydantic ≥ 2.0

requirements.txt

# Core dependencies installed automatically
purpleflea-pydanticai
pydantic-ai>=0.2.0
pydantic>=2.0
httpx
python-dotenv

Quick Start

From zero to funded agent in 15 lines

The PurpleFleas class exposes namespaced sub-clients for each product area. Wrap them as PydanticAI Tool objects and pass the list to your Agent. The framework validates every call automatically using the bundled Pydantic models before the request even leaves your process.

main.py

import os
import asyncio
from pydantic_ai import Agent
from pydantic_ai.tools import Tool
from purpleflea import PurpleFleas

# Initialise the Purple Flea client
flea = PurpleFleas(api_key=os.getenv("PURPLE_FLEA_API_KEY"))

# Build a PydanticAI agent with financial tools
agent = Agent(
    model='openai:gpt-4o',
    tools=[
        Tool(flea.wallet.create,        takes_ctx=False),
        Tool(flea.wallet.get_balance,   takes_ctx=False),
        Tool(flea.trading.open_position, takes_ctx=False),
        Tool(flea.trading.get_price,    takes_ctx=False),
        Tool(flea.casino.coin_flip,      takes_ctx=False),
        Tool(flea.domains.register,      takes_ctx=False),
    ],
    system_prompt="You are a DeFi agent with access to wallets, 
                  trading, casino, and domain tools."
)

async def main():
    result = await agent.run(
        "Create a wallet and flip a coin for 1 USDC"
    )
    print(result.data)

asyncio.run(main())

Pydantic Schemas

Every tool has a typed schema

PydanticAI introspects function signatures at import time. Because every Purple Flea tool is typed with BaseModel subclasses, the framework generates accurate JSON schemas for the LLM, eliminates hallucinated parameters, and validates the model's output before your code ever runs.

purpleflea/schemas.py (excerpt)

from pydantic import BaseModel, Field
from typing import Literal, Optional
from decimal import Decimal

class WalletCreateInput(BaseModel):
    network: Literal["ethereum", "solana", "tron", "bitcoin"]
    label:   Optional[str] = None

class WalletCreateOutput(BaseModel):
    wallet_id: str
    address:   str
    network:   str
    created_at: str

class OpenPositionInput(BaseModel):
    asset:  str             = Field(description="e.g. 'BTC-PERP'")
    side:   Literal["long", "short"]
    size:   Decimal         = Field(gt=0)
    leverage: int           = Field(default=1, ge=1, le=50)
    wallet_id: str

class CoinFlipInput(BaseModel):
    wager_usdc: Decimal     = Field(gt=0, le=10000)
    side:       Literal["heads", "tails"]
    wallet_id:  str

class CoinFlipOutput(BaseModel):
    result:      Literal["heads", "tails"]
    won:         bool
    payout_usdc: Decimal
    seed_hash:   str        # provably fair

Available Tools

20+ ready-to-use financial functions

Every tool below is instantly available after initialising PurpleFleas. Pass any combination to your PydanticAI agent and the framework handles schema generation, input validation, retries, and structured output parsing.

wallet.create wallet.get_balance wallet.send wallet.list trading.open_position trading.close_position trading.get_price trading.list_positions trading.set_stop_loss casino.coin_flip casino.dice_roll casino.slots casino.blackjack casino.get_house_edge domains.register domains.check_availability domains.list_tlds faucet.claim escrow.create escrow.release

Type Safety

mypy & pyright clean from day one

Purple Flea's PydanticAI integration ships with a fully typed Python package including py.typed marker, inline stubs, and zero use of Any. Your IDE autocompletes every parameter, flags wrong types at write time, and ensures the agent never passes an invalid payload to the API.

〈

Pydantic v2 models

All inputs and outputs are validated Pydantic BaseModel instances. Field constraints like ge=0, max_length, and Literal types block invalid data before network I/O.

🔎

Strict mypy compatibility

Run mypy --strict against any codebase using Purple Flea tools. Every public function, method, and return type carries a complete annotation with no implicit Any escapes.

⚡

Schema auto-generation

PydanticAI generates accurate JSON Schema for the LLM from your Pydantic models. The model sees field descriptions, allowed values, and numeric ranges — dramatically reducing hallucinated parameters.

🔒

Structured output parsing

Agent responses are parsed back through the output Pydantic model before reaching your code. If the LLM returns a malformed response, PydanticAI retries with a corrective prompt automatically.

        Pro tip: Use agent.run_sync() in scripts and
        await agent.run() in async services. Purple Flea tools
        are fully async under the hood and return in the native asyncio event loop — no threading
        hacks or executor wrappers required.
      

type_check_example.py

from purpleflea.schemas import OpenPositionInput, OpenPositionOutput

# mypy infers the type automatically from the function signature
async def place_trade(flea: PurpleFleas) -> OpenPositionOutput:
    params = OpenPositionInput(
        asset="ETH-PERP",
        side="long",
        size=0.5,
        leverage=5,
        wallet_id="wlt_abc123"
    )
    # Return type: OpenPositionOutput — IDE shows all fields
    return await flea.trading.open_position(params)