Metadata-Version: 2.4
Name: elizaos-plugin-farcaster
Version: 2.0.0a5
Summary: Farcaster plugin for elizaOS - Python implementation for casting and receiving messages
Project-URL: Homepage, https://github.com/elizaos/eliza
Project-URL: Documentation, https://elizaos.ai/docs
Project-URL: Repository, https://github.com/elizaos/eliza
Project-URL: Issues, https://github.com/elizaos/eliza/issues
Author: elizaOS Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,elizaos,farcaster,neynar,social,web3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.19.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest-xprocess>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.14.0; extra == 'dev'
Description-Content-Type: text/markdown

# elizaOS Farcaster Plugin - Python

A Python implementation of the Farcaster plugin for elizaOS, providing full integration with the Farcaster decentralized social network via the Neynar API.

## Features

- **Cast Management**: Send casts, reply to casts, and manage your timeline
- **Profile Management**: Fetch and cache user profiles
- **Mentions & Notifications**: Monitor and respond to mentions
- **Timeline Provider**: Access your Farcaster feed
- **Thread Support**: Navigate and respond within cast threads
- **Embed Processing**: Handle images, videos, and embedded casts

## Installation

```bash
pip install elizaos-plugin-farcaster
```

Or with development dependencies:

```bash
pip install elizaos-plugin-farcaster[dev]
```

## Configuration

The plugin requires the following environment variables:

| Variable                   | Required | Description                                               |
| -------------------------- | -------- | --------------------------------------------------------- |
| `FARCASTER_FID`            | Yes      | Your Farcaster ID (FID)                                   |
| `FARCASTER_SIGNER_UUID`    | Yes      | Neynar signer UUID for signing casts                      |
| `FARCASTER_NEYNAR_API_KEY` | Yes      | Neynar API key for API access                             |
| `FARCASTER_DRY_RUN`        | No       | Enable dry run mode (default: false)                      |
| `FARCASTER_MODE`           | No       | Operation mode: 'polling' or 'webhook' (default: polling) |
| `MAX_CAST_LENGTH`          | No       | Maximum cast length (default: 320)                        |
| `FARCASTER_POLL_INTERVAL`  | No       | Polling interval in seconds (default: 120)                |

## Usage

### Basic Usage

```python
from elizaos_plugin_farcaster import FarcasterClient, FarcasterConfig

# Load configuration from environment
config = FarcasterConfig.from_env()

# Create client
client = FarcasterClient(config)

# Send a cast
async def main():
    cast = await client.send_cast("Hello from elizaOS! 🤖")
    print(f"Cast sent: {cast.hash}")

    # Get your profile
    profile = await client.get_profile(config.fid)
    print(f"Username: {profile.username}")

# Run
import asyncio
asyncio.run(main())
```

### With elizaOS Runtime

```python
from elizaos_plugin_farcaster import farcaster_plugin

# Register with agent runtime
runtime.register_plugin(farcaster_plugin)
```

## Development

### Running Tests

```bash
cd python
pytest
```

### Type Checking

```bash
mypy elizaos_plugin_farcaster
```

### Linting

```bash
ruff check .
ruff format .
```

## API Reference

### FarcasterClient

The main client for interacting with Farcaster via Neynar.

- `send_cast(text, reply_to=None)` - Send a new cast
- `get_cast(hash)` - Get a cast by hash
- `get_profile(fid)` - Get a user profile by FID
- `get_mentions(limit=20)` - Get mentions for the configured FID
- `get_timeline(limit=50)` - Get the user's timeline

### Types

- `Cast` - Represents a Farcaster cast
- `Profile` - Represents a Farcaster user profile
- `CastEmbed` - Represents embedded content in a cast
- `FarcasterConfig` - Configuration for the Farcaster client

## License

MIT License - see LICENSE file for details.
