amit/quantum-ai-v3
1
0
Fork 0
mirror of https://github.com/thecyberlearn/quantum-ai-v3.git synced 2026-08-18 16:32:57 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

📚 Update documentation to reflect current simplified architecture

Browse Source 
- Removed all references to legacy agent_base app and individual agent apps
- Updated architecture to show unified workflows system
- Simplified agent creation process documentation
- Updated URL structure to show current routing
- Fixed template architecture documentation
- Updated database design to show current models
- Removed outdated management commands
- Updated URL namespacing examples to use workflows:marketplace

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude 2025-07-29 20:44:31 +05:30
parent fe6dbe1e58
commit 6c665f3072
2 changed files with 79 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
CLAUDE.md
View File

@ -37,7 +37,7 @@ MAKE ALL FIXES AND CODE CHANGES AS SIMPLE AS HUMANLY POSSIBLE. THEY SHOULD ONLY
## Project Overview ## Project Overview
Quantum Tasks AI is a Django-based AI agent marketplace platform where users can purchase and interact with specialized AI agents. The system supports both webhook-based and API-based agents with integrated payment processing via Stripe. Quantum Tasks AI is a Django-based AI agent marketplace platform where users can purchase and interact with specialized AI agents. The system uses a unified workflows architecture with direct N8N webhook integration for maximum scalability and maintainability.
## Development Commands ## Development Commands
@ -55,18 +55,12 @@ pip install -r requirements.txt
### Database Operations ### Database Operations
```bash ```bash
# Check database configuration
python manage.py check_db
# Create and apply migrations # Create and apply migrations
python manage.py makemigrations python manage.py makemigrations
python manage.py migrate python manage.py migrate
# Backup user data # Check Django configuration
python manage.py backup_users --action info python manage.py check
# Populate agent catalog
python manage.py populate_agents
``` ```
### Development Server ### Development Server
@ -80,33 +74,17 @@ python manage.py runserver
### Testing ### Testing
```bash ```bash
# Run specific agent tests
python tests/test_weather_agent.py
python tests/test_five_whys_webhook.py
# Test homepage functionality
python tests/test_homepage.py
# Test health check endpoint # Test health check endpoint
curl http://localhost:8000/health/ curl http://localhost:8000/health/
# Test agent configuration loading
DJANGO_SETTINGS_MODULE=netcop_hub.settings python -c "import django; django.setup(); from workflows.config.agents import get_all_agents; print(f'✅ {len(get_all_agents())} agents loaded')"
``` ```
### Custom Management Commands ### File Management
```bash ```bash
# Create new agent # File uploads are stored in media/uploads/
python manage.py create_agent # Files are automatically cleaned up after processing
# Create test user
python manage.py create_user
# Reset database (development only)
python manage.py reset_database
# Test webhook functionality
python manage.py test_webhook
# Cleanup uploaded files
python manage.py cleanup_uploads
``` ```
### Documentation Management ### Documentation Management
@ -144,36 +122,30 @@ python manage_n8n_workflows.py backup
## Architecture Overview ## Architecture Overview
### Agent System Architecture (`agent_base/`) ### Unified Workflows System Architecture
**Centralized Agent Management:** **Scalable Plugin-Based Design:**
- `agent_base/models.py` - `BaseAgent` model for marketplace catalog The system uses a unified workflows architecture that eliminates the scalability issues of hard-coded agent handling. All agents are processed through a single, extensible system.
- `agent_base/processors.py` - `BaseAgentProcessor` abstract class for agent interactions
- `agent_base/views.py` - Marketplace and agent discovery views
- `agent_base/urls.py` - Agent system URL routing
- `agent_base/generators/` - Template generation system for creating new agents
- `templates/agent_base/` - Marketplace and agent catalog templates
**Agent Types:** ### Core Components
1. **Webhook Agents** - Process requests via external N8N webhook APIs (require N8N workflows)
- `data_analyzer` - File analysis and insights
- `social_ads_generator` - Social media ad creation
- `job_posting_generator` - Professional job postings
- `five_whys_analyzer` - Root cause analysis
2. **API Agents** - Direct API integration for immediate responses
- `weather_reporter` - OpenWeather API integration
- `email_writer` - Custom email composition logic
**Individual Agent Apps:** **Workflows App (`workflows/`):**
Each agent is a separate Django app following this structure: - `workflows/views.py` - Unified handler for all agents with plugin architecture
- `models.py` - Agent-specific request/response models - `workflows/processors/` - Agent-specific processing logic with shared base class
- `processor.py` - Inherits from `BaseAgentProcessor`, implements specific logic - `workflows/config/agents.py` - Simple 5-line agent configuration system
- `views.py` - Agent detail page and request handling - `workflows/templates/workflows/` - Individual agent templates with shared components
- `templates/[agent_name]/detail.html` - Agent interface
- `urls.py` - Agent-specific URL routing **Working Agents:**
- `n8n_workflows/` - N8N workflow configurations (webhook agents only) 1. **Social Ads Generator** - Create engaging social media advertisements (6.0 AED)
- `workflow.json` - Production workflow 2. **Job Posting Generator** - Create professional job postings (10.0 AED)
- `README.md` - Setup and configuration documentation 3. **Data Analyzer** - AI-powered analysis of data files (8.0 AED)
**Agent System Architecture:**
- Configuration-driven agent definitions in `workflows/config/agents.py`
- Dynamic template loading based on agent slug
- Direct N8N webhook integration with no Django fallbacks
- Shared CSS from main static directory (`{% static 'css/agent-base.css' %}`)
- Self-contained JavaScript utilities in main static directory (`{% static 'js/workflows-core.js' %}`)
### N8N Workflow Architecture ### N8N Workflow Architecture
@ -251,40 +223,40 @@ User Request → Django App (Railway) → HTTP POST → N8N Instance (Separate H
/pricing/ # Pricing page (core app) /pricing/ # Pricing page (core app)
/health/ # Health check endpoint for monitoring (core app) /health/ # Health check endpoint for monitoring (core app)
/contact/ # Contact form submission (core app) /contact/ # Contact form submission (core app)
/marketplace/ # Agent marketplace (agent_base app) /agents/ # Agent marketplace (workflows app)
/agents/<slug>/ # Agent detail redirect (agent_base app) /agents/<agent-slug>/ # Unified workflows system for all agents
/auth/ # Authentication (login, register, profile) /auth/ # Authentication (login, register, profile)
/wallet/ # Wallet management and top-up (wallet app) /wallet/ # Wallet management and top-up (wallet app)
/wallet/stripe/ # Stripe webhooks and debug (wallet app) /wallet/stripe/ # Stripe webhooks and debug (wallet app)
/agents/[agent-slug]/ # Individual agent pages (individual apps)
/workflows/<agent-slug>/ # Unified workflows app agent processing (NEW)
/admin/ # Django admin /admin/ # Django admin
/api/agents/ # Agent API endpoint (agent_base app)
``` ```
### Template Architecture ### Template Architecture
**Template Hierarchy:** **Component-Based System:**
- `templates/base.html` - Main layout with navigation and auth - `templates/base.html` - Main layout with navigation and auth
- `templates/components/` - Reusable components (agent_header, wallet_card, etc.) - `templates/components/` - Reusable components (agent_header, wallet_card, etc.)
- `templates/core/` - Platform pages (homepage, pricing) - `templates/core/` - Platform pages (homepage, pricing)
- `templates/agent_base/` - Agent marketplace and catalog
- `templates/wallet/` - Payment and wallet management - `templates/wallet/` - Payment and wallet management
- `templates/authentication/` - User authentication pages - `templates/authentication/` - User authentication pages
- Agent-specific templates in individual app directories - `workflows/templates/workflows/` - Individual agent templates using shared components
- `workflows/templates/workflows/marketplace.html` - Agent marketplace
**CSS Architecture:** **CSS Architecture:**
- `base.css` - Global styles and CSS variables - `base.css` - Global styles and CSS variables
- `agent-base.css` - Agent page styling - `agent-base.css` - Agent page styling
- `header-component.css` - Header styling (replaces deprecated header.css) - `header-component.css` - Header styling
- Component-specific CSS files - Component-specific CSS files
### Database Design ### Database Design
**Key Models:** **Key Models:**
- `BaseAgent` - Agent catalog and marketplace data
- `User` - Extended Django user with wallet functionality - `User` - Extended Django user with wallet functionality
- Agent-specific request models (e.g., `WeatherReportAgentRequest`) - `WorkflowRequest` - Agent processing requests
- `WorkflowResponse` - Agent processing results
- `WorkflowAnalytics` - Usage analytics and metrics
**Note:** Agent metadata is now configuration-driven via `workflows/config/agents.py` instead of database models.
### Environment Configuration ### Environment Configuration
@ -296,57 +268,41 @@ Required environment variables (see `.env.example`):
### Simplified Agent Creation Process ### Simplified Agent Creation Process
**New Streamlined Workflow (90% less complexity!):** **New agents require only 5 lines of configuration:**
The workflows app now uses a dramatically simplified agent creation process. No more complex configurations or dynamic field systems - just simple metadata and individual templates. #### **Step 1: Add Agent Configuration**
### 4-Step Agent Creation Process
#### **Step 1: Add Agent Configuration (5 lines)**
```python ```python
# In workflows/config/agents.py - add to AGENT_CONFIGS # In workflows/config/agents.py - add to AGENT_CONFIGS
'your-agent-slug': { 'your-agent-slug': {
'name': 'Your Agent Name', 'name': 'Your Agent Name',
'description': 'What this agent does', 'description': 'What this agent does',
'category': 'utilities', # or 'marketing', 'analytics', 'content'
'price': 3.0, 'price': 3.0,
'icon': '🤖', 'icon': '🤖',
'webhook_url': 'http://localhost:5678/webhook/your-webhook-id', 'webhook_url': 'http://localhost:5678/webhook/your-webhook-id',
}, },
``` ```
#### **Step 2: Create Individual Template** #### **Step 2: Create Template**
```django
<!-- Copy workflows/templates/workflows/agent-template-starter.html -->
<!-- Customize form fields for your agent -->
<!-- All shared components included automatically -->
```
#### **Step 3: Test Agent**
```bash ```bash
# CORRECT: Start with agent template prototype for reference # Agent automatically available at /agents/{slug}/
# Reference: agent_template_prototype.html (perfect UI patterns) # Plugin architecture handles everything automatically
# Then copy the starter template
cp workflows/templates/workflows/agent-template-starter.html workflows/templates/workflows/your-agent.html
# Customize the template by replacing:
# - Form fields section with your agent-specific inputs
# - Processing messages and result titles
# - How it works steps (optional)
# ⚠️ NEVER copy from existing agent templates (leads to bloat!)
``` ```
#### **Step 3: Add Template Mapping** ### Benefits of New Architecture
```python
# In workflows/views.py - add to template_mapping dict
template_mapping = {
'social-ads-generator': 'workflows/social-ads-generator.html',
# ... existing mappings ...
'your-agent-slug': 'workflows/your-agent.html', # <-- Add this line
}
```
#### **Step 4: Optional - Add to Marketplace** - ✅ **Infinite Scalability** - New agents need only 5 lines of config
```python - ✅ **No Code Duplication** - Shared processors and webhook strategies
# If you want the agent in the marketplace - ✅ **Plugin Architecture** - Dynamic processor loading
from agent_base.models import BaseAgent - ✅ **Consistent UI** - Shared components across all agents
- ✅ **Easy Maintenance** - Single codebase for all agent processing
BaseAgent.objects.create( - ✅ **Type Safety** - Abstract base classes enforce proper implementation
name="Your Agent Name",
slug="your-agent-slug", slug="your-agent-slug",
description="What this agent does", description="What this agent does",
price=3.0, price=3.0,
@ -663,22 +619,22 @@ curl http://localhost:8000/health/
**Single Responsibility:** **Single Responsibility:**
- `core` - Platform presentation and static pages only - `core` - Platform presentation and static pages only
- `agent_base` - Agent marketplace, catalog, and cross-agent functionality - `workflows` - Unified agent processing with plugin architecture and marketplace
- `wallet` - Complete payment system with Stripe integration - `wallet` - Complete payment system with Stripe integration
- Individual agent apps - Specific agent logic and interfaces - `authentication` - User authentication and management
**URL Namespacing:** **URL Namespacing:**
- Use `agent_base:marketplace` for marketplace links - Use `workflows:marketplace` for marketplace links
- Use `workflows:agent` for individual agent pages
- Use `wallet:wallet` for wallet-related links - Use `wallet:wallet` for wallet-related links
- Use `core:homepage` for platform homepage - Use `core:homepage` for platform homepage
- Individual agents have their own URL namespaces
**Template Organization:** **Template Organization:**
- Templates are organized by app responsibility - Templates are organized by app responsibility
- Use proper URL namespacing in templates - Use proper URL namespacing in templates
- Marketplace functionality is in `agent_base` app, not `core` - All agent functionality unified in `workflows` app
Always run `python manage.py check_db` before making database-related changes to ensure proper configuration. Always run `python manage.py check` before making database-related changes to ensure proper configuration.
--- ---
Last updated: Last updated: Last updated: Last updated: Last updated: Last updated: Last updated: Last updated: 2025-07-29 20:04:46 Last updated: Last updated: Last updated: Last updated: Last updated: Last updated: Last updated: Last updated: Last updated: 2025-07-29 20:12:03

18
docs_update_summary.txt
View File

@ -1,20 +1,26 @@
=== Documentation Auto-Update Summary === === Documentation Auto-Update Summary ===
Update Date: 2025-07-29 20:08:47 Update Date: 2025-07-29 20:12:03
Recent Commits: Recent Commits:
- fe6dbe1 🔧 Fix wallet NoReverseMatch error - update agent_base references
- 94a8655 Improve marketplace layout: search above, category buttons below - 94a8655 Improve marketplace layout: search above, category buttons below
- bc160b1 🎯 Keep only working agents and simplify marketplace view - bc160b1 🎯 Keep only working agents and simplify marketplace view
- ec42b51 🗑️ Complete agent_base app removal and legacy cleanup
Documentation Changes: Agents Changes:
- CLAUDE.md - templates/components/quick_agents_panel.html
Frontend Changes: Frontend Changes:
- workflows/templates/workflows/marketplace.html - templates/403.html
- templates/404.html
- templates/500.html
- templates/wallet/wallet.html
- templates/wallet/wallet_topup.html
Backend Changes: Backend Changes:
- docs_update_summary.txt - docs_update_summary.txt
No documentation files required updates. Updated Documentation Files:
- /home/amit/projects/quantum_ai_v2/CLAUDE.md
- /home/amit/projects/quantum_ai_v2/docs/development/agent-creation.md
=== End Summary === === End Summary ===