mirror of
https://github.com/fsecada01/Pygentic-AI.git
synced 2026-02-11 08:48:23 +00:00
StrategIQ
Built with the tools and technologies:
☀️ Table of Contents
- ☀ ️ Table of Contents
- 🌞 Overview
- 🔥 Features
- 🌅 Project Structure 4.1. 🌄 Project Index
- 🚀 Getting Started 5.1. 🌟 Prerequisites 5.2. ⚡ Installation 5.3. 🔆 Usage 5.4. 🌠 Testing
- 🌻 Roadmap
- 🤝 Contributing
- 📜 License
- ✨ Acknowledgments
🌞 Overview
StrategIQ is an AI-powered SWOT analysis platform that transforms any entity — company, URL, or product — into actionable business intelligence. Using advanced language models (Claude, GPT-4) and web-search grounding via Tavily, the system researches, compares, and generates comprehensive SWOT analyses with competitive intelligence from Reddit and the open web.
Key Capabilities
- 🔍 Intelligent URL Analysis - Extracts and analyzes content from any web page
- 🧠 AI-Powered SWOT - Generates structured SWOT analysis using Claude/GPT-4
- 💬 Reddit Intelligence - Gathers competitive insights from relevant subreddits
- ⚡ Async Processing - Celery-based task queue for long-running analysis
- ♿ Accessible UI - WCAG 2.1 AA compliant responsive interface
- 🎨 Modern Frontend - SCSS modular architecture with progressive enhancement
🔥 Features
AI Analysis Engine
- Multi-model support (Anthropic Claude, OpenAI GPT-4o-mini)
- Tool-augmented generation with Reddit intelligence
- Structured output validation with Pydantic
- Async task processing with Celery
User Interface
- Component-based templates with Jinjax
- HTMX for progressive enhancement
- Modular SCSS architecture (7-1 pattern)
- Full keyboard navigation and screen reader support
- Progressive loading with real-time status updates
Infrastructure
- Docker containerization with multi-stage builds
- GitHub Actions CI/CD with Komodo deployment
- Traefik reverse proxy with Let's Encrypt
- Health checks and monitoring
- Environment-based configuration
🌅 Project Structure
└── strategiq/
├── .github
│ └── workflows
├── bin
│ ├── build.sh
│ ├── linux_build.sh
│ ├── python_build.sh
│ └── start.sh
├── compose.yaml
├── core_requirements.in
├── core_requirements.txt
├── dev_requirements.in
├── dev_requirements.txt
├── docker
│ ├── celery
│ └── pygentic_ai
├── Dockerfile
├── pyproject.toml
├── README.md
├── src
│ ├── app.py
│ ├── backend
│ ├── cworker.py
│ └── frontend
└── uv.lock
🌄 Project Index
strategiq/
__root__
⦿ __root__
File Name Summary compose.yaml Code>❯ REPLACE-ME core_requirements.in Code>❯ REPLACE-ME core_requirements.txt Code>❯ REPLACE-ME dev_requirements.in Code>❯ REPLACE-ME dev_requirements.txt Code>❯ REPLACE-ME Dockerfile Code>❯ REPLACE-ME pyproject.toml Code>❯ REPLACE-ME
bin
⦿ bin
File Name Summary build.sh Code>❯ REPLACE-ME linux_build.sh Code>❯ REPLACE-ME python_build.sh Code>❯ REPLACE-ME start.sh Code>❯ REPLACE-ME
src
⦿ src
File Name Summary app.py Code>❯ REPLACE-ME cworker.py Code>❯ REPLACE-ME backend
frontend
⦿ src.frontendtemplates
⦿ src.frontend.templates
File Name Summary home.html Code>❯ REPLACE-ME result.html Code>❯ REPLACE-ME status.html Code>❯ REPLACE-ME components
⦿ src.frontend.templates.componentsforms
⦿ src.frontend.templates.components.forms
File Name Summary Form.jinja Code>❯ REPLACE-ME Search.jinja Code>❯ REPLACE-ME main
⦿ src.frontend.templates.components.main
File Name Summary base.html Code>❯ REPLACE-ME Base.jinja Code>❯ REPLACE-ME footer.html Code>❯ REPLACE-ME Footer.jinja Code>❯ REPLACE-ME header.html Code>❯ REPLACE-ME Header.jinja Code>❯ REPLACE-ME nav.html Code>❯ REPLACE-ME Nav.jinja Code>❯ REPLACE-ME Scripts.jinja Code>❯ REPLACE-ME Stylesheets.jinja Code>❯ REPLACE-ME style_sheets.html Code>❯ REPLACE-ME snippets
⦿ src.frontend.templates.components.snippets
File Name Summary Css.jinja Code>❯ REPLACE-ME js.html Code>❯ REPLACE-ME Js.jinja Code>❯ REPLACE-ME NavbarBrand.jinja Code>❯ REPLACE-ME NavbarMenu.jinja Code>❯ REPLACE-ME Result.jinja Code>❯ REPLACE-ME ResultEntry.jinja Code>❯ REPLACE-ME Spinner.jinja Code>❯ REPLACE-ME StatusResult.jinja Code>❯ REPLACE-ME
.github
⦿ .githubworkflows
⦿ .github.workflows
File Name Summary bandit.yml Code>❯ REPLACE-ME docker-image.yml Code>❯ REPLACE-ME
docker
⦿ dockercelery
⦿ docker.celery
File Name Summary start.sh Code>❯ REPLACE-ME pygentic_ai
⦿ docker.pygentic_ai
File Name Summary build.sh Code>❯ REPLACE-ME python_build.sh Code>❯ REPLACE-ME python_start.sh Code>❯ REPLACE-ME
🚀 Getting Started
🌟 Prerequisites
This project requires the following dependencies:
- Programming Language: Python 3.13+
- Package Manager: uv (recommended) or pip
- Container Runtime: Docker & Docker Compose
- Task Runner: just (command runner)
- Node.js: For frontend asset compilation (npm)
⚡ Installation
Install just (Task Runner)
macOS/Linux:
# macOS
brew install just
# Linux
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
Windows:
# Using Scoop
scoop install just
# Using Chocolatey
choco install just
Build StrategIQ from Source
-
Clone the repository:
git clone https://github.com/FJS-Services-Inc/strategiq -
Navigate to the project directory:
cd strategiq -
Quick setup with justfile (recommended):
# One command setup: creates .env, installs deps, compiles SCSS just setup -
Manual installation (alternative):
Using docker:
```sh
❯ docker build -t s3docker.francissecada.com/pygentic_ai .
```
Using pip:
```sh
❯ pip install -r core_requirements.txt, dev_requirements.txt
```
If this fails due to platform-specific issues, try this instead:
```sh
❯ pip install -r core_requirements.in, dev_requirements.in
```
Using uv:
```sh
❯ uv sync --all-extras --dev
```
🔆 Usage
Development Mode
Quick start (recommended):
# Terminal 1: Start FastAPI development server
just dev
# Terminal 2: Start Celery worker
just celery
# Terminal 3: Auto-compile SCSS on changes
just scss-watch
Manual start:
# Using uv (recommended)
uv run python src/app.py # FastAPI server
uv run python src/cworker.py # Celery worker
# Using pip
python src/app.py
python src/cworker.py
Production Mode (Docker)
With justfile:
# Build and start all services
just build
just up-d
# Check status
just health
just ps
# View logs
just logs-f
Manual Docker commands:
# Build image
docker build -t s3docker.francissecada.com/pygentic_ai:latest .
# Start services
docker-compose up -d
# View logs
docker-compose logs -f
Available Commands
Run just to see all available commands:
just # List all commands
just --list # Same as above
# Common commands
just setup # First-time setup
just dev # Development server
just test # Run tests
just build [tag] # Build Docker image
just deploy [tag] # Deploy to production
just health # Check service health
just clean # Clean up containers
🌠 Testing
Run all tests:
just test # Quick test run
just test-cov # With coverage report
Manual testing:
# Using uv (recommended)
uv run pytest tests/ -v
uv run pytest tests/ --cov=src --cov-report=html
# Using pip
pytest tests/ -v
Quality checks:
just lint # Run linters
just format # Format code
just security # Security scan
just check # All checks (pre-commit)
🤖 Claude AI Assistance
This project includes a multi-agent orchestration system for Claude AI to assist with development.
Setup
The project includes two key files for Claude integration:
.claude/system-prompt.md- Multi-agent orchestration instructions (personas, MCP routing, patterns)CLAUDE.md- Project initialization guide (architecture, workflows, commands)
Available Personas
Claude activates appropriate personas based on the task:
- 🏗️ Architect - System design, architecture decisions, scaling
- 🎨 Frontend - UI/UX, SCSS, accessibility, Jinjax components
- ⚙️ Backend - FastAPI, Celery, database, AI agents
- 🔒 Security - Authentication, secrets, input validation
- 🚀 DevOps - Docker, CI/CD, deployment, monitoring
Usage
# View Claude context files
just start-claude # Display orchestration context
# When using Claude
# Use /init command to load project context from CLAUDE.md
# Claude will activate appropriate personas for your task
Example Workflows
Feature Development:
User: "Add user authentication"
Claude: Activates 🏗️ Architect, 🔒 Security, ⚙️ Backend, 🎨 Frontend
- Designs auth architecture
- Implements secure endpoints
- Creates login UI components
- Updates deployment configs
Bug Fixing:
User: "Fix SCSS compilation error"
Claude: Activates 🎨 Frontend persona
- Identifies SCSS syntax issues
- Runs just scss to verify fix
- Updates documentation if needed
📋 Justfile Command Reference
Quick reference for common just commands:
Development
just setup # First-time project setup
just dev # Start FastAPI dev server
just celery # Start Celery worker
just scss # Compile SCSS once
just scss-watch # Auto-compile SCSS on changes
just npm-install # Install frontend dependencies
Docker Operations
just build [tag] # Build Docker image
just up # Start services
just up-d # Start in detached mode
just down # Stop services
just restart # Restart services
just logs-f # Follow all logs
just logs-web # Follow web service logs
just logs-celery # Follow celery logs
just health # Check service health
just ps # Show container status
just stats # Show resource usage
Testing & Quality
just test # Run test suite
just test-cov # Run with coverage
just lint # Run linters
just format # Format code
just security # Security scan
just check # All quality checks
Deployment
just deploy [tag] # Deploy with specific tag
just deploy-dev # Deploy dev environment
just deploy-main # Deploy production
just pull [tag] # Pull Docker image
Database
just migrate # Run migrations
just migration [name] # Create migration
Cleanup
just clean # Remove containers
just clean-images # Remove images
just clean-all # Full cleanup
just prune # Remove unused resources
Utilities
just info # Show environment info
just config # Show Docker Compose config
just check-env # Validate environment variables
just init-env # Create .env from template
For a complete list: just --list
🌻 Roadmap
Task 1: Bootstrap a minimal application buildTask 2: Implement DB Backend with PostgreSQLTask 3: Integrate user auth and group controls
🤝 Contributing
- 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
- 🐛 Report Issues: Submit bugs found or log feature requests for the
StrategIQproject. - 💡 Submit Pull Requests: Review open PRs, and submit your own PRs.
Contributing Guidelines
- Fork the Repository: Start by forking the project repository to your github account.
- Clone Locally: Clone the forked repository to your local machine using a git client.
git clone https://github.com/FJS-Services-Inc/strategiq - Create a New Branch: Always work on a new branch, giving it a descriptive name.
git checkout -b new-feature-x - Make Your Changes: Develop and test your changes locally.
- Commit Your Changes: Commit with a clear message describing your updates.
git commit -m 'Implemented new feature x.' - Push to github: Push the changes to your forked repository.
git push origin new-feature-x - Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
- Review: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!
Contributor Graph
📜 License
StrategIQ is protected under the LICENSE License. For more details, refer to the LICENSE file.
✨ Acknowledgments
- Credit
contributors,inspiration,references, etc.