talos-agent · talos-agent · Jul 29, 2025 · Jul 29, 2025
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,9 +1,142 @@
 # Contributing
 
-When contributing to this repository, please ensure that your code passes all checks before submitting a pull request.
+Thank you for your interest in contributing to Talos! This document provides guidelines for contributing to the project.
 
-## Checks
+## Development Setup
 
-- `mypy`: Run `mypy .` to check for type errors.
-- `pytest`: Run `pytest` to run all tests.
-- `ruff`: Run `ruff .` to check for linting errors.
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/talos-agent/talos.git
+   cd talos
+   ```
+
+2. **Set up the development environment**:
+   ```bash
+   uv venv
+   source .venv/bin/activate
+   ./scripts/install_deps.sh
+   ```
+
+3. **Set up environment variables**:
+   ```bash
+   export OPENAI_API_KEY="your-openai-api-key"
+   export PINATA_API_KEY="your-pinata-api-key"
+   export PINATA_SECRET_API_KEY="your-pinata-secret-api-key"
+   # Optional for full functionality
+   export GITHUB_API_TOKEN="your-github-token"
+   export TWITTER_BEARER_TOKEN="your-twitter-bearer-token"
+   export ARBISCAN_API_KEY="your-arbiscan-api-key"
+   ```
+
+## Code Quality Checks
+
+Before submitting a pull request, ensure your code passes all checks:
+
+### Linting and Formatting
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+### Type Checking
+```bash
+uv run mypy src
+```
+
+### Testing
+```bash
+uv run pytest
+```
+
+### Run All Checks
+```bash
+./scripts/run_checks.sh
+```
+
+## Code Style Guidelines
+
+- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) for Python code
+- Use modern Python type hints (`list` and `dict` instead of `List` and `Dict`)
+- Never use quotes around type hints
+- Use type hints for all function signatures
+- Write clear and concise docstrings for modules, classes, and functions
+- Keep lines under 88 characters long
+- Use `model_post_init` for Pydantic `BaseModel` post-initialization logic
+- Organize imports: standard library, third-party, first-party
+- Use `ConfigDict` for Pydantic model configuration
+
+## Documentation Standards
+
+- Update documentation when adding new features
+- Include usage examples in CLI documentation
+- Ensure README files are accurate and up-to-date
+- Add docstrings to all public functions and classes
+- Update environment variable documentation when adding new requirements
+
+## Testing Guidelines
+
+- Write tests for all new functionality
+- Ensure existing tests continue to pass
+- Include both unit tests and integration tests where appropriate
+- Test error handling and edge cases
+- Mock external API calls in tests
+
+## Pull Request Process
+
+1. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** following the guidelines above
+
+3. **Run all checks** to ensure code quality
+
+4. **Commit your changes** with clear, descriptive commit messages
+
+5. **Push your branch** and create a pull request
+
+6. **Ensure CI passes** and address any feedback
+
+## Commit Message Guidelines
+
+- Use clear, descriptive commit messages
+- Start with a verb in the imperative mood
+- Keep the first line under 50 characters
+- Include additional details in the body if needed
+
+Examples:
+```
+Add memory search functionality to CLI
+
+Implement semantic search for agent memories with user filtering
+and configurable result limits. Includes both database and file
+backend support.
+```
+
+## Issue Reporting
+
+When reporting issues:
+- Use the issue templates when available
+- Provide clear reproduction steps
+- Include relevant environment information
+- Add logs or error messages when applicable
+
+## Feature Requests
+
+For feature requests:
+- Clearly describe the proposed functionality
+- Explain the use case and benefits
+- Consider implementation complexity
+- Discuss potential alternatives
+
+## Getting Help
+
+- Check existing documentation first
+- Search existing issues and discussions
+- Join our community channels for questions
+- Tag maintainers for urgent issues
+
+## License
+
+By contributing to Talos, you agree that your contributions will be licensed under the MIT License.
diff --git a/README.md b/README.md
@@ -60,7 +60,7 @@ Talos provides a set of services for interacting with various platforms:
 
 ## Development
 
-This project uses `uv` for dependency management.
+This project uses `uv` for dependency management and requires Python 3.12+.
 
 1.  Create a virtual environment:
 
@@ -95,6 +95,14 @@ uv run talos
 
 You can then interact with the agent in a continuous conversation. To exit, type `exit`.
 
+### Non-Interactive Mode
+
+Run a single query and exit:
+
+```bash
+uv run talos "your query here"
+```
+
 ### Daemon Mode
 
 To run the agent in daemon mode for continuous operation with scheduled jobs:
@@ -110,6 +118,25 @@ uv run talos daemon
 
 The daemon will run continuously, executing scheduled jobs and can be gracefully shutdown with SIGTERM or SIGINT.
 
+### Available CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `twitter` | Twitter-related operations and sentiment analysis |
+| `github` | GitHub repository management and PR reviews |
+| `proposals` | Governance proposal evaluation |
+| `memory` | Memory management and search operations |
+| `arbiscan` | Arbitrum blockchain contract source code retrieval |
+| `generate-keys` | Generate RSA key pairs for encryption |
+| `get-public-key` | Retrieve the current public key |
+| `encrypt` | Encrypt data using public key |
+| `decrypt` | Decrypt data using private key |
+| `daemon` | Run in continuous daemon mode |
+| `cleanup-users` | Clean up temporary users and conversation data |
+| `db-stats` | Show database statistics |
+
+For detailed command usage, see the [CLI Documentation](https://docs.talos.is/cli/overview/).
+
 ### Docker Usage
 
 #### Building and Running with Docker
@@ -170,11 +197,15 @@ The daemon will run continuously, executing scheduled jobs and can be gracefully
 #### Required Environment Variables
 
 - `OPENAI_API_KEY`: Required for AI functionality
-- `GITHUB_API_TOKEN`: Required for GitHub operations
-- `TWITTER_BEARER_TOKEN`: Required for Twitter functionality
 - `PINATA_API_KEY`: Required for IPFS operations
 - `PINATA_SECRET_API_KEY`: Required for IPFS operations
 
+#### Optional Environment Variables
+
+- `GITHUB_API_TOKEN`: Required for GitHub operations
+- `TWITTER_BEARER_TOKEN`: Required for Twitter functionality
+- `ARBISCAN_API_KEY`: Optional for higher rate limits when accessing Arbitrum contract data
+
 #### Graceful Shutdown
 
 The Docker container supports graceful shutdown. When you run `docker stop`, it sends a SIGTERM signal to the process, which triggers:

diff --git a/docs/cli/arbiscan.md b/docs/cli/arbiscan.md
@@ -0,0 +1,164 @@
+# Arbiscan CLI
+
+The Arbiscan CLI module provides commands for retrieving smart contract source code from Arbitrum blockchain networks.
+
+## Commands
+
+### `get-source-code` - Retrieve Contract Source Code
+
+Gets the source code of a verified smart contract from Arbiscan.
+
+```bash
+uv run talos arbiscan get-source-code <contract_address> [options]
+```
+
+**Arguments:**
+- `contract_address`: The contract address to get source code for (required)
+
+**Options:**
+- `--api-key, -k`: Optional API key for higher rate limits
+- `--chain-id, -c`: Chain ID (default: 42161 for Arbitrum One)
+- `--format, -f`: Output format - 'formatted', 'json', or 'source-only' (default: 'formatted')
+
+## Supported Networks
+
+| Chain ID | Network | Description |
+|----------|---------|-------------|
+| 42161 | Arbitrum One | Main Arbitrum network |
+| 42170 | Arbitrum Nova | Arbitrum Nova network |
+| 421614 | Arbitrum Sepolia | Arbitrum testnet |
+
+## Usage Examples
+
+### Basic Usage
+
+```bash
+# Get source code for a contract on Arbitrum One
+uv run talos arbiscan get-source-code 0x1234567890abcdef1234567890abcdef12345678
+
+# Get source code with API key for higher rate limits
+uv run talos arbiscan get-source-code 0x1234567890abcdef1234567890abcdef12345678 --api-key your_api_key
+```
+
+### Different Networks
+
+```bash
+# Get source code from Arbitrum Nova
+uv run talos arbiscan get-source-code 0x1234567890abcdef1234567890abcdef12345678 --chain-id 42170
+
+# Get source code from Arbitrum Sepolia testnet
+uv run talos arbiscan get-source-code 0x1234567890abcdef1234567890abcdef12345678 --chain-id 421614
+```
+
+### Output Formats
+
+```bash
+# Formatted output (default) - human-readable with contract details
+uv run talos arbiscan get-source-code 0x1234567890abcdef1234567890abcdef12345678 --format formatted
+
+# JSON output - structured data format
+uv run talos arbiscan get-source-code 0x1234567890abcdef1234567890abcdef12345678 --format json
+
+# Source code only - just the contract source code
+uv run talos arbiscan get-source-code 0x1234567890abcdef1234567890abcdef12345678 --format source-only
+```
+
+## Output Information
+
+### Formatted Output
+
+The formatted output includes:
+- **Contract Name**: Name of the smart contract
+- **Compiler Version**: Solidity compiler version used
+- **Optimization Used**: Whether compiler optimization was enabled
+- **Optimization Runs**: Number of optimization runs (if enabled)
+- **License Type**: Contract license information
+- **Proxy Implementation**: Implementation address (for proxy contracts)
+- **Source Code**: Complete contract source code
+
+### JSON Output
+
+The JSON output provides structured data with all contract information in a machine-readable format.
+
+### Source-Only Output
+
+Returns only the contract source code without additional metadata.
+
+## API Key Setup
+
+### Environment Variable
+
+Set your Arbiscan API key as an environment variable:
+
+```bash
+export ARBISCAN_API_KEY=your_api_key_here
+```
+
+### Command Line Option
+
+Alternatively, provide the API key directly:
+
+```bash
+uv run talos arbiscan get-source-code 0x1234... --api-key your_api_key_here
+```
+
+### Getting an API Key
+
+1. Visit [https://arbiscan.io/apis](https://arbiscan.io/apis)
+2. Create a free account
+3. Generate an API key
+4. Use the key for higher rate limits and better reliability
+
+## Rate Limits
+
+- **Without API Key**: Limited requests per minute
+- **With API Key**: Higher rate limits and better reliability
+- **Free Tier**: Sufficient for most use cases
+- **Paid Tiers**: Available for high-volume usage
+
+## Error Handling
+
+The command includes comprehensive error handling for:
+
+### API Errors
+- Missing or invalid API key
+- Rate limit exceeded
+- Invalid contract address
+- Contract not verified
+- Network connectivity issues
+
+### Input Validation
+- Invalid contract address format
+- Unsupported chain ID
+- Invalid output format
+
+### Example Error Messages
+
+```bash
+# Missing API key error
+Error: Arbiscan API key is required to get contract source code.
+Please provide an API key using the --api-key option.
+You can get a free API key from https://arbiscan.io/apis
+
+# Invalid contract address
+Error: Invalid contract address format
+
+# Contract not verified
+Error: Contract source code not verified on Arbiscan
+```
+
+## Integration
+
+The Arbiscan CLI integrates with:
+- Smart contract analysis workflows
+- Security audit processes
+- Development and debugging tools
+- Automated contract verification systems
+
+## Use Cases
+
+- **Security Analysis**: Review contract source code for vulnerabilities
+- **Development**: Study implementation patterns and best practices
+- **Auditing**: Verify contract functionality and security
+- **Research**: Analyze DeFi protocols and smart contract architectures
+- **Integration**: Retrieve contract ABIs and interfaces for development