{"id":41865021,"url":"https://github.com/vimalmenon/ai","last_synced_at":"2026-01-25T11:38:09.508Z","repository":{"id":301369626,"uuid":"936677410","full_name":"vimalmenon/ai","owner":"vimalmenon","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-22T23:26:37.000Z","size":2609,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-23T01:33:45.431Z","etag":null,"topics":["fastapi","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vimalmenon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-21T13:52:19.000Z","updated_at":"2025-08-07T16:31:14.000Z","dependencies_parsed_at":"2025-07-12T05:22:55.445Z","dependency_job_id":"fe3b8fd8-f3ca-4ce5-8800-3a5c3cb27f74","html_url":"https://github.com/vimalmenon/ai","commit_stats":null,"previous_names":["vimalmenon/ai"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/vimalmenon/ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimalmenon%2Fai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimalmenon%2Fai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimalmenon%2Fai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimalmenon%2Fai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vimalmenon","download_url":"https://codeload.github.com/vimalmenon/ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vimalmenon%2Fai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28752668,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T10:25:12.305Z","status":"ssl_error","status_checked_at":"2026-01-25T10:25:11.933Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","python"],"created_at":"2026-01-25T11:38:08.758Z","updated_at":"2026-01-25T11:38:09.503Z","avatar_url":"https://github.com/vimalmenon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Elara (Ela) - AI Agent\n\nAn AI Agent named after the moon of Jupiter, representing curiosity and exploration. Elara works alongside Vimal Menon to assist with various development and automation tasks.\n\n## About\n\n**Name**: Elara  \n**Email**: elara.ai@proton.me  \n**Version**: 0.0.19  \n**Python**: 3.13+\n\n## Features\n\n- 🤖 AI-powered workflow automation\n- 🔗 Link management and organization\n- 📝 Blog content generation\n- 🌐 FastAPI-based REST API with modern lifespan management\n- 📊 Comprehensive testing and quality assurance (76% coverage)\n- 🔄 Celery-based background task processing\n- 🔍 Interactive development environment\n- 🛡️ Enhanced error handling and logging\n- ⚡ Request timing and performance monitoring\n- 🔧 Developer-friendly testing tools and scripts\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.13+\n- Poetry for dependency management\n- AWS credentials (for DynamoDB and S3)\n- Docker and Docker Compose (optional, for containerized deployment)\n\n### Installation\n\n#### Local Development\n\n```sh\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd ai\n\n# Install dependencies\npoetry install\n\n# Start the development server\npoetry run fastapi dev main.py\n# or using the poetry script\npoetry run app\n```\n\nThe API will be available at:\n- Main API: `http://localhost:8000`\n- Health Check: `http://localhost:8000/health`\n- API Documentation: `http://localhost:8000/docs`\n- ReDoc Documentation: `http://localhost:8000/redoc`\n\n#### Docker Development\n\n```sh\n# Build and run with Docker Compose\ndocker-compose up --build\n\n# Or run in detached mode\ndocker-compose up -d --build\n\n# View logs\ndocker-compose logs -f app\n\n# Stop services\ndocker-compose down\n```\n\n#### Production Deployment\n\n```sh\n# Production deployment with optimized settings\ndocker-compose -f docker-compose.prod.yml up -d --build\n\n# With Nginx reverse proxy\ndocker-compose -f docker-compose.prod.yml --profile with-nginx up -d --build\n```\n\n## Development Roadmap\n\n### Completed ✅\n- [x] Make the group Link name consistent (Use the name LinkGroup and not GroupLink)\n- [x] Handle exception better\n- [x] Set up auth\n- [x] Upgrade poetry to use Python 3.13\n- [x] Mock LLM service for testing\n- [x] Add interactive development shell with FastAPI context\n- [x] Enhanced main.py with improved logging and error handling\n- [x] Modern FastAPI lifespan event handlers (replaced deprecated @app.on_event)\n- [x] Comprehensive pytest configuration with coverage reporting\n- [x] Developer-friendly testing tools and Makefile commands\n- [x] Request timing middleware for performance monitoring\n- [x] Health check and root endpoints\n- [x] Environment-based CORS configuration\n\n### In Progress 🔄\n- [ ] Optimize workflow execution (make Workflow and execute parallel - fetch optimization)\n- [ ] Implement batch operations for DynamoDB\n- [ ] Move business logic from managers to services\n- [ ] Set up batch processes for scheduler\n\n### Planned 📋\n- [ ] Optimize workflow execution (make Workflow and execute parallel - fetch optimization)\n- [ ] Auto-generate workflow nodes from database\n- [ ] Add comprehensive logging to Service and Manager classes\n- [ ] Implement Celery batch jobs (30-minute intervals)\n- [ ] Auto-execute nodes (except human input required)\n- [ ] Increase test coverage to 85%+ (currently at 76%)\n- [ ] Clean up environment variables\n- [ ] Fix Google LLM integration\n- [ ] Set up Celery backend\n- [ ] Implement AWS authentication\n- [ ] Update secondary key structure\n- [ ] Add more AI tools\n\n### Future Enhancements 🚀\n- [ ] **[Low Priority]** Migrate from string IDs to UUID\n- [ ] **[Low Priority]** Multi-node connections\n- [ ] **[AI Features]** Content generation\n- [ ] **[AI Features]** Code generation\n- [ ] **[AI Features]** Code review automation\n\n## Links\n\n- [SonarCloud Analysis](https://sonarcloud.io/project/overview?id=vimalmenon_ai)\n\n## API Features\n\n### Enhanced FastAPI Application\n\nThe main application (`main.py`) includes several production-ready features:\n\n#### 🔧 **Robust Error Handling**\n- Custom exception handlers for validation errors, HTTP exceptions, and general errors\n- Backward-compatible error responses with enhanced detail structure\n- Request URL context in error logs\n- Debug-conditional error message exposure\n\n#### 📊 **Comprehensive Logging**\n- Console and file logging with structured format\n- Request/response timing middleware\n- Error logging with stack traces\n- Configurable log levels\n\n#### ⚡ **Performance Monitoring**\n- Request timing middleware\n- Response time logging\n- Performance metrics tracking\n\n#### 🛡️ **Modern Patterns**\n- FastAPI lifespan event handlers (replaces deprecated `@app.on_event`)\n- Type-safe request/response handling\n- Proper middleware implementation\n\n#### 🌐 **API Endpoints**\n- `GET /` - Root endpoint with API information\n- `GET /health` - Health check with environment details\n- `GET /docs` - Interactive API documentation\n- `GET /redoc` - ReDoc API documentation\n\n#### 🔄 **Middleware Features**\n- CamelCase to snake_case request body conversion\n- Environment-based CORS configuration\n- Request logging and timing\n\n### Environment Configuration\n\nThe application supports flexible environment-based configuration:\n\n```python\n# Environment variables\nALLOWED_ORIGINS=http://localhost:3000,https://example.com\nDEBUG=true\nHOST=0.0.0.0\nPORT=8000\n```\n\n## Development Environment\n\nThis project provides multiple ways to interact with the FastAPI application for development, debugging, and testing.\n\n### Interactive Development Shell\n\nStart an enhanced Python shell with pre-loaded FastAPI context:\n\n```sh\n# Basic Python shell with FastAPI context\npoetry run python shell.py\n\n# Enhanced IPython shell (recommended - if IPython is installed)\npoetry run python ishell.py\n```\n\n**Available objects in the shell:**\n- `app` - FastAPI application instance\n- `wm` - Pre-configured WorkflowManager instance  \n- `db` - Pre-configured DbManager instance\n- `WorkflowManager`, `DbManager` - Manager classes\n- `WorkflowModel`, `WorkflowSlimModel`, `UpdateWorkflowRequest` - Model classes\n- `DbKeys` - Database key enumerations\n- `generate_uuid`, `created_date` - Utility functions\n\n### Management Commands\n\nDjango-style management interface for common development tasks:\n\n```sh\n# Show all available commands\npoetry run python manage.py\n\n# Start interactive shell\npoetry run python manage.py shell\n\n# Workflow management\npoetry run python manage.py workflow list\npoetry run python manage.py workflow get-with-executed\npoetry run python manage.py workflow create --name \"My New Workflow\"\n\n# Run specific tests\npoetry run python manage.py test --method test_get_workflows\npoetry run python manage.py test  # Run all tests\n```\n\n### Development Examples\n\n```python\n# In the shell, you can:\n\n# Get all workflows\nworkflows = wm.get_workflows()\n\n# Get workflow by ID\nworkflow = wm.get_workflow_by_id(\"some-id\")\n\n# Create a new workflow\nfrom ai.model import WorkflowSlimModel\nnew_wf = wm.create_workflow(WorkflowSlimModel(name=\"Test Workflow\"))\n\n# Test database operations\nfrom boto3.dynamodb.conditions import Key\nitems = db.query_items(Key(DbKeys.Primary.value).eq(\"AI#WORKFLOWS\"))\n\n# Access FastAPI routes\nprint([route.path for route in app.routes])\n```\n\n### Quick Access Commands\n\n```sh\n# Quick functionality access\npoetry run python -c \"\nfrom ai.managers.workflow_manager.workflow_manager import WorkflowManager\nwm = WorkflowManager()\nprint('Total Workflows:', len(wm.get_workflows()))\n\"\n\n# Interactive session with preloaded context\npoetry run python -i -c \"\nfrom main import app\nfrom ai.managers.workflow_manager.workflow_manager import WorkflowManager\nwm = WorkflowManager()\nprint('Ready! Use wm and app objects for interaction')\n\"\n```\n\n## Testing and Quality Assurance\n\nThis project features a comprehensive testing setup with pytest, coverage reporting, and developer-friendly tools.\n\n### Quick Testing Commands\n\n```sh\n# Run all tests with coverage\nmake test\n\n# Fast mode (stop on first failure)\nmake test-fast\n\n# Run with detailed coverage report\nmake test-cov\n\n# Run tests by category (directory-based)\nmake test-units      # Manager and service tests (30 tests)\nmake test-apis       # API endpoint tests (20 tests)\n\n# Run tests in parallel\nmake test-parallel\n\n# Run specific test file\nmake test-file FILE=ai/tests/api/test_error_handling.py\n\n# Run tests matching a pattern\nmake test-pattern PATTERN=\"validation\"\n\n# Run tests in watch mode\nmake test-watch\n\n# Clean test artifacts\nmake clean\n```\n\n### Using the Test Script\n\nThe project includes a custom test runner (`test.py`) with additional options:\n\n```sh\n# Basic usage\npython test.py\n\n# With coverage and verbose output\npython test.py --coverage --verbose\n\n# Fast mode with parallel execution\npython test.py --fast --parallel\n\n# Run specific test markers\npython test.py --markers unit\n\n# Run tests matching keywords\npython test.py --keyword \"error_handling\"\n\n# Run specific test path\npython test.py ai/tests/api/test_links.py\n```\n\n### Pytest Configuration\n\nThe project uses a comprehensive pytest configuration in `pyproject.toml`:\n\n- **Coverage**: Automatic coverage reporting with 76% current coverage\n- **Markers**: Support for `unit`, `integration`, and `slow` test markers\n- **Strict Mode**: Strict marker and config validation\n- **Multiple Reports**: Terminal and HTML coverage reports\n- **Branch Coverage**: Tracks code branch coverage\n\n### Test Structure\n\n```\nai/tests/\n├── api/           # API endpoint tests\n├── conftest.py    # Shared fixtures and test configuration\n├── factory/       # Test data factories\n├── managers/      # Manager layer tests  \n└── services/      # Service layer tests\n```\n\n### Available Test Fixtures\n\n- `client` - FastAPI test client\n- `dynamodb_mock` - Mocked DynamoDB for testing\n- `mock_llm_execute_service` - Mocked LLM service\n- `mock_ai_message_manager` - Mocked AI message manager\n- `setup_env` - Automatic environment setup for tests\n\n### Tox Integration\n\nThis project uses **tox** for comprehensive testing and quality assurance across different environments.\n\n### Tox Environments\n\n```sh\n# Run all environments (tests, linting, type checking)\ntox\n\n# Run only tests with coverage\ntox -e py313\n\n# Run only linting checks\ntox -e lint\n\n# Run only type checking\ntox -e type-check\n\n# Auto-format code (black + ruff fix)\ntox -e format\n\n# Documentation environment (placeholder)\ntox -e docs\n```\n\n### Individual Quality Checks\n\n```sh\n# Test coverage with detailed reporting\ntox -e py313\n\n# Check code formatting and style\ntox -e lint\n\n# Type checking with mypy\ntox -e type-check\n\n# Format code automatically\ntox -e format\n```\n\n### Additional Development Commands\n\n```sh\n# Makefile commands for development workflow\nmake help           # Show all available commands\nmake install        # Install dependencies\nmake dev            # Start development server\nmake test           # Run all tests\nmake test-fast      # Fast test mode\nmake test-cov       # Tests with coverage\nmake lint           # Run all linting tools\nmake format         # Auto-format code\nmake type-check     # Run type checking\nmake clean          # Clean build artifacts\n\n# Manual commands\n# Code formatting and linting\npoetry run ruff check --fix\npoetry run black .\n\n# Test in watch mode\npoetry run ptw\n\n# Run Celery worker\npoetry run celery -A tasks worker -l info\n```\n\n## Utility Commands\n\n### Git and Branch Management\n\n```sh\n# Clean up remote branches\ngit remote update origin --prune\n\n# Remove old local branches\ngit branch | grep -v \"$(git branch --show-current)\" | xargs git branch -D\n```\n\n### System Utilities\n\n```sh\n# Find process running on port 8000\nsudo lsof -i :8000\n```\n\n## Docker Commands\n\n### Development\n\n```sh\n# Build the Docker image\ndocker build -t elara-ai .\n\n# Run the container\ndocker run -p 8000:8000 --env-file .env elara-ai\n\n# Build and run with Docker Compose\ndocker-compose up --build\n\n# Run in background\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f app\n\n# Stop and remove containers\ndocker-compose down\n```\n\n### Production\n\n```sh\n# Production deployment\ndocker-compose -f docker-compose.prod.yml up -d --build\n\n# Scale the application\ndocker-compose -f docker-compose.prod.yml up -d --scale app=3\n\n# Update application\ndocker-compose -f docker-compose.prod.yml pull\ndocker-compose -f docker-compose.prod.yml up -d --build\n\n# View production logs\ndocker-compose -f docker-compose.prod.yml logs -f app\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run quality checks:\n   ```sh\n   # Run tests\n   make test-cov\n   \n   # Run linting\n   make lint\n   \n   # Run type checking  \n   make type-check\n   \n   # Or run everything with tox\n   tox\n   ```\n5. Ensure tests pass and coverage is maintained\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n### Development Guidelines\n\n- Write tests for new features (aim for 80%+ coverage)\n- Use type hints throughout the codebase\n- Follow existing code style (enforced by ruff and black)\n- Add docstrings for public functions and classes\n- Update README for significant changes\n\n### Pre-Push Quality Checks\n\nThis project has several mechanisms to ensure code quality before pushing:\n\n#### Automatic Git Hook\nA pre-push git hook is installed that automatically runs all quality checks before allowing a push. The hook will prevent pushing if any checks fail.\n\n#### Manual Quality Checks\nYou can manually run quality checks using any of these methods:\n\n```bash\n# Using make (recommended)\nmake pre-push\n\n# Using the dedicated script\n./scripts/pre-push-check.sh\n\n# Using tox for comprehensive testing\ntox\n```\n\n#### What Gets Checked\n- **Code Formatting**: Black formatting compliance\n- **Linting**: Ruff and Flake8 code quality checks  \n- **Type Checking**: MyPy static type analysis\n- **Tests**: Full test suite with coverage reporting\n\n#### GitHub Actions CI/CD\nThe repository includes GitHub Actions workflows that run the same checks on every push and pull request to the main branches.\n\n## License\n\nThis project is private and proprietary.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvimalmenon%2Fai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvimalmenon%2Fai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvimalmenon%2Fai/lists"}