Phase 1: Project 9 automation, workspace_providers, orchestrator (from draft)

.cursor/llm/README.md

@@ -0,0 +1,108 @@
+# LLM Documentation Resources
+
+This directory contains curated `llm.txt` files for each major dependency, library, and service used in HyperAgent. These files follow the [llms.txt standard](https://llmstxt.org/) to help AI systems understand and work with external documentation.
+
+## Purpose
+
+Each `llm.txt` file provides:
+- Overview of the technology and its role in HyperAgent
+- Key use cases and implementation details
+- Links to official documentation
+- Code examples relevant to HyperAgent
+- Best practices for integration
+
+## Available Resources
+
+### Core Frameworks
+- **thirdweb-llm.txt** - Thirdweb SDK for wallets, ERC-4337, and deployments
+- **langgraph-llm.txt** - LangGraph for agent orchestration
+- **fastapi-llm.txt** - FastAPI for backend API
+- **nextjs-react-llm.txt** - Next.js and React for frontend
+
+### Infrastructure
+- **supabase-llm.txt** - Supabase for database and multi-tenant workspaces
+- **redis-llm.txt** - Redis for caching and message queuing
+- **pinecone-llm.txt** - Pinecone for vector database and RAG
+- **acontext-llm.txt** - Acontext for agent long-term memory
+
+### Blockchain & Smart Contracts
+- **hardhat-foundry-llm.txt** - Hardhat and Foundry for Solidity development
+- **openzeppelin-llm.txt** - OpenZeppelin Contracts library
+- **slither-mythril-llm.txt** - Security auditing tools
+- **erc-4337-llm.txt** - Account Abstraction standard
+- **erc-8004-llm.txt** - Trustless Agents standard
+
+### Storage & Data
+- **ipfs-pinata-llm.txt** - IPFS and Pinata for decentralized storage
+- **eigenda-llm.txt** - EigenDA for verifiable data availability
+
+### Observability
+- **opentelemetry-llm.txt** - OpenTelemetry for distributed tracing
+- **mlflow-llm.txt** - MLflow for ML experiment tracking
+- **tenderly-llm.txt** - Tenderly for contract simulation and monitoring
+- **dune-analytics-llm.txt** - Dune Analytics for on-chain analytics
+
+### LLM Providers
+- **anthropic-openai-llm.txt** - Anthropic (Claude) and OpenAI (GPT) for code generation
+- **gemini-llm.txt** - Google Gemini for fast, cost-effective generation
+
+### Payments
+- **x402-llm.txt** - x402 payment protocol for SKALE
+
+### DevOps & Deployment
+- **docker-llm.txt** - Docker and Docker Compose for containerization
+
+## Usage
+
+When working on HyperAgent features that involve external dependencies:
+
+1. **Check the relevant `llm.txt` file first** - It contains HyperAgent-specific context
+2. **Reference official docs** - Links provided for detailed information
+3. **Follow best practices** - Each file includes integration best practices
+4. **Use code examples** - Examples are tailored to HyperAgent's use cases
+
+## File Structure
+
+Each `llm.txt` file follows this structure:
+
+```markdown
+# [Technology] Documentation for HyperAgent
+
+## Overview
+Brief description and role in HyperAgent
+
+## Key Use Cases in HyperAgent
+Specific use cases in the project
+
+## Documentation Links
+Links to official documentation
+
+## Implementation in HyperAgent
+Where and how it's used in the codebase
+
+## Code Examples
+Relevant code examples
+
+## Best Practices
+Integration best practices
+
+## Related Resources
+Additional resources
+```
+
+## Maintenance
+
+- Update files when dependencies change
+- Add new dependencies as they're integrated
+- Keep documentation links current
+- Update code examples when implementation changes
+
+## Contributing
+
+When adding a new dependency:
+1. Create a new `{dependency}-llm.txt` file
+2. Follow the standard structure
+3. Include HyperAgent-specific context
+4. Add links to official documentation
+5. Update this README
+

.cursor/llm/acontext-llm.txt

@@ -0,0 +1,76 @@
+# Acontext Documentation for HyperAgent
+
+## Overview
+
+Acontext is a long-term memory system for AI agents, providing persistent context management across agent sessions. HyperAgent uses Acontext for maintaining agent memory, storing conversation history, and enabling agents to learn from past interactions.
+
+## Key Use Cases in HyperAgent
+
+- **Agent Memory**: Long-term memory for agents
+- **Context Management**: Maintain context across sessions
+- **Learning**: Agents learn from past interactions
+- **Conversation History**: Store user-agent interactions
+- **Knowledge Retention**: Persistent knowledge storage
+
+## Documentation Links
+
+### Official Documentation
+- **Main Docs**: https://docs.acontext.io/
+- **API Reference**: https://docs.acontext.io/api-reference/introduction
+- **Integration Guide**: https://docs.acontext.io/integrations/intro
+
+### Key Concepts
+- **Contexts**: Organized memory units
+- **Memories**: Individual memory entries
+- **Retrieval**: Semantic search over memories
+- **Persistence**: Long-term storage
+- **Privacy**: Workspace-scoped memories
+
+## Implementation in HyperAgent
+
+### Memory Service
+- Location: `hyperagent/llm/acontext_client.py`
+- Stores agent interactions
+- Retrieves relevant context for agents
+
+### Use Cases
+- SpecAgent memory of user requirements
+- CodeGenAgent memory of patterns
+- AuditAgent memory of vulnerabilities
+
+## Code Examples
+
+### Storing Memory
+```python
+from acontext import AcontextClient
+
+client = AcontextClient(api_key="your-api-key")
+
+memory_id = client.create_memory(
+    content="User prefers gas-optimized contracts",
+    metadata={"workspace_id": "ws-123", "agent": "CodeGenAgent"}
+)
+```
+
+### Retrieving Context
+```python
+contexts = client.search_memories(
+    query="gas optimization preferences",
+    workspace_id="ws-123",
+    limit=5
+)
+```
+
+## Best Practices
+
+1. **Context Organization**: Organize by workspace and agent
+2. **Metadata**: Add rich metadata for better retrieval
+3. **Privacy**: Ensure workspace isolation
+4. **Retention**: Define memory retention policies
+5. **Retrieval**: Use semantic search for relevant context
+
+## Related Resources
+
+- Acontext GitHub: https://github.com/memodb-io/acontext
+- Acontext Documentation: https://docs.acontext.io/
+

.cursor/llm/anthropic-openai-llm.txt

@@ -0,0 +1,91 @@
+# Anthropic & OpenAI LLM Documentation for HyperAgent
+
+## Overview
+
+Anthropic (Claude) and OpenAI (GPT) are LLM providers used by HyperAgent for code generation, reasoning, and agent operations. HyperAgent uses a multi-model routing strategy, using different models for different tasks based on complexity, cost, and quality requirements.
+
+## Key Use Cases in HyperAgent
+
+- **Code Generation**: Generate Solidity contracts from natural language
+- **Complex Reasoning**: Architecture design and planning
+- **Quick Edits**: Fast iterations and code modifications
+- **Model Routing**: Route tasks to appropriate models
+- **Cost Optimization**: Balance quality and cost
+
+## Documentation Links
+
+### Anthropic (Claude)
+- **Main Docs**: https://docs.anthropic.com/
+- **API Reference**: https://docs.anthropic.com/claude/reference
+- **Python SDK**: https://github.com/anthropics/anthropic-sdk-python
+- **Best Practices**: https://docs.anthropic.com/claude/docs
+
+### OpenAI (GPT)
+- **Main Docs**: https://platform.openai.com/docs
+- **API Reference**: https://platform.openai.com/docs/api-reference
+- **Python SDK**: https://github.com/openai/openai-python
+- **Best Practices**: https://platform.openai.com/docs/guides
+
+### Key Concepts
+- **Prompt Engineering**: Effective prompt design
+- **Token Management**: Token limits and costs
+- **Streaming**: Real-time response streaming
+- **Function Calling**: Tool use and function calling
+- **Rate Limiting**: API rate limits and handling
+
+## Implementation in HyperAgent
+
+### Multi-Model Router
+- Location: `hyperagent/core/routing/multi_model_router.py`
+- Routes tasks to appropriate models
+- Fallback logic for failures
+- Cost and latency optimization
+
+### Model Configuration
+- Location: `config/llm.yaml`
+- Model selection per task type
+- Timeout and retry configuration
+- Cost tracking
+
+## Code Examples
+
+### Anthropic Client
+```python
+from anthropic import Anthropic
+
+client = Anthropic(api_key="your-api-key")
+
+response = client.messages.create(
+    model="claude-3-5-sonnet-20241022",
+    max_tokens=4096,
+    messages=[{"role": "user", "content": prompt}]
+)
+```
+
+### OpenAI Client
+```python
+from openai import OpenAI
+
+client = OpenAI(api_key="your-api-key")
+
+response = client.chat.completions.create(
+    model="gpt-4-turbo-preview",
+    messages=[{"role": "user", "content": prompt}],
+    temperature=0.7
+)
+```
+
+## Best Practices
+
+1. **Model Selection**: Use appropriate model for task complexity
+2. **Prompt Design**: Write clear, specific prompts
+3. **Error Handling**: Implement retry logic for API failures
+4. **Cost Management**: Monitor token usage and costs
+5. **Rate Limiting**: Respect API rate limits
+
+## Related Resources
+
+- Anthropic GitHub: https://github.com/anthropics
+- OpenAI GitHub: https://github.com/openai
+- Prompt Engineering Guide: https://www.promptingguide.ai/
+

.cursor/llm/docker-llm.txt

@@ -0,0 +1,82 @@
+# Docker Documentation for HyperAgent
+
+## Overview
+
+Docker is a containerization platform used by HyperAgent for packaging services, ensuring consistent environments, and simplifying deployment. HyperAgent uses Docker and Docker Compose for local development and production deployments.
+
+## Key Use Cases in HyperAgent
+
+- **Service Containerization**: Package each microservice
+- **Development Environment**: Consistent local setup
+- **CI/CD**: Containerized builds and tests
+- **Production Deployment**: Deploy containers to cloud
+- **Dependency Isolation**: Isolate service dependencies
+
+## Documentation Links
+
+### Official Documentation
+- **Main Docs**: https://docs.docker.com/
+- **Docker Compose**: https://docs.docker.com/compose/
+- **Best Practices**: https://docs.docker.com/develop/dev-best-practices/
+- **Multi-stage Builds**: https://docs.docker.com/build/building/multi-stage/
+
+### Key Concepts
+- **Images**: Immutable templates for containers
+- **Containers**: Running instances of images
+- **Dockerfile**: Instructions for building images
+- **Docker Compose**: Multi-container orchestration
+- **Volumes**: Persistent data storage
+
+## Implementation in HyperAgent
+
+### Dockerfiles
+- `Dockerfile` - Main backend service
+- `Dockerfile.mlflow` - MLflow service
+- `frontend/Dockerfile.dev` - Frontend development
+
+### Docker Compose
+- `docker-compose.yml` - Local development setup
+- Services: API, frontend, database, Redis, MLflow
+
+## Code Examples
+
+### Dockerfile
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+CMD ["uvicorn", "hyperagent.api.main:app", "--host", "0.0.0.0"]
+```
+
+### Docker Compose
+```yaml
+services:
+  api:
+    build: .
+    ports:
+      - "8000:8000"
+    environment:
+      - DATABASE_URL=postgresql://...
+    depends_on:
+      - db
+      - redis
+```
+
+## Best Practices
+
+1. **Multi-stage Builds**: Reduce image size
+2. **Layer Caching**: Optimize build times
+3. **Security**: Use non-root users
+4. **Health Checks**: Add health check endpoints
+5. **Resource Limits**: Set memory and CPU limits
+
+## Related Resources
+
+- Docker GitHub: https://github.com/docker
+- Docker Hub: https://hub.docker.com/
+- Best Practices: https://docs.docker.com/develop/dev-best-practices/
+