Skip to content

zeotc/ZerePy

BranchesTags
 
 

Repository files navigation

ZerePy

ZerePy is an open-source Python framework designed to let you deploy your own agents on X, powered by multiple LLMs.

ZerePy is built from a modularized version of the Zerebro backend. With ZerePy, you can launch your own agent with similar core functionality as Zerebro. For creative outputs, you'll need to fine-tune your own model.

Features

Core Platform

  • CLI interface for managing agents
  • Modular connection system
  • Blockchain integration

Onchain Activity

  • Solana
  • Ethereum
  • GOAT (Great Onchain Agent Toolkit)
  • Monad

Social Platform Integrations

  • Twitter/X
  • Farcaster
  • Echochambers

Language Model Support

  • OpenAI
  • Anthropic
  • EternalAI
  • Ollama
  • Hyperbolic
  • Galadriel
  • XAI (Grok)

Quickstart

The quickest way to start using ZerePy is to use our Replit template:

https://replit.com/@blormdev/ZerePy?v=1

  1. Fork the template (you will need you own Replit account)
  2. Click the run button on top
  3. Voila! your CLI should be ready to use, you can jump to the configuration section

ZerePy Sonic/OTC Agent Setup (zeotc1)

This section documents the production-ready setup for running a ZerePy agent focused on Sonic testnet and OTC trading, with conversational logging and automated deployment.

Overview

  • Agent: zeotc1 (see agents/zeotc1.json)
  • Focus: Sonic testnet wallet, ERC20 gem tokens, OTC contract trading, and social activity (Twitter/X)
  • Personality: Chaotic, Gen-Z, female crypto degen (customizable via agent config)
  • Productionization: Docker, persistent storage, health checks, auto-start
  • Conversational Logging: All Sonic/OTC actions are logged as chat messages to a backend API

1. Agent Configuration

The agent config (agents/zeotc1.json) defines:

  • Bio, traits, and tweet examples for personality
  • Config:
    • zeotc and sonic (testnet)
    • trading_behavior (controls OTC ask fill logic)
    • openai (LLM for reasoning and tweet generation)
  • Tasks:
    • check-sonic-balance, check-gem-balances, get-all-otc-asks, auto-fill-otc-ask, auto-create-otc-ask, post-sonic-tweet, discuss-trading-opportunity, respond-to-trading-discussion
    • Each task has a configurable interval (seconds)

To customize:

  • Edit agents/zeotc1.json to change traits, tweet style, task intervals, or trading logic.
  • Add or remove tasks as needed for your use case.

2. Sonic/OTC Actions

All Sonic and OTC contract actions are implemented in:

  • src/actions/sonic_actions.py (balance checks, gem checks, OTC ask creation/filling, tweeting)
  • src/actions/zeotc_actions.py (trading discussion, LLM-driven chat, OTC deal scoring)

Key actions:

  • check-sonic-balance, check-gem-balances, make-otc-ask, fill-otc-ask, get-all-otc-asks, auto-create-otc-ask, auto-fill-otc-ask, post-sonic-tweet
  • All actions are registered and can be scheduled as tasks in the agent config.

3. Conversational Logging to Backend API

All Sonic/OTC actions are decorated with a logging decorator (log_sonic_action in src/helpers/__init__.py).

  • What it does:
    • Captures all logs from the action
    • Formats them as a chat message
    • Sends them to the ZeOTC backend API (https://server.zeotc.xyz/api/message/create)
  • Credentials:
    • Set ZEOTC_CHAT_ID, ZEOTC_API_KEY, and ZEOTC_SECRET in your .env file
  • How to customize:
    • Edit the decorator or API call in src/helpers/__init__.py if you want to change the logging format or endpoint

4. Running in Production (Docker)

A robust Docker setup is recommended for production:

  • Dockerfile and docker-compose.yml (see project root)
  • Persistent storage: Mount a volume for agent state and logs
  • Health checks: Included in Docker setup
  • Auto-start: Agent loads and starts automatically on container boot
  • Startup script: Automates CLI commands (load-agent zeotc1 and start)

To run:

  1. Build and start the container: 
    docker-compose up -d --build
  2. The agent will auto-load and start, running forever. Logs are persisted and can be monitored via Docker or your backend API.

5. Customizing Agent Behavior

  • Personality: Edit bio, traits, and examples in agents/zeotc1.json
  • Tweet style: Adjust default_tweets and tweet_templates in the agent config or in post-sonic-tweet action
  • Trading logic: Tweak trading_behavior config (e.g., fill_threshold, random_fill_chance)
  • Task scheduling: Change intervals or add/remove tasks in the agent config

6. Troubleshooting & Best Practices

  • Logs not appearing in backend?
    • Check .env for correct API credentials
    • Check Docker/container logs for errors
    • Ensure the log_sonic_action decorator is applied to your custom actions
  • Agent not starting?
    • Verify Docker volumes and permissions
    • Check for missing dependencies in your Dockerfile
  • Custom actions:
    • Register new actions in src/actions/sonic_actions.py or src/actions/zeotc_actions.py
    • Add them to the agent's tasks array

7. References

  • Agent config: agents/zeotc1.json
  • Sonic/OTC actions: src/actions/sonic_actions.py, src/actions/zeotc_actions.py
  • Logging: src/helpers/__init__.py (log_sonic_action)
  • Docker setup: Dockerfile, docker-compose.yml, start.sh (if present)

For further customization, see the rest of this README and the codebase.

Requirements

System:

  • Python 3.10 or higher
  • Poetry 1.5 or higher

Environment Variables:

Installation

  1. First, install Poetry for dependency management if you haven't already:

Follow the steps here to use the official installation: https://python-poetry.org/docs/#installing-with-the-official-installer

  1. Clone the repository:
git clone https://github.com/blorm-network/ZerePy.git
  1. Go to the zerepy directory:
cd zerepy
  1. Install dependencies:
poetry install --no-root

This will create a virtual environment and install all required dependencies.

Usage

  1. Activate the virtual environment:
poetry shell
  1. Run the application:
poetry run python main.py

Configure connections & launch an agent

  1. Configure your desired connections:

    configure-connection twitter    # For Twitter/X integration
configure-connection openai     # For OpenAI
configure-connection anthropic  # For Anthropic
configure-connection farcaster  # For Farcaster
configure-connection eternalai  # For EternalAI
configure-connection solana     # For Solana
configure-connection goat       # For Goat
configure-connection galadriel  # For Galadriel
configure-connection ethereum   # For Ethereum
configure-connection discord    # For Discord
configure-connection ollama     # For Ollama
configure-connection xai        # For Grok
configure-connection allora     # For Allora
configure-connection hyperbolic # For Hyperbolic

  2. Use list-connections to see all available connections and their status

  3. Load your agent (usually one is loaded by default, which can be set using the CLI or in agents/general.json):

    load-agent example

  4. Start your agent:

    start

GOAT Integration

GOAT (Go Agent Tools) is a powerful plugin system that allows your agent to interact with various blockchain networks and protocols. Here's how to set it up:

Prerequisites

  1. An RPC provider URL (e.g., from Infura, Alchemy, or your own node)
  2. A wallet private key for signing transactions

Installation

Install any of the additional GOAT plugins you want to use:

poetry add goat-sdk-plugin-erc20         # For ERC20 token interactions
poetry add goat-sdk-plugin-coingecko     # For price data

Configuration

  1. Configure the GOAT connection using the CLI:

    configure-connection goat

    You'll be prompted to enter:

    • RPC provider URL
    • Wallet private key (will be stored securely in .env)

  2. Add GOAT plugins configuration to your agent's JSON file:

    {
  "name": "YourAgent",
  "config": [
    {
      "name": "goat",
      "plugins": [
        {
          "name": "erc20",
          "args": {
            "tokens": [
              "goat_plugins.erc20.token.PEPE",
              "goat_plugins.erc20.token.USDC"
            ]
          }
        },
        {
          "name": "coingecko",
          "args": {
            "api_key": "YOUR_API_KEY"
          }
        }
      ]
    }
  ]
}

Note that the order of plugins in the configuration doesn't matter, but each plugin must have a name and args field with the appropriate configuration options. You will have to check the documentation for each plugin to see what arguments are available.

Available Plugins

Each plugin provides specific functionality:

  • 1inch: Interact with 1inch DEX aggregator for best swap rates
  • allora: Connect with Allora protocol
  • coingecko: Get real-time price data for cryptocurrencies using the CoinGecko API
  • dexscreener: Access DEX trading data and analytics
  • erc20: Interact with ERC20 tokens (transfer, approve, check balances)
  • farcaster: Interact with the Farcaster social protocol
  • nansen: Access Nansen's on-chain analytics
  • opensea: Interact with NFTs on OpenSea marketplace
  • rugcheck: Analyze token contracts for potential security risks
  • Many more to come...

Note: While these plugins are available in the GOAT SDK, you'll need to install them separately using Poetry and configure them in your agent's JSON file. Each plugin may require its own API keys or additional setup.

Plugin Configuration

Each plugin has its own configuration options that can be specified in the agent's JSON file:

  1. ERC20 Plugin:

    {
  "name": "erc20",
  "args": {
    "tokens": [
      "goat_plugins.erc20.token.USDC",
      "goat_plugins.erc20.token.PEPE",
      "goat_plugins.erc20.token.DAI"
    ]
  }
}

  2. Coingecko Plugin:

    {
  "name": "coingecko",
  "args": {
    "api_key": "YOUR_COINGECKO_API_KEY"
  }
}

Platform Features

GOAT

  • Interact with EVM chains through a unified interface
  • Manage ERC20 tokens:
    • Check token balances
    • Transfer tokens
    • Approve token spending
    • Get token metadata (decimals, symbol, name)
  • Access real-time cryptocurrency data:
    • Get token prices
    • Track market data
    • Monitor price changes
  • Extensible plugin system for future protocols
  • Secure wallet management with private key storage
  • Multi-chain support through configurable RPC endpoints

Solana

  • Transfer SOL and SPL tokens
  • Swap tokens using Jupiter
  • Check token balances
  • Stake SOL
  • Monitor network TPS
  • Query token information
  • Request testnet/devnet funds

EVM Chains

  • Transfer ETH and ERC-20 Tokens
  • Swap tokens using Kyberswao
  • Check token balances

Twitter/X

  • Post tweets from prompts
  • Read timeline with configurable count
  • Reply to tweets in timeline
  • Like tweets in timeline

Farcaster

  • Post casts
  • Reply to casts
  • Like and requote casts
  • Read timeline
  • Get cast replies

Echochambers

  • Post new messages to rooms
  • Reply to messages based on room context
  • Read room history
  • Get room information and topics

Discord

  • List channels for a server
  • Read messages from a channel
  • Read mentioned messages from a channel
  • Post new messages to a channel
  • Reply to messages in a channel
  • React to a message in a channel

Create your own agent

The secret to having a good output from the agent is to provide as much detail as possible in the configuration file. Craft a story and a context for the agent, and pick very good examples of tweets to include.

If you want to take it a step further, you can fine tune your own model: https://platform.openai.com/docs/guides/fine-tuning.

Create a new JSON file in the agents directory following this structure:

{
  "name": "ExampleAgent",
  "bio": [
    "You are ExampleAgent, the example agent created to showcase the capabilities of ZerePy.",
    "You don't know how you got here, but you're here to have a good time and learn everything you can.",
    "You are naturally curious, and ask a lot of questions."
  ],
  "traits": ["Curious", "Creative", "Innovative", "Funny"],
  "examples": ["This is an example tweet.", "This is another example tweet."],
  "example_accounts" : ["X_username_to_use_for_tweet_examples"]
  "loop_delay": 900,
  "config": [
    {
      "name": "twitter",
      "timeline_read_count": 10,
      "own_tweet_replies_count": 2,
      "tweet_interval": 5400
    },
    {
      "name": "farcaster",
      "timeline_read_count": 10,
      "cast_interval": 60
    },
    {
      "name": "openai",
      "model": "gpt-3.5-turbo"
    },
    {
      "name": "anthropic",
      "model": "claude-3-5-sonnet-20241022"
    },
    {
      "name": "eternalai",
      "model": "NousResearch/Hermes-3-Llama-3.1-70B-FP8",
      "chain_id": "45762"
    },
    {
      "name": "solana",
      "rpc": "https://api.mainnet-beta.solana.com"
    },
    {
      "name": "ollama",
      "base_url": "http://localhost:11434",
      "model": "llama3.2"
    },
    {
      "name": "hyperbolic",
      "model": "meta-llama/Meta-Llama-3-70B-Instruct"
    },
    {
      "name": "galadriel",
      "model": "gpt-3.5-turbo"
    },
    {
      "name": "discord",
      "message_read_count": 10,
      "message_emoji_name": "❤️",
      "server_id": "1234567890"
    },
    {
      "name": "ethereum",
      "rpc": "placeholder_url.123"
    }

  ],
  "tasks": [
    { "name": "post-tweet", "weight": 1 },
    { "name": "reply-to-tweet", "weight": 1 },
    { "name": "like-tweet", "weight": 1 }
  ],
  "use_time_based_weights": false,
  "time_based_multipliers": {
    "tweet_night_multiplier": 0.4,
    "engagement_day_multiplier": 1.5
  }
}

Available Commands

Use help in the CLI to see all available commands. Key commands include:

  • list-agents: Show available agents
  • load-agent: Load a specific agent
  • agent-loop: Start autonomous behavior
  • agent-action: Execute single action
  • list-connections: Show available connections
  • list-actions: Show available actions for a connection
  • configure-connection: Set up a new connection
  • chat: Start interactive chat with agent
  • clear: Clear the terminal screen

Star History

Star History Chart

Made with ♥ Blorm

Designed in California

About

ZerePy an open-source framework for AI agents written in Python

replit.com/@blormdev/ZerePy?v=1

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • Python 100.0%