# Helix - DeSci AI Agent
A powerful Python package for creating science-themed AI agents with advanced research and experimentation capabilities. Helix enables automated scientific workflows, experiment simulation, research paper analysis, and collaborative research.
## Table of Contents
- [Features Overview](#features-overview)
- [Benefits](#benefits)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration Parameters](#configuration-parameters)
- [Quick Start](#quick-start)
- [Usage Examples](#usage-examples)
- [Documentation](#documentation)
- [Development](#development)
- [Common Issues](#common-issues)
- [Support](#support)
## Features Overview
| Feature Category | Functionality | Description | Key Benefits |
|-----------------|---------------|-------------|--------------|
| **Core AI** | Agent Personas | Specialized agents (physicist, biologist, etc.) | Domain-specific expertise and terminology |
| | Context Management | Maintains conversation history | Coherent, context-aware interactions |
| | Multi-Agent Collaboration | Agent-to-agent interactions | Cross-disciplinary research insights |
| | Async Processing | Non-blocking operations | Efficient handling of complex tasks |
| **Machine Learning** | Model Training | Train and tune ML models | Automated model optimization |
| | Model Evaluation | Comprehensive performance metrics | Rigorous model assessment |
| | Feature Analysis | Importance analysis and selection | Data-driven insights |
| | Model Management | Save and load trained models | Reproducible ML workflows |
| **Data Management** | Data Validation | Validate datasets against rules | Data quality assurance |
| | Data Cleaning | Automated cleaning operations | Consistent data preparation |
| | Format Conversion | Convert between data formats | Flexible data handling |
| | Version Control | Track dataset versions | Data lineage management |
| **Research Tools** | Task Planning | Create and track research plans | Structured research management |
| | Experiment Management | Design and run experiments | Reproducible scientific workflows |
| | Paper Analysis | Extract metadata from papers | Efficient literature review |
| | Citation Handling | Format scientific citations | Proper academic documentation |
| | Data Analysis | Statistical analysis with confidence intervals | Rigorous scientific analysis |
| **Collaboration** | Git Integration | Version control management | Code collaboration |
| | Jupyter Integration | Create notebooks programmatically | Interactive documentation |
| | Report Generation | Generate Markdown reports | Automated documentation |
| | Change Tracking | Track document changes | Version management |
| **Social Integration** | Twitter Integration | Post updates and track engagement | Research communication |
| | Media Sharing | Share images and graphs | Visual result sharing |
| | Engagement Analytics | Track social media metrics | Impact assessment |
## Tool Classes
Helix provides several specialized tool classes for different aspects of scientific research:
### MLTools
Machine learning utilities for model development and evaluation:
```python
from helix_agent.tools import MLTools
# Prepare data
data = MLTools.prepare_data(X, y, test_size=0.2)
# Train model with hyperparameter tuning
model = RandomForestClassifier()
param_grid = {'n_estimators': [100, 200], 'max_depth': [10, 20]}
results = MLTools.train_model(model, data['X_train'], data['y_train'], param_grid=param_grid)
# Evaluate model
metrics = MLTools.evaluate_model(results['model'], data['X_test'], data['y_test'])
print(f"Accuracy: {metrics['accuracy']}")
```
### DataTools
Data management and quality control utilities:
```python
from helix_agent.tools import DataTools
# Validate dataset
rules = {
'dtypes': {'A': 'float64', 'B': 'object'},
'required_columns': ['A', 'B']
}
validation = DataTools.validate_dataset(data, rules)
# Clean dataset
operations = [
{'type': 'remove_duplicates'},
{'type': 'fill_missing', 'method': 'mean'}
]
cleaned = DataTools.clean_dataset(data, operations)
```
### ResearchTools
Tools for research paper analysis and literature review:
```python
from helix_agent.tools import ResearchTools
# Search ArXiv
papers = ResearchTools.search_arxiv("quantum computing", max_results=5)
# Generate citation graph
graph = ResearchTools.generate_citation_graph(papers)
# Summarize literature
summary = ResearchTools.summarize_literature(papers)
```
### CollaborationTools
Utilities for collaboration and documentation:
```python
from helix_agent.tools import CollaborationTools
# Generate report
content = {
'title': 'Research Results',
'methods': ['Method 1', 'Method 2'],
'results': {'accuracy': 0.95}
}
report = CollaborationTools.generate_markdown_report(content)
# Track changes
original = "Initial results"
modified = "Updated results"
diff = CollaborationTools.track_changes(original, modified)
```
## Benefits
| Use Case | Benefits | Example Application |
|----------|----------|-------------------|
| **Research Planning** | - Structured workflow<br>- Progress tracking<br>- Dependency management | Planning multi-phase experiments |
| **Experimentation** | - Protocol standardization<br>- Result reproducibility<br>- Statistical rigor | Running controlled experiments |
| **Literature Review** | - Automated metadata extraction<br>- Citation management<br>- Content summarization | Analyzing research papers |
| **Collaboration** | - Cross-discipline interaction<br>- Knowledge sharing<br>- Unified analysis | Multi-team research projects |
| **Communication** | - Automated updates<br>- Engagement tracking<br>- Media management | Sharing research findings |
## Prerequisites
| Requirement | Version | Required | Notes |
|------------|---------|----------|--------|
| Python | ≥3.8 | Yes | For modern language features |
| OpenAI API Key | N/A | Yes | For AI capabilities |
| Twitter API Credentials | N/A | No | Only for social features |
## Installation
### From PyPI (Recommended)
```bash
# Install basic package
pip install helix-agent
# Install with development tools
pip install helix-agent[dev]
```
### From Source
```bash
# Clone repository
git clone https://github.com/helixagent/helix-agent.git
cd helix_agent
# Install in development mode
pip install -e .
# Install development dependencies
pip install -e ".[dev]"
```
### Environment Setup
1. Create a virtual environment (recommended):
```bash
python -m venv venv
source venv/bin/activate # Linux/Mac
venv\Scripts\activate # Windows
```
2. Set up API keys:
```bash
# Linux/Mac
export OPENAI_API_KEY="your-key-here"
export TWITTER_API_KEY="your-key-here"
export TWITTER_API_SECRET="your-secret-here"
export TWITTER_ACCESS_TOKEN="your-token-here"
export TWITTER_ACCESS_SECRET="your-secret-here"
# Windows
set OPENAI_API_KEY=your-key-here
set TWITTER_API_KEY=your-key-here
set TWITTER_API_SECRET=your-secret-here
set TWITTER_ACCESS_TOKEN=your-token-here
set TWITTER_ACCESS_SECRET=your-secret-here
```
## Configuration Parameters
### HelixAgent Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| agent_name | str | No | "Default Scientist" | Name/role of the AI agent |
| model_name | str | No | "helix-70b" | AI model to use |
| tools_enabled | bool | No | True | Enable scientific tools |
| interactive | bool | No | True | Enable interactive mode |
| streaming_on | bool | No | True | Enable response streaming |
| temperature | float | No | 0.7 | Response randomness (0-1) |
| max_tokens | int | No | 150 | Maximum response length |
| use_context | bool | No | True | Enable conversation memory |
| persona | str | No | None | Predefined role (physicist/biologist) |
| logging_enabled | bool | No | False | Enable activity logging |
| api_key | str | Yes* | None | OpenAI API key (*can be set via env var) |
| twitter_config | dict | No | None | Twitter API credentials |
### Twitter Configuration
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| api_key | str | Yes | Twitter API Key |
| api_secret | str | Yes | Twitter API Secret |
| access_token | str | Yes | Twitter Access Token |
| access_token_secret | str | Yes | Twitter Access Token Secret |
## Quick Start
1. Set up your OpenAI API key:
```python
import os
os.environ["OPENAI_API_KEY"] = "your-api-key-here"
```
2. Create a basic agent:
```python
from helix_agent import HelixAgent
agent = HelixAgent(
agent_name="Research Scientist",
model_name="helix-70b",
tools_enabled=True
)
```
3. Run an experiment:
```python
# Create protocol
protocol = agent.create_experiment(
steps=["Sample preparation", "Data collection"],
materials=["Reagent A", "Equipment B"],
duration="2 hours",
conditions={"temperature": 25}
)
# Run experiment
results = agent.run_experiment(
protocol=protocol,
variables={"concentration": 0.5},
iterations=3
)
# Analyze results
analysis = agent.analyze_data(
[r['variables']['concentration'] for r in results['results']]
)
```
## Core Methods
| Method | Purpose | Key Parameters | Return Value |
|--------|---------|----------------|--------------|
| create_experiment | Design experiment protocol | steps, materials, duration, conditions | Protocol dict |
| run_experiment | Execute experiment | protocol, variables, iterations | Results dict |
| analyze_data | Statistical analysis | data, confidence_level | Analysis dict |
| plan_research_task | Create research plan | objective, subtasks, dependencies | Plan dict |
| analyze_paper | Extract paper metadata | paper_text | Metadata dict |
| format_citation | Format citation | authors, title, journal, year, doi | Citation string |
| post_tweet | Share updates | content, media_paths | Tweet metadata |
| collaborate | Multi-agent discussion | other_agent, prompt, turns | Discussion string |
## Basic Agent Usage
### Initialize Agent
```python
from helix_agent import HelixAgent
# Basic initialization
agent = HelixAgent(
agent_name="Research Scientist",
model_name="helix-70b",
tools_enabled=True
)
# With persona
physicist = HelixAgent(
persona="physicist",
temperature=0.7,
max_tokens=200
)
# With logging
logged_agent = HelixAgent(
agent_name="Logged Scientist",
logging_enabled=True,
log_file="research.log"
)
```
### Generate Responses
```python
# Basic response
response = agent.generate_response(
"Explain the double-slit experiment"
)
# With streaming
streaming_agent = HelixAgent(streaming_on=True)
response = streaming_agent.generate_response(
"Describe quantum entanglement"
)
# Using context
agent.generate_response("What is dark matter?")
followup = agent.generate_response("How is it detected?") # Uses previous context
```
## Research Tools
### Task Planning
```python
# Simple task plan
basic_plan = agent.plan_research_task(
objective="Study protein folding",
subtasks=[
"Review literature",
"Design experiments",
"Collect data"
]
)
# Complex plan with dependencies
complex_plan = agent.plan_research_task(
objective="Investigate quantum tunneling in enzymes",
subtasks=[
"Literature review on quantum biology",
"Identify key enzymes",
"Design detection method",
"Setup equipment",
"Run experiments",
"Analyze results"
],
dependencies={
"task-2": ["task-1"],
"task-3": ["task-2"],
"task-4": ["task-3"],
"task-5": ["task-4"],
"task-6": ["task-5"]
}
)
# Update progress
updated_plan = agent.update_task_progress(
["task-1", "task-2"] # Completed tasks
)
print(f"Progress: {updated_plan['progress']}%")
```
## Usage Examples
### Create Experiment Protocol
```python
# Basic protocol
simple_protocol = agent.create_experiment(
steps=[
"Prepare samples",
"Run analysis"
],
materials=[
"Sample A",
"Buffer solution"
],
duration="1 hour",
conditions={"temperature": 25}
)
# Detailed protocol
detailed_protocol = agent.create_experiment(
steps=[
"Prepare protein samples in phosphate buffer",
"Calibrate spectrophotometer",
"Measure baseline absorbance",
"Add substrate incrementally",
"Record kinetic measurements",
"Analyze reaction rates"
],
materials=[
"Purified enzyme (1mg/mL)",
"Phosphate buffer (pH 7.4)",
"Substrate solution (10mM)",
"UV-Vis spectrophotometer",
"Temperature-controlled cuvette holder",
"Micropipettes"
],
duration="3 hours",
conditions={
"temperature": 37,
"pH": 7.4,
"buffer_concentration": 50,
"ionic_strength": 0.15
}
)
```
### Run Experiments
```python
# Single condition
results = agent.run_experiment(
protocol=simple_protocol,
variables={"concentration": 0.5},
iterations=3
)
# Multiple conditions
complex_results = agent.run_experiment(
protocol=detailed_protocol,
variables={
"enzyme_concentration": 0.1,
"substrate_concentration": 1.0,
"temperature": 37
},
iterations=5
)
# Analyze results
analysis = agent.analyze_data(
[r['variables']['enzyme_concentration'] for r in complex_results['results']],
confidence_level=0.95
)
print(f"Mean: {analysis['mean']}")
print(f"Standard Deviation: {analysis['std_dev']}")
print(f"Confidence Interval: {analysis['confidence_interval']}")
```
## Paper Analysis
### Extract Metadata
```python
# Basic paper
paper_text = """
Title: Quantum Effects in Biological Systems
Abstract: This study investigates quantum phenomena in biological processes.
Keywords: quantum biology, coherence, entanglement
"""
metadata = agent.analyze_paper(paper_text)
# Complex paper with references
complex_paper = """
Title: Advanced Quantum Biology Studies
Abstract: A comprehensive review of quantum effects in biological systems,
focusing on photosynthesis and enzyme catalysis.
Keywords: quantum biology, photosynthesis, enzymes, coherence
References:
1. Smith et al. (2022) Nature Physics
2. Johnson et al. (2023) Quantum Biology Review
"""
metadata = agent.analyze_paper(complex_paper)
```
### Format Citations
```python
# Basic citation
citation = agent.format_citation(
authors=["Smith, J.", "Johnson, M."],
title="Quantum Effects in Biology",
journal="Nature Physics",
year=2023
)
# With DOI
citation_with_doi = agent.format_citation(
authors=["Smith, J.", "Johnson, M.", "Williams, R."],
title="Advanced Quantum Biology",
journal="Science",
year=2023,
doi="10.1234/science.2023.001"
)
```
## Social Media Integration
### Post Updates
```python
# Basic tweet
agent.post_tweet(
"Exciting new results from our quantum biology experiments! 🧬✨"
)
# With media
agent.post_tweet(
"Our latest findings on quantum coherence in photosynthesis! 🌱\n"
"Check out these amazing results! #SciComm #QuantumBiology",
media_paths=["results_graph.png", "experiment_setup.jpg"]
)
# Schedule tweet
from datetime import datetime, timedelta
future = datetime.now() + timedelta(days=1)
agent.schedule_tweet(
"Join us tomorrow for our quantum biology seminar! 🎓",
scheduled_time=future
)
```
### Analyze Engagement
```python
# Get recent tweets
history = agent.get_tweet_history(count=5)
# Analyze engagement
for tweet in history:
metrics = agent.analyze_tweet_engagement(tweet['id'])
print(f"Tweet: {tweet['content']}")
print(f"Likes: {metrics['likes']}")
print(f"Retweets: {metrics['retweets']}")
```
## Multi-Agent Collaboration
### Basic Collaboration
```python
# Create specialized agents
physicist = HelixAgent(persona="physicist")
biologist = HelixAgent(persona="biologist")
# Simple discussion
discussion = physicist.collaborate(
other_agent=biologist,
prompt="Discuss quantum effects in photosynthesis",
turns=3
)
```
### Complex Collaboration
```python
# Create team of specialists
physicist = HelixAgent(persona="physicist")
biologist = HelixAgent(persona="biologist")
chemist = HelixAgent(persona="chemist")
# Sequential collaboration
physics_view = physicist.generate_response(
"Explain quantum tunneling in enzyme catalysis"
)
biology_view = biologist.generate_response(
f"Based on this physics explanation: {physics_view}\n"
"How might this affect enzyme function?"
)
chemistry_view = chemist.generate_response(
f"Given these insights:\n"
f"Physics: {physics_view}\n"
f"Biology: {biology_view}\n"
"What chemical techniques could we use to detect this?"
)
# Collaborative experiment
protocol = physicist.create_experiment(
steps=["Setup quantum detection", "Prepare enzymes", "Measure activity"],
materials=["Quantum sensor", "Enzyme samples"],
duration="5 hours",
conditions={"temperature": 5} # Low temp for quantum effects
)
physics_results = physicist.run_experiment(
protocol=protocol,
variables={"tunneling_rate": 0.1},
iterations=3
)
biology_analysis = biologist.analyze_data(
[r['variables']['tunneling_rate'] for r in physics_results['results']]
)
chemistry_insights = chemist.generate_response(
f"Analyze these results from chemical perspective:\n"
f"Physics data: {physics_results['summary_stats']}\n"
f"Biology analysis: {biology_analysis}"
)
```
## Documentation
Detailed documentation for each feature is available in the `docs/` directory.
## Development
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest tests/
# Format code
black helix_agent/
isort helix_agent/
```
## Common Issues and Solutions
| Issue | Cause | Solution |
|-------|-------|----------|
| OpenAI API Error | Invalid/missing API key | Set OPENAI_API_KEY environment variable |
| Twitter API Error | Invalid credentials | Verify Twitter API credentials |
| Import Error | Missing dependencies | Install required packages |
| Memory Issues | Large experiments | Reduce batch size/iterations |
| Rate Limits | Too many API calls | Implement request throttling |
## Support
- Report bugs through [GitHub Issues](https://github.com/helixagent/helix-agent/issues)
- Check documentation in the `docs/` directory
- Review examples in the `examples/` directory
## License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/helixagent/helix-agent",
"name": "helix-agent",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "AI, OpenAI, science, research, agents, GPT, Helix, DeSci, experiments, analysis, machine learning, data science, collaboration",
"author": "Helix Agent",
"author_email": "helixagentsol@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/89/d0/b3c41a8484fd7651dab37e101f01902b2b2d34793328046c5a3550831af9/helix_agent-1.2.0.tar.gz",
"platform": null,
"description": "# Helix - DeSci AI Agent\r\n\r\nA powerful Python package for creating science-themed AI agents with advanced research and experimentation capabilities. Helix enables automated scientific workflows, experiment simulation, research paper analysis, and collaborative research.\r\n\r\n## Table of Contents\r\n- [Features Overview](#features-overview)\r\n- [Benefits](#benefits)\r\n- [Prerequisites](#prerequisites)\r\n- [Installation](#installation)\r\n- [Configuration Parameters](#configuration-parameters)\r\n- [Quick Start](#quick-start)\r\n- [Usage Examples](#usage-examples)\r\n- [Documentation](#documentation)\r\n- [Development](#development)\r\n- [Common Issues](#common-issues)\r\n- [Support](#support)\r\n\r\n## Features Overview\r\n\r\n| Feature Category | Functionality | Description | Key Benefits |\r\n|-----------------|---------------|-------------|--------------|\r\n| **Core AI** | Agent Personas | Specialized agents (physicist, biologist, etc.) | Domain-specific expertise and terminology |\r\n| | Context Management | Maintains conversation history | Coherent, context-aware interactions |\r\n| | Multi-Agent Collaboration | Agent-to-agent interactions | Cross-disciplinary research insights |\r\n| | Async Processing | Non-blocking operations | Efficient handling of complex tasks |\r\n| **Machine Learning** | Model Training | Train and tune ML models | Automated model optimization |\r\n| | Model Evaluation | Comprehensive performance metrics | Rigorous model assessment |\r\n| | Feature Analysis | Importance analysis and selection | Data-driven insights |\r\n| | Model Management | Save and load trained models | Reproducible ML workflows |\r\n| **Data Management** | Data Validation | Validate datasets against rules | Data quality assurance |\r\n| | Data Cleaning | Automated cleaning operations | Consistent data preparation |\r\n| | Format Conversion | Convert between data formats | Flexible data handling |\r\n| | Version Control | Track dataset versions | Data lineage management |\r\n| **Research Tools** | Task Planning | Create and track research plans | Structured research management |\r\n| | Experiment Management | Design and run experiments | Reproducible scientific workflows |\r\n| | Paper Analysis | Extract metadata from papers | Efficient literature review |\r\n| | Citation Handling | Format scientific citations | Proper academic documentation |\r\n| | Data Analysis | Statistical analysis with confidence intervals | Rigorous scientific analysis |\r\n| **Collaboration** | Git Integration | Version control management | Code collaboration |\r\n| | Jupyter Integration | Create notebooks programmatically | Interactive documentation |\r\n| | Report Generation | Generate Markdown reports | Automated documentation |\r\n| | Change Tracking | Track document changes | Version management |\r\n| **Social Integration** | Twitter Integration | Post updates and track engagement | Research communication |\r\n| | Media Sharing | Share images and graphs | Visual result sharing |\r\n| | Engagement Analytics | Track social media metrics | Impact assessment |\r\n\r\n## Tool Classes\r\n\r\nHelix provides several specialized tool classes for different aspects of scientific research:\r\n\r\n### MLTools\r\nMachine learning utilities for model development and evaluation:\r\n```python\r\nfrom helix_agent.tools import MLTools\r\n\r\n# Prepare data\r\ndata = MLTools.prepare_data(X, y, test_size=0.2)\r\n\r\n# Train model with hyperparameter tuning\r\nmodel = RandomForestClassifier()\r\nparam_grid = {'n_estimators': [100, 200], 'max_depth': [10, 20]}\r\nresults = MLTools.train_model(model, data['X_train'], data['y_train'], param_grid=param_grid)\r\n\r\n# Evaluate model\r\nmetrics = MLTools.evaluate_model(results['model'], data['X_test'], data['y_test'])\r\nprint(f\"Accuracy: {metrics['accuracy']}\")\r\n```\r\n\r\n### DataTools\r\nData management and quality control utilities:\r\n```python\r\nfrom helix_agent.tools import DataTools\r\n\r\n# Validate dataset\r\nrules = {\r\n 'dtypes': {'A': 'float64', 'B': 'object'},\r\n 'required_columns': ['A', 'B']\r\n}\r\nvalidation = DataTools.validate_dataset(data, rules)\r\n\r\n# Clean dataset\r\noperations = [\r\n {'type': 'remove_duplicates'},\r\n {'type': 'fill_missing', 'method': 'mean'}\r\n]\r\ncleaned = DataTools.clean_dataset(data, operations)\r\n```\r\n\r\n### ResearchTools\r\nTools for research paper analysis and literature review:\r\n```python\r\nfrom helix_agent.tools import ResearchTools\r\n\r\n# Search ArXiv\r\npapers = ResearchTools.search_arxiv(\"quantum computing\", max_results=5)\r\n\r\n# Generate citation graph\r\ngraph = ResearchTools.generate_citation_graph(papers)\r\n\r\n# Summarize literature\r\nsummary = ResearchTools.summarize_literature(papers)\r\n```\r\n\r\n### CollaborationTools\r\nUtilities for collaboration and documentation:\r\n```python\r\nfrom helix_agent.tools import CollaborationTools\r\n\r\n# Generate report\r\ncontent = {\r\n 'title': 'Research Results',\r\n 'methods': ['Method 1', 'Method 2'],\r\n 'results': {'accuracy': 0.95}\r\n}\r\nreport = CollaborationTools.generate_markdown_report(content)\r\n\r\n# Track changes\r\noriginal = \"Initial results\"\r\nmodified = \"Updated results\"\r\ndiff = CollaborationTools.track_changes(original, modified)\r\n```\r\n\r\n## Benefits\r\n\r\n| Use Case | Benefits | Example Application |\r\n|----------|----------|-------------------|\r\n| **Research Planning** | - Structured workflow<br>- Progress tracking<br>- Dependency management | Planning multi-phase experiments |\r\n| **Experimentation** | - Protocol standardization<br>- Result reproducibility<br>- Statistical rigor | Running controlled experiments |\r\n| **Literature Review** | - Automated metadata extraction<br>- Citation management<br>- Content summarization | Analyzing research papers |\r\n| **Collaboration** | - Cross-discipline interaction<br>- Knowledge sharing<br>- Unified analysis | Multi-team research projects |\r\n| **Communication** | - Automated updates<br>- Engagement tracking<br>- Media management | Sharing research findings |\r\n\r\n## Prerequisites\r\n\r\n| Requirement | Version | Required | Notes |\r\n|------------|---------|----------|--------|\r\n| Python | \u00e2\u2030\u00a53.8 | Yes | For modern language features |\r\n| OpenAI API Key | N/A | Yes | For AI capabilities |\r\n| Twitter API Credentials | N/A | No | Only for social features |\r\n\r\n## Installation\r\n\r\n### From PyPI (Recommended)\r\n\r\n```bash\r\n# Install basic package\r\npip install helix-agent\r\n\r\n# Install with development tools\r\npip install helix-agent[dev]\r\n```\r\n\r\n### From Source\r\n\r\n```bash\r\n# Clone repository\r\ngit clone https://github.com/helixagent/helix-agent.git\r\ncd helix_agent\r\n\r\n# Install in development mode\r\npip install -e .\r\n\r\n# Install development dependencies\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Environment Setup\r\n\r\n1. Create a virtual environment (recommended):\r\n```bash\r\npython -m venv venv\r\nsource venv/bin/activate # Linux/Mac\r\nvenv\\Scripts\\activate # Windows\r\n```\r\n\r\n2. Set up API keys:\r\n```bash\r\n# Linux/Mac\r\nexport OPENAI_API_KEY=\"your-key-here\"\r\nexport TWITTER_API_KEY=\"your-key-here\"\r\nexport TWITTER_API_SECRET=\"your-secret-here\"\r\nexport TWITTER_ACCESS_TOKEN=\"your-token-here\"\r\nexport TWITTER_ACCESS_SECRET=\"your-secret-here\"\r\n\r\n# Windows\r\nset OPENAI_API_KEY=your-key-here\r\nset TWITTER_API_KEY=your-key-here\r\nset TWITTER_API_SECRET=your-secret-here\r\nset TWITTER_ACCESS_TOKEN=your-token-here\r\nset TWITTER_ACCESS_SECRET=your-secret-here\r\n```\r\n\r\n## Configuration Parameters\r\n\r\n### HelixAgent Parameters\r\n\r\n| Parameter | Type | Required | Default | Description |\r\n|-----------|------|----------|---------|-------------|\r\n| agent_name | str | No | \"Default Scientist\" | Name/role of the AI agent |\r\n| model_name | str | No | \"helix-70b\" | AI model to use |\r\n| tools_enabled | bool | No | True | Enable scientific tools |\r\n| interactive | bool | No | True | Enable interactive mode |\r\n| streaming_on | bool | No | True | Enable response streaming |\r\n| temperature | float | No | 0.7 | Response randomness (0-1) |\r\n| max_tokens | int | No | 150 | Maximum response length |\r\n| use_context | bool | No | True | Enable conversation memory |\r\n| persona | str | No | None | Predefined role (physicist/biologist) |\r\n| logging_enabled | bool | No | False | Enable activity logging |\r\n| api_key | str | Yes* | None | OpenAI API key (*can be set via env var) |\r\n| twitter_config | dict | No | None | Twitter API credentials |\r\n\r\n### Twitter Configuration\r\n\r\n| Parameter | Type | Required | Description |\r\n|-----------|------|----------|-------------|\r\n| api_key | str | Yes | Twitter API Key |\r\n| api_secret | str | Yes | Twitter API Secret |\r\n| access_token | str | Yes | Twitter Access Token |\r\n| access_token_secret | str | Yes | Twitter Access Token Secret |\r\n\r\n## Quick Start\r\n\r\n1. Set up your OpenAI API key:\r\n\r\n```python\r\nimport os\r\nos.environ[\"OPENAI_API_KEY\"] = \"your-api-key-here\"\r\n```\r\n\r\n2. Create a basic agent:\r\n\r\n```python\r\nfrom helix_agent import HelixAgent\r\n\r\nagent = HelixAgent(\r\n agent_name=\"Research Scientist\",\r\n model_name=\"helix-70b\",\r\n tools_enabled=True\r\n)\r\n```\r\n\r\n3. Run an experiment:\r\n\r\n```python\r\n# Create protocol\r\nprotocol = agent.create_experiment(\r\n steps=[\"Sample preparation\", \"Data collection\"],\r\n materials=[\"Reagent A\", \"Equipment B\"],\r\n duration=\"2 hours\",\r\n conditions={\"temperature\": 25}\r\n)\r\n\r\n# Run experiment\r\nresults = agent.run_experiment(\r\n protocol=protocol,\r\n variables={\"concentration\": 0.5},\r\n iterations=3\r\n)\r\n\r\n# Analyze results\r\nanalysis = agent.analyze_data(\r\n [r['variables']['concentration'] for r in results['results']]\r\n)\r\n```\r\n\r\n## Core Methods\r\n\r\n| Method | Purpose | Key Parameters | Return Value |\r\n|--------|---------|----------------|--------------|\r\n| create_experiment | Design experiment protocol | steps, materials, duration, conditions | Protocol dict |\r\n| run_experiment | Execute experiment | protocol, variables, iterations | Results dict |\r\n| analyze_data | Statistical analysis | data, confidence_level | Analysis dict |\r\n| plan_research_task | Create research plan | objective, subtasks, dependencies | Plan dict |\r\n| analyze_paper | Extract paper metadata | paper_text | Metadata dict |\r\n| format_citation | Format citation | authors, title, journal, year, doi | Citation string |\r\n| post_tweet | Share updates | content, media_paths | Tweet metadata |\r\n| collaborate | Multi-agent discussion | other_agent, prompt, turns | Discussion string |\r\n\r\n## Basic Agent Usage\r\n\r\n### Initialize Agent\r\n\r\n```python\r\nfrom helix_agent import HelixAgent\r\n\r\n# Basic initialization\r\nagent = HelixAgent(\r\n agent_name=\"Research Scientist\",\r\n model_name=\"helix-70b\",\r\n tools_enabled=True\r\n)\r\n\r\n# With persona\r\nphysicist = HelixAgent(\r\n persona=\"physicist\",\r\n temperature=0.7,\r\n max_tokens=200\r\n)\r\n\r\n# With logging\r\nlogged_agent = HelixAgent(\r\n agent_name=\"Logged Scientist\",\r\n logging_enabled=True,\r\n log_file=\"research.log\"\r\n)\r\n```\r\n\r\n### Generate Responses\r\n\r\n```python\r\n# Basic response\r\nresponse = agent.generate_response(\r\n \"Explain the double-slit experiment\"\r\n)\r\n\r\n# With streaming\r\nstreaming_agent = HelixAgent(streaming_on=True)\r\nresponse = streaming_agent.generate_response(\r\n \"Describe quantum entanglement\"\r\n)\r\n\r\n# Using context\r\nagent.generate_response(\"What is dark matter?\")\r\nfollowup = agent.generate_response(\"How is it detected?\") # Uses previous context\r\n```\r\n\r\n## Research Tools\r\n\r\n### Task Planning\r\n\r\n```python\r\n# Simple task plan\r\nbasic_plan = agent.plan_research_task(\r\n objective=\"Study protein folding\",\r\n subtasks=[\r\n \"Review literature\",\r\n \"Design experiments\",\r\n \"Collect data\"\r\n ]\r\n)\r\n\r\n# Complex plan with dependencies\r\ncomplex_plan = agent.plan_research_task(\r\n objective=\"Investigate quantum tunneling in enzymes\",\r\n subtasks=[\r\n \"Literature review on quantum biology\",\r\n \"Identify key enzymes\",\r\n \"Design detection method\",\r\n \"Setup equipment\",\r\n \"Run experiments\",\r\n \"Analyze results\"\r\n ],\r\n dependencies={\r\n \"task-2\": [\"task-1\"],\r\n \"task-3\": [\"task-2\"],\r\n \"task-4\": [\"task-3\"],\r\n \"task-5\": [\"task-4\"],\r\n \"task-6\": [\"task-5\"]\r\n }\r\n)\r\n\r\n# Update progress\r\nupdated_plan = agent.update_task_progress(\r\n [\"task-1\", \"task-2\"] # Completed tasks\r\n)\r\nprint(f\"Progress: {updated_plan['progress']}%\")\r\n```\r\n\r\n## Usage Examples\r\n\r\n### Create Experiment Protocol\r\n\r\n```python\r\n# Basic protocol\r\nsimple_protocol = agent.create_experiment(\r\n steps=[\r\n \"Prepare samples\",\r\n \"Run analysis\"\r\n ],\r\n materials=[\r\n \"Sample A\",\r\n \"Buffer solution\"\r\n ],\r\n duration=\"1 hour\",\r\n conditions={\"temperature\": 25}\r\n)\r\n\r\n# Detailed protocol\r\ndetailed_protocol = agent.create_experiment(\r\n steps=[\r\n \"Prepare protein samples in phosphate buffer\",\r\n \"Calibrate spectrophotometer\",\r\n \"Measure baseline absorbance\",\r\n \"Add substrate incrementally\",\r\n \"Record kinetic measurements\",\r\n \"Analyze reaction rates\"\r\n ],\r\n materials=[\r\n \"Purified enzyme (1mg/mL)\",\r\n \"Phosphate buffer (pH 7.4)\",\r\n \"Substrate solution (10mM)\",\r\n \"UV-Vis spectrophotometer\",\r\n \"Temperature-controlled cuvette holder\",\r\n \"Micropipettes\"\r\n ],\r\n duration=\"3 hours\",\r\n conditions={\r\n \"temperature\": 37,\r\n \"pH\": 7.4,\r\n \"buffer_concentration\": 50,\r\n \"ionic_strength\": 0.15\r\n }\r\n)\r\n```\r\n\r\n### Run Experiments\r\n\r\n```python\r\n# Single condition\r\nresults = agent.run_experiment(\r\n protocol=simple_protocol,\r\n variables={\"concentration\": 0.5},\r\n iterations=3\r\n)\r\n\r\n# Multiple conditions\r\ncomplex_results = agent.run_experiment(\r\n protocol=detailed_protocol,\r\n variables={\r\n \"enzyme_concentration\": 0.1,\r\n \"substrate_concentration\": 1.0,\r\n \"temperature\": 37\r\n },\r\n iterations=5\r\n)\r\n\r\n# Analyze results\r\nanalysis = agent.analyze_data(\r\n [r['variables']['enzyme_concentration'] for r in complex_results['results']],\r\n confidence_level=0.95\r\n)\r\n\r\nprint(f\"Mean: {analysis['mean']}\")\r\nprint(f\"Standard Deviation: {analysis['std_dev']}\")\r\nprint(f\"Confidence Interval: {analysis['confidence_interval']}\")\r\n```\r\n\r\n## Paper Analysis\r\n\r\n### Extract Metadata\r\n\r\n```python\r\n# Basic paper\r\npaper_text = \"\"\"\r\nTitle: Quantum Effects in Biological Systems\r\nAbstract: This study investigates quantum phenomena in biological processes.\r\nKeywords: quantum biology, coherence, entanglement\r\n\"\"\"\r\n\r\nmetadata = agent.analyze_paper(paper_text)\r\n\r\n# Complex paper with references\r\ncomplex_paper = \"\"\"\r\nTitle: Advanced Quantum Biology Studies\r\nAbstract: A comprehensive review of quantum effects in biological systems,\r\nfocusing on photosynthesis and enzyme catalysis.\r\nKeywords: quantum biology, photosynthesis, enzymes, coherence\r\nReferences:\r\n1. Smith et al. (2022) Nature Physics\r\n2. Johnson et al. (2023) Quantum Biology Review\r\n\"\"\"\r\n\r\nmetadata = agent.analyze_paper(complex_paper)\r\n```\r\n\r\n### Format Citations\r\n\r\n```python\r\n# Basic citation\r\ncitation = agent.format_citation(\r\n authors=[\"Smith, J.\", \"Johnson, M.\"],\r\n title=\"Quantum Effects in Biology\",\r\n journal=\"Nature Physics\",\r\n year=2023\r\n)\r\n\r\n# With DOI\r\ncitation_with_doi = agent.format_citation(\r\n authors=[\"Smith, J.\", \"Johnson, M.\", \"Williams, R.\"],\r\n title=\"Advanced Quantum Biology\",\r\n journal=\"Science\",\r\n year=2023,\r\n doi=\"10.1234/science.2023.001\"\r\n)\r\n```\r\n\r\n## Social Media Integration\r\n\r\n### Post Updates\r\n\r\n```python\r\n# Basic tweet\r\nagent.post_tweet(\r\n \"Exciting new results from our quantum biology experiments! \u00f0\u0178\u00a7\u00ac\u00e2\u0153\u00a8\"\r\n)\r\n\r\n# With media\r\nagent.post_tweet(\r\n \"Our latest findings on quantum coherence in photosynthesis! \u00f0\u0178\u0152\u00b1\\n\"\r\n \"Check out these amazing results! #SciComm #QuantumBiology\",\r\n media_paths=[\"results_graph.png\", \"experiment_setup.jpg\"]\r\n)\r\n\r\n# Schedule tweet\r\nfrom datetime import datetime, timedelta\r\nfuture = datetime.now() + timedelta(days=1)\r\nagent.schedule_tweet(\r\n \"Join us tomorrow for our quantum biology seminar! \u00f0\u0178\u017d\u201c\",\r\n scheduled_time=future\r\n)\r\n```\r\n\r\n### Analyze Engagement\r\n\r\n```python\r\n# Get recent tweets\r\nhistory = agent.get_tweet_history(count=5)\r\n\r\n# Analyze engagement\r\nfor tweet in history:\r\n metrics = agent.analyze_tweet_engagement(tweet['id'])\r\n print(f\"Tweet: {tweet['content']}\")\r\n print(f\"Likes: {metrics['likes']}\")\r\n print(f\"Retweets: {metrics['retweets']}\")\r\n```\r\n\r\n## Multi-Agent Collaboration\r\n\r\n### Basic Collaboration\r\n\r\n```python\r\n# Create specialized agents\r\nphysicist = HelixAgent(persona=\"physicist\")\r\nbiologist = HelixAgent(persona=\"biologist\")\r\n\r\n# Simple discussion\r\ndiscussion = physicist.collaborate(\r\n other_agent=biologist,\r\n prompt=\"Discuss quantum effects in photosynthesis\",\r\n turns=3\r\n)\r\n```\r\n\r\n### Complex Collaboration\r\n\r\n```python\r\n# Create team of specialists\r\nphysicist = HelixAgent(persona=\"physicist\")\r\nbiologist = HelixAgent(persona=\"biologist\")\r\nchemist = HelixAgent(persona=\"chemist\")\r\n\r\n# Sequential collaboration\r\nphysics_view = physicist.generate_response(\r\n \"Explain quantum tunneling in enzyme catalysis\"\r\n)\r\n\r\nbiology_view = biologist.generate_response(\r\n f\"Based on this physics explanation: {physics_view}\\n\"\r\n \"How might this affect enzyme function?\"\r\n)\r\n\r\nchemistry_view = chemist.generate_response(\r\n f\"Given these insights:\\n\"\r\n f\"Physics: {physics_view}\\n\"\r\n f\"Biology: {biology_view}\\n\"\r\n \"What chemical techniques could we use to detect this?\"\r\n)\r\n\r\n# Collaborative experiment\r\nprotocol = physicist.create_experiment(\r\n steps=[\"Setup quantum detection\", \"Prepare enzymes\", \"Measure activity\"],\r\n materials=[\"Quantum sensor\", \"Enzyme samples\"],\r\n duration=\"5 hours\",\r\n conditions={\"temperature\": 5} # Low temp for quantum effects\r\n)\r\n\r\nphysics_results = physicist.run_experiment(\r\n protocol=protocol,\r\n variables={\"tunneling_rate\": 0.1},\r\n iterations=3\r\n)\r\n\r\nbiology_analysis = biologist.analyze_data(\r\n [r['variables']['tunneling_rate'] for r in physics_results['results']]\r\n)\r\n\r\nchemistry_insights = chemist.generate_response(\r\n f\"Analyze these results from chemical perspective:\\n\"\r\n f\"Physics data: {physics_results['summary_stats']}\\n\"\r\n f\"Biology analysis: {biology_analysis}\"\r\n)\r\n```\r\n\r\n## Documentation\r\n\r\nDetailed documentation for each feature is available in the `docs/` directory.\r\n\r\n## Development\r\n\r\n```bash\r\n# Install development dependencies\r\npip install -e \".[dev]\"\r\n\r\n# Run tests\r\npytest tests/\r\n\r\n# Format code\r\nblack helix_agent/\r\nisort helix_agent/\r\n```\r\n\r\n## Common Issues and Solutions\r\n\r\n| Issue | Cause | Solution |\r\n|-------|-------|----------|\r\n| OpenAI API Error | Invalid/missing API key | Set OPENAI_API_KEY environment variable |\r\n| Twitter API Error | Invalid credentials | Verify Twitter API credentials |\r\n| Import Error | Missing dependencies | Install required packages |\r\n| Memory Issues | Large experiments | Reduce batch size/iterations |\r\n| Rate Limits | Too many API calls | Implement request throttling |\r\n\r\n## Support\r\n\r\n- Report bugs through [GitHub Issues](https://github.com/helixagent/helix-agent/issues)\r\n- Check documentation in the `docs/` directory\r\n- Review examples in the `examples/` directory\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package for creating science-themed AI agents with research and experimentation capabilities.",
"version": "1.2.0",
"project_urls": {
"Documentation": "https://github.com/helixagent/helix-agent/tree/main/docs",
"Homepage": "https://github.com/helixagent/helix-agent",
"Issues": "https://github.com/helixagent/helix-agent/issues",
"Source": "https://github.com/helixagent/helix-agent"
},
"split_keywords": [
"ai",
" openai",
" science",
" research",
" agents",
" gpt",
" helix",
" desci",
" experiments",
" analysis",
" machine learning",
" data science",
" collaboration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8311fb7700a3384562e6c62a5b415b6df466c1ebd16a573758760bf72e9cf9f9",
"md5": "1a9f04c2e745d5c42f884758b367e3a6",
"sha256": "aacd015c61d3e1c5f3e9888b95b3bade2752e83b71ce0e5be65d44bcb1408b75"
},
"downloads": -1,
"filename": "helix_agent-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a9f04c2e745d5c42f884758b367e3a6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23598,
"upload_time": "2025-01-12T13:10:48",
"upload_time_iso_8601": "2025-01-12T13:10:48.366939Z",
"url": "https://files.pythonhosted.org/packages/83/11/fb7700a3384562e6c62a5b415b6df466c1ebd16a573758760bf72e9cf9f9/helix_agent-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "89d0b3c41a8484fd7651dab37e101f01902b2b2d34793328046c5a3550831af9",
"md5": "f5f78ca91bb08088dd2af005b271df83",
"sha256": "54bc282998a129db89e5a48bbe4e8ba9e0c6cbd13995102954e5ab56eae41db7"
},
"downloads": -1,
"filename": "helix_agent-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "f5f78ca91bb08088dd2af005b271df83",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 35907,
"upload_time": "2025-01-12T13:10:49",
"upload_time_iso_8601": "2025-01-12T13:10:49.717892Z",
"url": "https://files.pythonhosted.org/packages/89/d0/b3c41a8484fd7651dab37e101f01902b2b2d34793328046c5a3550831af9/helix_agent-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-12 13:10:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "helixagent",
"github_project": "helix-agent",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.21.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.7.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.0.0"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
">=",
"2.8.2"
]
]
}
],
"lcname": "helix-agent"
}
JSON
