{"id":29843299,"url":"https://github.com/tomatyss/taskter-v1","last_synced_at":"2025-07-29T15:42:49.873Z","repository":{"id":303154819,"uuid":"1014071497","full_name":"tomatyss/taskter-v1","owner":"tomatyss","description":"AI‑powered Kanban board with autonomous agents.","archived":false,"fork":false,"pushed_at":"2025-07-21T21:16:27.000Z","size":303,"stargazers_count":2,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-23T03:23:04.831Z","etag":null,"topics":["agentic-ai","agents","anthropic","flask","gemini","kanban","kanban-board","llm","openai"],"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/tomatyss.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-07-05T02:05:33.000Z","updated_at":"2025-07-13T17:05:16.000Z","dependencies_parsed_at":"2025-07-06T02:36:05.604Z","dependency_job_id":"df78e4a3-244c-4215-ab8a-e76c3eadb2c7","html_url":"https://github.com/tomatyss/taskter-v1","commit_stats":null,"previous_names":["tomatyss/taskter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tomatyss/taskter-v1","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomatyss%2Ftaskter-v1","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomatyss%2Ftaskter-v1/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomatyss%2Ftaskter-v1/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomatyss%2Ftaskter-v1/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomatyss","download_url":"https://codeload.github.com/tomatyss/taskter-v1/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomatyss%2Ftaskter-v1/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267710230,"owners_count":24131936,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agentic-ai","agents","anthropic","flask","gemini","kanban","kanban-board","llm","openai"],"created_at":"2025-07-29T15:42:49.113Z","updated_at":"2025-07-29T15:42:49.831Z","avatar_url":"https://github.com/tomatyss.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Taskter - AI-Powered Kanban Board Application\n\nAn intelligent kanban board application built with Flask, PostgreSQL, and AI agents. The application combines traditional task management with AI automation, allowing you to assign tasks to AI agents that can execute them using various tools and LLM providers.\n\n## Features\n\n### Core Kanban Features\n- **Four-column Kanban Board**: To Do, In Progress, Blocked, Done\n- **Task Management**: Create, edit, delete, and move tasks between columns\n- **Server-driven UI**: All interactions handled server-side with full page refreshes\n- **PostgreSQL Database**: Persistent data storage\n- **Docker Support**: Easy deployment and development setup\n- **Responsive Design**: Works on desktop and mobile devices\n\n### AI Agent Features\n- **Multi-LLM Support**: OpenAI GPT, Anthropic Claude, and Google Gemini\n- **Agent Management**: Create, configure, and manage AI agents with custom instructions\n- **Task Assignment**: Assign tasks to AI agents for automated execution\n- **Tool Integration**: Agents can use web search, email, and script execution tools\n- **Background Processing**: Asynchronous task execution with Celery and Redis\n- **Execution Monitoring**: Real-time tracking of agent task execution\n- **Conversation Logs**: Detailed logs of agent decision-making processes\n\n## Technology Stack\n\n- **Backend**: Flask (Python)\n- **Database**: PostgreSQL\n- **Frontend**: HTML, CSS, Bootstrap 5, JavaScript\n- **Validation**: Pydantic for request/response schemas\n- **Background Tasks**: Celery with Redis\n- **Containerization**: Docker \u0026 Docker Compose\n\n## Quick Start\n\n### Using Docker Compose (Recommended)\n\n1. Clone or download the project files\n2. Navigate to the project directory:\n   ```bash\n   cd taskter\n   ```\n\n3. Copy the environment file and configure your API keys:\n   ```bash\n   cp .env.example .env\n   ```\n   \n   Edit `.env` and add your API keys:\n   ```bash\n   # LLM Provider API Keys (at least one required for AI features)\n   OPENAI_API_KEY=your-openai-api-key-here\n   ANTHROPIC_API_KEY=your-anthropic-api-key-here\n   GEMINI_API_KEY=your-gemini-api-key-here\n   \n   # Optional: Email configuration for send_email tool\n   SMTP_USERNAME=your-email@gmail.com\n   SMTP_PASSWORD=your-app-password\n   \n   # Optional: Google Search configuration for web_search tool\n   GOOGLE_SEARCH_API_KEY=your-google-search-api-key\n   GOOGLE_SEARCH_ENGINE_ID=your-search-engine-id\n   ```\n\n4. Start the application:\n   ```bash\n   docker-compose up --build\n   ```\n   \n   The system will automatically:\n   - Start PostgreSQL and Redis\n   - Run database migrations\n   - Seed sample data\n   - Start the web application and background services\n\n5. Open your browser and go to: http://localhost:5001\n\n6. To stop the application:\n   ```bash\n   docker-compose down\n   ```\n\n### Manual Setup (Development)\n\n1. Install Python 3.11+ and PostgreSQL\n2. Create a virtual environment:\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n3. Install dependencies:\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. Setup PostgreSQL database:\n   - Create a database named `kanban_db`\n   - Create a user `kanban_user` with password `kanban_pass`\n   - Grant all privileges to the user\n\n5. Configure environment variables:\n   ```bash\n   cp .env.example .env\n   # Edit .env with your configuration\n   ```\n\n6. Run database migrations:\n   ```bash\n   python manage_migrations.py upgrade\n   python manage_migrations.py seed\n   ```\n\n7. Create an initial user:\n   ```bash\n   python scripts/setup_user.py\n   ```\n\n8. Run the application:\n   ```bash\n   python main.py\n   ```\n\n## Project Structure\n\n```\ntaskter/\n├── main.py                      # Main Flask application entry point\n├── manage_migrations.py         # Database migration management\n├── celery_app.py               # Celery configuration\n├── requirements.txt            # Python dependencies\n├── Dockerfile                  # Docker configuration\n├── docker-compose.yml          # Docker Compose configuration\n├── .env                        # Environment variables\n├── app/                        # Main application package\n│   ├── __init__.py\n│   ├── api/                    # API layer\n│   │   ├── __init__.py\n│   │   ├── response.py         # API response utilities\n│   │   ├── middleware/         # API middleware\n│   │   └── v1/                 # API version 1\n│   │       ├── __init__.py\n│   │       ├── tasks.py        # Task endpoints\n│   │       ├── agents.py       # Agent endpoints\n│   │       └── executions.py   # Execution endpoints\n│   ├── core/                   # Core application components\n│   │   ├── __init__.py\n│   │   ├── config.py           # Centralized configuration\n│   │   ├── constants.py        # Application constants\n│   │   ├── exceptions.py       # Custom exceptions\n│   │   └── logging.py          # Logging configuration\n│   ├── models/                 # Database models\n│   │   ├── __init__.py\n│   │   ├── task.py             # Task model\n│   │   ├── agent.py            # Agent model\n│   │   └── execution.py        # Execution model\n│   ├── schemas/                # Pydantic schemas\n│   │   ├── __init__.py\n│   │   ├── task_schemas.py     # Task request/response schemas\n│   │   ├── agent_schemas.py    # Agent request/response schemas\n│   │   └── execution_schemas.py # Execution request/response schemas\n│   ├── services/               # Business logic layer\n│   │   ├── __init__.py\n│   │   ├── task_service.py     # Task business logic\n│   │   ├── agent_service.py    # Agent business logic\n│   │   └── execution_service.py # Execution business logic\n│   ├── repositories/           # Data access layer\n│   │   ├── __init__.py\n│   │   ├── base.py             # Base repository\n│   │   ├── task_repository.py  # Task data access\n│   │   ├── agent_repository.py # Agent data access\n│   │   └── execution_repository.py # Execution data access\n│   ├── agents/                 # AI agent system\n│   │   ├── __init__.py\n│   │   ├── providers/          # LLM providers\n│   │   └── tools/              # Agent tools\n│   └── utils/                  # Utility functions\n│       └── __init__.py\n├── migrations/                 # Database migration files\n├── templates/                  # HTML templates\n│   ├── base.html\n│   ├── index.html              # Main kanban board\n│   ├── agents.html             # Agent management\n│   ├── executions.html         # Execution monitoring\n│   └── edit_task.html          # Task editing form\n├── static/                     # Static files\n│   ├── css/\n│   │   └── style.css\n│   └── js/\n│       └── script.js\n├── tests/                      # Test files\n│   ├── __init__.py\n│   ├── unit/\n│   ├── integration/\n│   └── fixtures/\n└── scripts/                    # Utility scripts\n```\n\n## API Endpoints\n\nThe application provides a RESTful API with the following endpoints:\n\n### Tasks (`/api/v1/tasks`)\n- `GET /api/v1/tasks` - List tasks with filtering and pagination\n- `POST /api/v1/tasks` - Create new task\n- `GET /api/v1/tasks/{id}` - Get specific task\n- `PUT /api/v1/tasks/{id}` - Update task\n- `DELETE /api/v1/tasks/{id}` - Delete task\n- `PUT /api/v1/tasks/{id}/status` - Update task status\n- `POST /api/v1/tasks/{id}/assign` - Assign task to agent\n- `POST /api/v1/tasks/{id}/unassign` - Unassign task\n- `GET /api/v1/tasks/stats` - Get task statistics\n\n### Agents (`/api/v1/agents`)\n- `GET /api/v1/agents` - List agents with filtering\n- `POST /api/v1/agents` - Create new agent\n- `GET /api/v1/agents/{id}` - Get specific agent\n- `PUT /api/v1/agents/{id}` - Update agent\n- `DELETE /api/v1/agents/{id}` - Delete agent\n- `POST /api/v1/agents/{id}/toggle` - Toggle agent active status\n- `GET /api/v1/agents/{id}/tasks` - Get agent's assigned tasks\n- `GET /api/v1/agents/stats` - Get agent statistics\n\n### Executions (`/api/v1/executions`)\n- `GET /api/v1/executions` - List executions with filtering\n- `GET /api/v1/executions/{id}` - Get specific execution\n- `POST /api/v1/executions/{id}/cancel` - Cancel execution\n- `GET /api/v1/executions/stats` - Get execution statistics\n- `GET /api/v1/executions/running` - Get currently running executions\n\n## Usage\n\n### Basic Task Management\n\n#### Adding Tasks\n- Click the \"Add New Task\" button\n- Fill in the task title (required) and description (optional)\n- Click \"Add Task\"\n\n#### Moving Tasks\n- Use the arrow buttons on each task card to move between columns:\n  - From \"To Do\" → \"In Progress\" or \"Blocked\"\n  - From \"In Progress\" → \"To Do\", \"Blocked\", or \"Done\"\n  - From \"Blocked\" → \"In Progress\"\n  - From \"Done\" → \"In Progress\"\n\n#### Editing Tasks\n- Click the edit icon (pencil) on any task card\n- Modify the title and/or description\n- Click \"Save Changes\"\n\n#### Deleting Tasks\n- Click the delete icon (trash) on any task card\n- Confirm the deletion in the popup dialog\n\n### AI Agent System\n\n#### Setting Up AI Agents\n\n1. **Configure API Keys**: Add your LLM provider API keys to the `.env` file\n2. **Initialize Sample Agents**: Run the initialization script to create sample agents:\n   ```bash\n   # If using Docker\n   docker-compose exec web python init_agents.py\n   \n   # If running locally\n   python init_agents.py\n   ```\n\n#### Using AI Agents\n\n**Via Web Interface:**\n1. Navigate to `/agents` to manage agents\n2. Navigate to `/executions` to monitor task executions\n3. Assign tasks to agents from the main kanban board\n\n**Via API:**\n\n**Create a new agent:**\n```bash\ncurl -X POST http://localhost:5001/api/v1/agents \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Research Assistant\",\n    \"description\": \"Specialized in web research and data gathering\",\n    \"system_instructions\": \"You are a research assistant. Help users find information and summarize findings.\",\n    \"llm_provider\": \"openai\",\n    \"llm_model\": \"gpt-4\",\n    \"available_tools\": [\"web_search\"],\n    \"config\": {\n      \"temperature\": 0.7,\n      \"max_tokens\": 1000,\n      \"max_iterations\": 10\n    }\n  }'\n```\n\n**Assign a task to an agent:**\n```bash\ncurl -X POST http://localhost:5001/api/v1/tasks/1/assign \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"agent_id\": 1}'\n```\n\n**Monitor execution:**\n```bash\ncurl http://localhost:5001/api/v1/executions\n```\n\n#### Available Tools\n\n1. **Web Search Tool**: Search the web for information using Google Custom Search or DuckDuckGo\n2. **Send Email Tool**: Send emails via SMTP with customizable content\n3. **Execute Script Tool**: Run Python scripts safely with timeout and security restrictions\n\n#### LLM Providers\n\n- **OpenAI**: GPT-4, GPT-3.5-turbo models\n- **Anthropic**: Claude-3.5-sonnet and other Claude models\n- **Google Gemini**: Gemini-2.5-flash and other Gemini models\n\n## Configuration\n\nThe application uses a centralized configuration system with environment variables:\n\n### Required Configuration\n```bash\n# Database\nDATABASE_URL=postgresql://taskter_user:taskter_pass@db:5432/taskter_db\n\n# Flask\nSECRET_KEY=your-secret-key-change-in-production\n\n# Redis (for background tasks)\nREDIS_URL=redis://localhost:6379/0\n```\n\n### Optional Configuration\n```bash\n# LLM Provider API Keys (at least one required for AI features)\nOPENAI_API_KEY=your-openai-api-key-here\nANTHROPIC_API_KEY=your-anthropic-api-key-here\nGEMINI_API_KEY=your-gemini-api-key-here\n\n# Email Tool Configuration\nSMTP_SERVER=smtp.gmail.com\nSMTP_PORT=587\nSMTP_USERNAME=your-email@gmail.com\nSMTP_PASSWORD=your-app-password\n\n# Web Search Tool Configuration\nGOOGLE_SEARCH_API_KEY=your-google-search-api-key\nGOOGLE_SEARCH_ENGINE_ID=your-search-engine-id\n\n# Logging\nLOG_LEVEL=INFO\n\n# Agent Configuration\nAGENT_MAX_ITERATIONS=20\nAGENT_DEFAULT_TIMEOUT=300\nAGENT_MAX_TOKENS=1000\nAGENT_TEMPERATURE=0.7\n```\n\n## Database Migration System\n\nTaskter uses a robust database migration system built on Flask-Migrate (Alembic):\n\n### Quick Migration Commands\n\n```bash\n# Initialize migration repository (first time only)\npython manage_migrations.py init\n\n# Create new migration from model changes\npython manage_migrations.py migrate \"Add new feature\"\n\n# Apply all pending migrations\npython manage_migrations.py upgrade\n\n# Seed sample data\npython manage_migrations.py seed\n\n# Validate database state\npython manage_migrations.py validate\n\n# Create database backup\npython manage_migrations.py backup\n```\n\n### Docker Integration\n\nMigrations run automatically when using Docker Compose:\n\n```bash\n# Start with automatic migrations\ndocker-compose up --build\n\n# Manual migration in Docker\ndocker-compose run --rm migration python manage_migrations.py upgrade\n```\n\n## Database Schema\n\n### Task Table\n- `id`: Primary key (auto-increment)\n- `title`: Task title (required, max 200 characters)\n- `description`: Task description (optional, text)\n- `status`: Task status ('todo', 'in_progress', 'blocked', 'done')\n- `created_at`: Creation timestamp\n- `updated_at`: Last update timestamp\n- `assigned_agent_id`: Foreign key to Agent table (optional)\n- `execution_status`: Execution status ('manual', 'assigned', 'running', 'completed', 'failed')\n\n### Agent Table\n- `id`: Primary key (auto-increment)\n- `name`: Agent name (required, max 100 characters)\n- `description`: Agent description (optional, text)\n- `system_instructions`: System instructions for the agent (required, text)\n- `llm_provider`: LLM provider ('openai', 'anthropic', 'gemini')\n- `llm_model`: LLM model name\n- `llm_api_key`: API key for the LLM provider (optional)\n- `available_tools`: JSON array of available tools\n- `config`: JSON configuration object\n- `is_active`: Boolean flag for agent status\n- `created_at`: Creation timestamp\n- `updated_at`: Last update timestamp\n\n### AgentExecution Table\n- `id`: Primary key (auto-increment)\n- `task_id`: Foreign key to Task table\n- `agent_id`: Foreign key to Agent table\n- `status`: Execution status ('pending', 'running', 'completed', 'failed', 'stopped')\n- `conversation_log`: JSON array of conversation history\n- `result`: Execution result (text)\n- `error_message`: Error message if execution failed\n- `iterations_count`: Number of iterations performed\n- `tokens_used`: Number of tokens consumed\n- `execution_time_seconds`: Execution time in seconds\n- `started_at`: Execution start timestamp\n- `completed_at`: Execution completion timestamp\n- `created_at`: Creation timestamp\n\n## Docker Configuration\n\n### Services\n\n1. **Database (db)**: PostgreSQL 15 Alpine with health checks\n2. **Redis (redis)**: Redis 7 Alpine for background task queue\n3. **Migration (migration)**: Runs database migrations and seeding\n4. **Web Application (web)**: Main Flask application\n5. **Celery Worker (celery_worker)**: Background task processor\n6. **Celery Beat (celery_beat)**: Task scheduler\n\n### Volumes\n\n- `postgres_data`: Persistent storage for PostgreSQL data\n- `redis_data`: Persistent storage for Redis data\n\n## Development\n\n### Running in Development Mode\n\n1. Start the services:\n   ```bash\n   docker-compose up\n   ```\n\n2. The application will automatically reload when you make changes to the code\n\n3. Access the application at http://localhost:5001\n\n### Database Access\n\nTo access the PostgreSQL database directly:\n\n```bash\ndocker exec -it kanban_postgres psql -U kanban_user -d kanban_db\n```\n\n### Logs\n\nView application logs:\n```bash\ndocker-compose logs web\n```\n\nView background task logs:\n```bash\ndocker-compose logs celery_worker\ndocker-compose logs celery_beat\n```\n\n### Adding New Features\n\nThe application follows a layered architecture:\n\n1. **API Layer** (`app/api/v1/`): Handle HTTP requests and responses\n2. **Service Layer** (`app/services/`): Business logic and validation\n3. **Repository Layer** (`app/repositories/`): Data access and database operations\n4. **Model Layer** (`app/models/`): Database models and relationships\n\nWhen adding new features:\n1. Define database models in `app/models/`\n2. Create Pydantic schemas in `app/schemas/`\n3. Implement data access in `app/repositories/`\n4. Add business logic in `app/services/`\n5. Create API endpoints in `app/api/v1/`\n\n## Production Deployment\n\nFor production deployment:\n\n1. Change the `SECRET_KEY` in the environment variables\n2. Set `FLASK_ENV=production`\n3. Configure proper database credentials\n4. Set up SSL certificates\n5. Use a reverse proxy (nginx)\n6. Configure database backups\n7. Set up monitoring and logging\n\n## Sample Data\n\nThe application includes sample tasks and agents that are automatically created when the database is initialized:\n\n**Sample Tasks:**\n- Setup Development Environment (Done)\n- Design Database Schema (Done)\n- Implement User Authentication (In Progress)\n- Create Kanban Board UI (In Progress)\n- Add Task Management (To Do)\n- Write Unit Tests (To Do)\n- Deploy to Production (To Do)\n\n**Sample Agents:**\n- Research Assistant (OpenAI GPT-4)\n- Data Analyst (Anthropic Claude)\n- General Assistant (Google Gemini)\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Port already in use**: Change the port mapping in `docker-compose.yml`\n2. **Database connection failed**: Ensure PostgreSQL is running and credentials are correct\n3. **Permission denied**: Check file permissions and Docker daemon status\n4. **API key errors**: Verify your LLM provider API keys are correctly set in `.env`\n\n### Reset Database\n\nTo reset the database and start fresh:\n\n```bash\ndocker-compose down -v\ndocker-compose up --build\n```\n\n### Debugging Agent Executions\n\nCheck Celery logs for agent execution details:\n```bash\ndocker-compose logs celery_worker\n```\n\nMonitor executions via API:\n```bash\ncurl http://localhost:5001/api/v1/executions\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes following the established architecture\n4. Test thoroughly\n5. Submit a pull request\n\n## Continuous Integration\n\nAll pull requests automatically run the test suite via GitHub Actions. The\nworkflow defined in `.github/workflows/test.yml` installs dependencies from\n`requirements.txt` and also installs `pytest` before executing the tests.\n\n## Preview Deployments\n\nTo manually test a feature branch in Google Cloud Run, push a tag beginning with\n`deploy-` to the branch:\n\n```bash\ngit tag deploy-my-feature\ngit push origin deploy-my-feature\n```\n\nThe `deploy.yml` workflow builds a container image and deploys it to Cloud Run.\nConfigure the following repository secrets for authentication:\n\n- `GCP_PROJECT` – your Google Cloud project ID\n- `GCP_REGION` – the Cloud Run region\n- `GCP_SA_KEY` – JSON service account key with deploy permissions\n\n## License\n\nThis project is open source and available under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomatyss%2Ftaskter-v1","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomatyss%2Ftaskter-v1","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomatyss%2Ftaskter-v1/lists"}