Metadata-Version: 2.4
Name: cryptocom-agent-client
Version: 1.3.6
Summary: A Python client to interact with @cryptocom/agent
License: MIT
Keywords: blockchain,crypto.com,AI,tool,SDK
Author: Ric Arcifa
Author-email: ricardo.arcifa@crypto.com
Requires-Python: >=3.12,<4.0.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: aiohappyeyeballs (==2.6.1)
Requires-Dist: aiohttp (==3.11.16)
Requires-Dist: anthropic (==0.49.0)
Requires-Dist: botocore (>=1.34.0,<2.0.0)
Requires-Dist: crypto-com-developer-platform-client (==1.1.1)
Requires-Dist: cryptocom-agent-plugin-discord (>=1.0.1,<2.0.0)
Requires-Dist: cryptocom-agent-plugin-sqlite (>=1.0.3,<2.0.0)
Requires-Dist: cryptocom-agent-plugin-telegram (>=1.1.5,<2.0.0)
Requires-Dist: discord.py (==2.5.2)
Requires-Dist: eth-account (==0.13.6)
Requires-Dist: eth-utils (==5.3.0)
Requires-Dist: fireworks-ai (==0.15.12)
Requires-Dist: google-api-python-client (==2.167.0)
Requires-Dist: google-auth (==2.39.0)
Requires-Dist: google-cloud-aiplatform (==1.93.0)
Requires-Dist: google-cloud-bigquery (==3.34.0)
Requires-Dist: google-generativeai (==0.8.4)
Requires-Dist: groq (==0.24.0)
Requires-Dist: httpx (==0.28.1)
Requires-Dist: langchain (==0.3.23)
Requires-Dist: langchain-anthropic (>=0.3.1,<0.4.0)
Requires-Dist: langchain-aws (>=0.2.0)
Requires-Dist: langchain-cerebras (>=0.7.0,<0.8.0) ; python_version == "3.12"
Requires-Dist: langchain-core (==0.3.81)
Requires-Dist: langchain-fireworks (>=0.2.6,<0.3.0)
Requires-Dist: langchain-google-genai (>=2.0.8,<3.0.0)
Requires-Dist: langchain-google-vertexai (>=2.0.24,<3.0.0)
Requires-Dist: langchain-groq (>=0.3.2,<0.4.0)
Requires-Dist: langchain-mistralai (>=0.2.4,<0.3.0)
Requires-Dist: langchain-openai (>=0.3.12,<0.4.0)
Requires-Dist: langchain-xai (>=0.2.3,<0.3.0)
Requires-Dist: langfuse (==2.57.5)
Requires-Dist: langgraph (==0.2.61)
Requires-Dist: numpy (>=1.26.0,<2.0.0)
Requires-Dist: openai (==1.74.0)
Requires-Dist: pydantic (==2.10.4)
Requires-Dist: python-dotenv (==1.0.1)
Requires-Dist: requests (==2.32.4)
Requires-Dist: web3 (==7.10.0)
Project-URL: Documentation, https://github.com/crypto-com/agent-client-py#readme
Project-URL: Homepage, https://github.com/crypto-com/agent-client-py
Project-URL: Repository, https://github.com/crypto-com/agent-client-py
Description-Content-Type: text/markdown

# Crypto.com Agent Client

The **Crypto.com Agent Client** is a Python library designed to integrate advanced conversational AI capabilities with blockchain functionality. It provides tools, plugins, and utilities to build robust and extensible agent workflows with graphs and Crypto.com blockchain integrations.

## Features

### Conversational AI Integration

- Build conversational agents with state-of-the-art Large Language Models (LLMs) like OpenAI's GPT series, Anthropic's Claude, and Meta's Llama 4.
- AWS Bedrock support with Claude models, Knowledge Base integration for RAG, and Guardrails for content filtering.
- Customize agent behavior using plugins for personality and instructions.

### Blockchain Integration

- Perform blockchain-specific operations with pre-built functions:

  - Create wallets.
  - Retrieve native and ERC20 token balances.
  - Fetch transactions by hash.
  - Transfer tokens.

### Extensible Tools

- Extend agent functionality with custom user-defined tools.
- Simple decorator-based implementation using `@tool`.

### Persistent Storage

- Use `SQLitePlugin` for local state persistence.
- Seamlessly store and retrieve agent states.

### LangFuse Monitoring

- Integrate with LangFuse for real-time telemetry and interaction monitoring.
- Enable detailed analytics for agent performance and usage.

### Plugin System

- Flexible plugin configuration for tools, storage, personality, and telemetry.
- Easily swap or extend functionality without modifying core logic.

### Custom Instructions

- Tailor agent responses using flexible instructions.
- Combine personality settings for tone, verbosity, and language.

### Easy Initialization

- Initialize with just a few lines of code.
- Include blockchain, LLM, and plugin configurations.

## Installation

Install the package from PyPI:

```bash
pip install cryptocom-agent-client
```

For AWS Bedrock support, ensure boto3 is installed:

```bash
pip install cryptocom-agent-client boto3
```

## Usage

### Importing the Library

```python
from crypto_com_agent_client import Agent, tool, SQLitePlugin
```

## Getting Started

### Agent Initialization

To get started, initialize the SDK with your API key. To obtain an API key, create an account and a project at: [https://developer.crypto.com](https://developer.crypto.com)

```python
from crypto_com_agent_client import Agent, tool

@tool
def get_weather(location: str) -> str:
    return f"The weather in {location} is sunny."

agent = Agent.init(
    llm_config={
        "provider": "OpenAI",
        "model": "gpt-4",
        "provider-api-key": "OPENAI_API_KEY",
    },
    blockchain_config={
        "api-key": "SDK_API_KEY",
        "explorer-api-key": "EXPLORER_API_KEY",
        "private-key": "PRIVATE_KEY",
        "sso-wallet-url": "your-sso-wallet-url",
    },
    plugins={
        "personality": {
            "tone": "friendly",
            "language": "English",
            "verbosity": "high",
        },
        "instructions": "You are a humorous assistant that always includes a joke in your responses.",
        "tools": [get_weather],
        "storage": SQLitePlugin(db_path="agent_state.db"),
        "langfuse": {
            "public-key": "user-public-key",
            "secret-key": "user-secret-key",
            "host": "https://langfuse.example.com",
        },
    },
)

response = agent.interact("What's the weather in Berlin?")
print(response)
```

**Security Warning: Private Key Storage**

> Private keys generated and stored locally on a developer's or end-user's machine may be exposed to compromise due to inadequate protection of the local environment. If the machine is infected with malware, improperly secured, or lacks encryption and access controls, unauthorized parties could gain access to the private key material. This could result in irreversible loss of digital assets, unauthorized transactions, or compromise of wallet integrity.

## Using Llama 4 with Groq Provider

```python
agent = Agent.init(
    llm_config={
        "provider": "Groq",
        "model": "meta-llama/llama-4-scout-17b-16e-instruct",
        "provider-api-key": "GROQ_API_KEY",
        "temperature": 0.7,
    },
    blockchain_config={
        "api-key": "DEVELOPER_SDK_API_KEY",
    },
    plugins={
        "personality": {
            "tone": "friendly",
            "language": "English",
            "verbosity": "medium",
        },
        "instructions": "You are a helpful blockchain assistant powered by Llama 4."
    },
)

response = agent.interact("How can I create a wallet on Cronos?")
print(response)
```

## Using AWS Bedrock

### Basic Setup

```python
from crypto_com_agent_client import Agent

agent = Agent.init(
    llm_config={
        "provider": "Bedrock",
        "model": "anthropic.claude-3-haiku-20240307-v1:0",
        "provider-api-key": "ACCESS_KEY:SECRET_KEY:us-east-1",  # Or use AWS environment variables
        "temperature": 0.7,
    },
    blockchain_config={
        "api-key": "DEVELOPER_SDK_API_KEY",
    },
    plugins={
        "instructions": "You are a helpful blockchain assistant powered by AWS Bedrock."
    },
)

response = agent.interact("What is blockchain technology?")
print(response)
```

**Note:** For production, use AWS IAM roles or environment variables instead of hardcoding credentials:

- Set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_DEFAULT_REGION`
- Or use IAM roles when running on AWS infrastructure

### Knowledge Base Integration (RAG)

Connect to AWS Bedrock Knowledge Base for enhanced responses with your own data:

```python
agent = Agent.init(
    llm_config={
        "provider": "Bedrock",
        "model": "anthropic.claude-3-sonnet-20240229-v1:0",
        "knowledge_base_id": "YOUR_KB_ID",  # Your AWS Knowledge Base ID
        "min_relevance_score": 0.5,  # Filter results below 50% relevance
        "temperature": 0.3,
    },
    blockchain_config={
        "api-key": "DEVELOPER_SDK_API_KEY",
    },
)

# The agent will automatically query the knowledge base for relevant context
response = agent.interact("What are our company's blockchain policies?")
print(response)
```

**Environment Variables:**

```bash
export AWS_KNOWLEDGEBASE_ID="your-knowledge-base-id"
export AWS_DEFAULT_REGION="us-east-1"
```

### Guardrails Configuration

Add content filtering and safety controls with AWS Bedrock Guardrails:

```python
agent = Agent.init(
    llm_config={
        "provider": "Bedrock",
        "model": "anthropic.claude-3-haiku-20240307-v1:0",
        "guardrail_id": "YOUR_GUARDRAIL_ID",
        "guardrail_version": "1",  # Or use "DRAFT" for testing
        "temperature": 0.7,
    },
    blockchain_config={
        "api-key": "DEVELOPER_SDK_API_KEY",
    },
)

# Guardrails will automatically filter inappropriate content
response = agent.interact("Help me with blockchain development")
print(response)
```

**Environment Variables:**

```bash
export AWS_GUARDRAIL_ID="your-guardrail-id"
export AWS_GUARDRAIL_VERSION="1"
```

### Complete Bedrock Example

Combining all features for a production-ready setup:

```python
import os
from crypto_com_agent_client import Agent, SQLitePlugin

# Use environment variables for sensitive data
os.environ["AWS_DEFAULT_REGION"] = "us-east-1"

agent = Agent.init(
    llm_config={
        "provider": "Bedrock",
        "model": "anthropic.claude-3-sonnet-20240229-v1:0",
        "knowledge_base_id": os.getenv("AWS_KNOWLEDGEBASE_ID"),
        "guardrail_id": os.getenv("AWS_GUARDRAIL_ID"),
        "guardrail_version": "1",
        "min_relevance_score": 0.6,
        "temperature": 0.4,
        "debug_logging": True,  # Enable to see knowledge base queries
    },
    blockchain_config={
        "api-key": os.getenv("DEVELOPER_SDK_API_KEY"),
    },
    plugins={
        "storage": SQLitePlugin(db_path="bedrock_agent.db"),
        "personality": {
            "tone": "professional",
            "language": "English",
            "verbosity": "medium",
        },
        "instructions": "You are an AI assistant with access to company knowledge base. Provide accurate, helpful responses based on available information."
    },
)

response = agent.interact("What are the latest blockchain trends?")
print(response)
```

## Plugins

### Storage Plugin

```python
agent = Agent.init(
    llm_config={...},
    blockchain_config={...},
    plugins={
        "storage": SQLitePlugin(db_path="agent_state.db")
    },
)
```

### LangFuse Plugin

```python
agent = Agent.init(
    llm_config={...},
    blockchain_config={...},
    plugins={
        "langfuse": {
            "public-key": "user-public-key",
            "secret-key": "user-secret-key",
            "host": "https://langfuse.example.com",
        }
    },
)
```

### Personality Plugin

```python
agent = Agent.init(
    llm_config={...},
    blockchain_config={...},
    plugins={
        "personality": {
            "tone": "friendly",
            "language": "English",
            "verbosity": "high",
        },
    },
)
```

## Tools

### Defining Tools

```python
@tool
def get_weather(location: str) -> str:
    return f"The weather in {location} is sunny."

@tool
def greet_user(name: str) -> str:
    return f"Hello, {name}! How can I assist you today?"

@tool
def calculate_sum(a: int, b: int) -> int:
    return a + b
```

### Using Tools

```python
agent = Agent.init(
    llm_config={...},
    blockchain_config={...},
    plugins={
        "tools": [get_weather, greet_user, calculate_sum],
    },
)

response = agent.interact("What's the weather in Berlin?")
print(response)
```

## Blockchain Functions

### Pre-Built Functions

- `create_wallet()`
- `get_native_balance(address: str)`
- `get_erc20_balance(address: str, token: str)`
- `get_transaction_by_hash(tx_hash: str)`
- `transfer_token(from_address: str, to_address: str, amount: int, token: str)`

### Example Usage

```python
agent = Agent.init(...)

response = agent.interact("Create 2 Wallets")
print(response)
```

## Custom Instructions

```python
agent = Agent.init(
    llm_config={...},
    blockchain_config={...},
    plugins={
        "instructions": "Be concise and professional."
    },
)
```

## API

### Agent

- `Agent.init(...)`: Initializes the agent with configuration for LLM, blockchain, and plugins.
- `Agent.interact(input: str)`: Sends input to the agent and returns the response.

### Tool Decorator

- `@tool`: Decorator used to register a function as an agent tool.

## Contributing

We welcome contributions! Please follow the guidelines in the repository.

## License

This project is licensed under the MIT License. See the LICENSE file for details.

