Skip to content

Commit 9d30189

Browse files
cromewarcromewar
committed
askNebula MVP project
0 parents  commit 9d30189

15 files changed

+4947
-0
lines changed

‎.dockerignore

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Version control
2+
.git
3+
.gitignore
4+
5+
# Python virtual environments
6+
.venv
7+
__pycache__
8+
*.pyc
9+
*.pyo
10+
*.pyd
11+
.Python
12+
env
13+
14+
# Logs
15+
*.log
16+
17+
# Environment files (will be mounted as volumes)
18+
.env
19+
20+
# Miscellaneous
21+
.DS_Store
22+
README*.md
23+
.python-version
24+
Dockerfile
25+
docker-compose.yml
26+
.dockerignore

‎.env.example

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
OPENAI_API_KEY="your_openai_api_key"
2+
THIRDWEB_SECRET_KEY="your_thirdweb_secret_key"
3+
THIRDWEB_ENGINE_URL="your_thirdweb_engine_url"
4+
THIRDWEB_ENGINE_AUTH_JWT="your_thirdweb_engine_auth_jwt"
5+
6+
# X / Twitter API Keys
7+
ACCESS_TOKEN=your_access_token
8+
ACCESS_TOKEN_SECRET=your_access_token_secret
9+
TWITTER_API_KEY=your_twitter_api_key
10+
TWITTER_API_SECRET=your_twitter_api_secret
11+
BEARER_TOKEN=your_bearer_token
12+
13+
# Local OLLAMA model Name
14+
OLLAMA_MODEL_NAME="llama3.1:8b"

‎.gitignore

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Python-generated files
2+
__pycache__/
3+
*.py[oc]
4+
build/
5+
dist/
6+
wheels/
7+
*.egg-info
8+
9+
# Virtual environments
10+
.venv
11+
12+
# Environment variables
13+
.env

‎.python-version

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.11

‎Dockerfile

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
FROM python:3.11-slim
2+
3+
WORKDIR /app
4+
5+
# Copy dependency files
6+
COPY pyproject.toml .
7+
COPY uv.lock .
8+
COPY .env.example .
9+
10+
# Install dependencies directly with pip instead of using uv
11+
RUN pip install --no-cache-dir tweepy python-dotenv langchain langchain-openai thirdweb-ai pydantic
12+
13+
# Copy application code
14+
COPY *.py .
15+
COPY .env.example .env
16+
17+
# Run the Twitter bot
18+
CMD ["python", "twiiter_bot.py"]

‎README-docker.md

+102
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Docker Deployment for MVP AskNebula
2+
3+
This guide explains how to deploy the MVP AskNebula service using Docker and Docker Compose.
4+
5+
## Prerequisites
6+
7+
- Docker installed on your server
8+
- Docker Compose installed on your server
9+
- Your API keys and credentials ready for the `.env` file
10+
11+
## Setup
12+
13+
1. Clone the repository to your server:
14+
```
15+
git clone https://github.com/yourusername/mvp-ask-nebula.git
16+
cd mvp-ask-nebula
17+
```
18+
19+
2. Create your `.env` file from the template:
20+
```
21+
cp .env.example .env
22+
```
23+
24+
3. Edit the `.env` file with your actual API keys and credentials:
25+
```
26+
nano .env
27+
```
28+
29+
## Deployment
30+
31+
1. Build and start the container in detached mode:
32+
```
33+
docker-compose up -d
34+
```
35+
36+
2. Check the container status:
37+
```
38+
docker-compose ps
39+
```
40+
41+
3. View the logs:
42+
```
43+
docker-compose logs
44+
```
45+
46+
To follow the logs in real-time:
47+
```
48+
docker-compose logs -f
49+
```
50+
51+
## Managing the Container
52+
53+
### Stop the service
54+
```
55+
docker-compose stop
56+
```
57+
58+
### Restart the service
59+
```
60+
docker-compose restart
61+
```
62+
63+
### Rebuild and restart (after code changes)
64+
```
65+
docker-compose up -d --build
66+
```
67+
68+
### Completely remove the container
69+
```
70+
docker-compose down
71+
```
72+
73+
## Data Persistence
74+
75+
The Docker Compose configuration is set up to preserve:
76+
77+
1. The `last_mention.json` file, which tracks which Twitter mentions have been processed
78+
2. The `twitter_bot.log` file for logging
79+
80+
These files are mounted as volumes from your host system to the container.
81+
82+
## Troubleshooting
83+
84+
1. If the container fails to start, check the logs:
85+
```
86+
docker-compose logs
87+
```
88+
89+
2. If you update your code, remember to rebuild the container:
90+
```
91+
docker-compose up -d --build
92+
```
93+
94+
3. If you're having authentication issues, verify that your `.env` file is correctly mounted by checking:
95+
```
96+
docker-compose exec asknebula cat .env
97+
```
98+
99+
4. To enter the container for debugging:
100+
```
101+
docker-compose exec asknebula bash
102+
```

‎README.md

+147
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# MVP AskNebula - AI-Powered Blockchain Data Service
2+
3+
MVP AskNebula is an AI-powered blockchain data service that provides detailed information about blockchain transactions, addresses, ENS names, and more. The project consists of two main components:
4+
5+
1. **AskNebula Core Service** - A backend service that uses LangChain and ThirdWeb to query blockchain data
6+
2. **Twitter Bot** - A Twitter (X) bot that answers blockchain-related questions asked by users through mentions
7+
8+
## Features
9+
10+
- **Blockchain Data Retrieval**: Get detailed information about:
11+
- ENS name resolution
12+
- Wallet balances
13+
- Transaction details
14+
- Contract interactions
15+
- Suspicious activity detection
16+
- Cross-chain data
17+
18+
- **Intelligent Response Formatting**:
19+
- Complex answers are automatically formatted as Twitter threads
20+
- Simple answers are provided as single tweets
21+
- Off-topic questions receive clever responses
22+
23+
- **Continuous Monitoring**:
24+
- The Twitter bot continuously monitors for mentions
25+
- Processes new questions as they arrive
26+
- Respects Twitter API rate limits
27+
28+
## Architecture
29+
30+
The project is organized into three main Python modules:
31+
32+
1. **askNebula.py** - Core blockchain data service using ThirdWeb and LangChain
33+
2. **thread_creator.py** - Content formatting service for Twitter
34+
3. **twiiter_bot.py** - Twitter API integration for monitoring and responding to mentions
35+
36+
## Setup
37+
38+
### Prerequisites
39+
40+
- Python 3.7+
41+
- Twitter API credentials (API Key/Secret, Access Token/Secret, and Bearer Token)
42+
- ThirdWeb API key for AskNebula service
43+
- OpenAI API key
44+
45+
### Installation
46+
47+
1. Clone the repository
48+
2. Install dependencies using `uv`:
49+
```
50+
uv pip install tweepy python-dotenv langchain langchain-openai thirdweb-ai pydantic
51+
```
52+
53+
3. Create a `.env` file with your API credentials (see `.env.example` for required variables)
54+
55+
## Usage
56+
57+
### Running the AskNebula Service Standalone
58+
59+
To use the AskNebula service directly:
60+
61+
```python
62+
from askNebula import NebulaAgent
63+
64+
# Initialize the agent
65+
agent = NebulaAgent()
66+
67+
# Run a query
68+
response = agent.run("What's the address for vitalik.eth?")
69+
print(response)
70+
```
71+
72+
### Running the Twitter Bot
73+
74+
To start the bot, simply run:
75+
```
76+
python twiiter_bot.py
77+
```
78+
79+
The bot will:
80+
1. Authenticate with Twitter
81+
2. Find the most recent mention and store its ID (without responding to it or any older mentions)
82+
3. Check for new mentions approximately every 90 seconds (respecting Twitter API Basic tier rate limits)
83+
4. Process any new mentions (created after the bot started) and reply with blockchain data
84+
5. Track the last processed mention to avoid duplicate responses
85+
86+
## How It Works
87+
88+
### Core AskNebula Service
89+
90+
The `NebulaAgent` class in `askNebula.py` provides blockchain data by:
91+
92+
1. Using ThirdWeb's Nebula service to access on-chain data
93+
2. Leveraging LangChain for agent-based interaction
94+
3. Using specialized tools for different types of blockchain queries:
95+
- Balance queries
96+
- ENS resolution
97+
- Transaction details
98+
- Off-topic handling
99+
100+
### Twitter Content Formatting
101+
102+
The `ContentCreator` class in `thread_creator.py`:
103+
104+
1. Processes the user's blockchain query
105+
2. Gets data from the AskNebula service
106+
3. Determines the best format for the response:
107+
- Thread (3 tweets) for complex data
108+
- Single post for simple responses
109+
- Clever responses for off-topic queries
110+
4. Formats the content according to Twitter's character limits and best practices
111+
112+
### Twitter Bot
113+
114+
The Twitter bot in `twiiter_bot.py`:
115+
116+
1. Monitors for new mentions
117+
2. Extracts the blockchain query from the tweet text
118+
3. Sends the query to the thread_creator module
119+
4. Posts the formatted response as a reply to the original mention
120+
5. Tracks processed mentions to avoid duplicate responses
121+
122+
## Rate Limits and Performance
123+
124+
The bot is designed to work within Twitter's Basic API tier limitations:
125+
- The mentions endpoint allows 10 requests per 15 minutes
126+
- The tweet creation endpoint allows 100 requests per 24 hours
127+
- The bot sleeps for 90 seconds between mention checks to stay under rate limits
128+
129+
## Troubleshooting
130+
131+
### Logs
132+
133+
Check `twitter_bot.log` for detailed information about the bot's operation and any errors encountered.
134+
135+
### Common Issues
136+
137+
- **Rate limits**: If you encounter rate limit errors, the bot will automatically wait before trying again
138+
- **Authentication issues**: Ensure your API keys and tokens are correct in the `.env` file
139+
- **Missing dependencies**: Make sure all required packages are installed with `uv`
140+
141+
## License
142+
143+
This project is licensed under the MIT License - see the LICENSE file for details.
144+
145+
## Contributing
146+
147+
Contributions are welcome! Please feel free to submit a Pull Request.

0 commit comments

Comments
 (0)