Issue: CI failing with "UndefinedValueError: SECRET_KEY not found"
Root Cause: Settings modules load env vars at import time, before
conftest.py can set TESTING=true
Fix: Add minimal test environment variables to CI workflow
- SECRET_KEY for security module
- Database credentials (not used, but required for imports)
- API keys (fake values for testing, not used)
- Reddit credentials (not used in tests)
All values are fake/test-only and do not expose real credentials.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Bug: AttributeError: 'int' object has no attribute 'encode'
Root Cause: StreamingResponse error paths (no session, no result) were
using raw bytes instead of iterators
Fix:
- Import Response from starlette.responses
- Replace StreamingResponse with Response for error paths:
- No session ID (line 189)
- No result available (line 201)
- PDF success path already uses iterfile() generator (correct)
This prevents the encode error when PDF download fails validation checks.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Created TEST_COVERAGE_GAPS.md documenting areas needing test coverage.
Organized by priority with specific test suggestions for each gap.
High Priority Gaps:
- E2E test for complete analysis flow (form → celery → status → result → PDF)
- AI agent testing (SWOT generation, tool use, error handling)
- Input validation/sanitization (SQL injection, XSS, SSRF)
- PDF cache memory limits (no eviction policy currently)
- Dependency security scanning (4 high-severity vulnerabilities)
Medium Priority Gaps:
- Database operations (persistence, migrations, transactions)
- HTMX OOB swap DOM validation (verify correct structure)
- Load testing (concurrency, memory leaks, queue saturation)
- PDF security (size limits, timeouts, content sanitization)
- Deployment validation (Docker build, env vars, health checks)
Low Priority Gaps:
- Frontend Jinjax component testing
- Cross-browser compatibility
- Accessibility (WCAG 2.1 AA compliance)
- Logging and error tracking
- Test data fixtures
For each gap, document includes:
- Description of the gap
- Current coverage status
- Specific test suggestions
- Priority and effort estimates
Ready to convert to GitHub issues using provided template.
Current Coverage: ~15%
Target Coverage: 80%
Critical Path Target: 95%
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Bug: TemplateNotFound: 'status.html' not found
Cause: status.html was deleted during Jinjax refactor but analyze_url
endpoint still referenced it
Fix: Return empty HTMLResponse instead of template
- HTMX polling with hx-swap="none" doesn't need initial content
- All status rendering happens via OOB swaps from /status endpoint
- Empty response simply acknowledges form submission
This regression occurred because the Jinjax refactor removed status.html
but didn't update the analyze_url endpoint that used it.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Fixed two critical errors preventing PDF downloads:
1. KeyError: "Style 'BodyText' already defined in stylesheet"
- Renamed custom style from "BodyText" to "ReportBodyText"
- BodyText is a reserved ReportLab built-in style name
- Updated all references to use new name
2. AttributeError: 'int' object has no attribute 'encode'
- StreamingResponse expected an iterator, not BytesIO directly
- Added iterfile() generator function to yield BytesIO chunks
- Properly resets buffer position with seek(0) before iteration
Additional:
- Removed unused hex_to_rgb_tuple() function (dead code cleanup)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Replaced raw HTML string concatenation with proper Jinjax components
following the project's established component patterns.
Component Architecture:
- StatusItem.jinja: Individual status message component
* Accepts: message, is_last, result, use_oob
* Determines status type (error/loading/complete/info) automatically
* Renders with appropriate icons and styling
* Optional HTMX OOB swap for dynamic appending
- StatusTimeline.jinja: Container component for status items
* Provides semantic HTML structure with ARIA labels
* Optional HTMX OOB swap for initial insertion
* Children appended via HTMX to #status-timeline
Backend Changes:
- Removed raw HTML string templates (anti-pattern)
- Use catalog.render() for all component rendering
- First poll: Render StatusTimeline + StatusItem components with OOB
- Subsequent polls: Render only new StatusItem components with OOB
- Clean separation of concerns (backend = logic, Jinjax = presentation)
Frontend Changes:
- Changed #status div to hx-swap="none" (all updates via OOB)
- Removed old status.html and status_item.html templates
- StatusItem and StatusTimeline now in components/snippets/
Benefits:
- No raw HTML in Python code
- Reusable Jinjax components
- Consistent with project patterns
- Easier to maintain and test
- Clean separation of presentation and logic
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Issue: PDF download button wasn't working because Alpine.js doesn't
automatically initialize on dynamically loaded HTMX content. The
result.html template is loaded via HTMX polling, and the x-data
directive wasn't being processed on the new DOM elements.
Solution: Replaced the Alpine.js-powered button with a simple anchor
tag styled as a button. This works immediately without requiring
Alpine initialization and properly triggers browser download behavior.
Changes:
- Removed x-data, @click, :disabled, :class Alpine directives
- Changed <button> to <a> with href="{{ url_for('download_pdf') }}"
- Added download attribute for proper download hint
- Kept all styling and accessibility features
- Simplified implementation without loading state (unnecessary for downloads)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The status-timeline container was missing its id attribute, causing
HTMX out-of-band swaps to fail silently. Status items were being
generated but not appended to the DOM because the OOB swap directive
hx-swap-oob="beforeend:#status-timeline" couldn't find the target.
Fixed by adding id="status-timeline" to the status timeline div.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Explicitly set background-color to white for executive summary to fix
dark text on dark background readability issue.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Replace full container refresh with incremental status item appends
using HTMX Out-of-Band swaps for smoother UX without flashing.
Problem:
- Status container innerHTML swap replaced entire timeline every second
- All items re-rendered causing visual flashing even with CSS transitions
- Inefficient: re-sends all messages every poll
Solution:
- Track last message index per session
- Return only NEW messages since last poll
- Use HTMX hx-swap-oob="beforeend:#status-timeline" to append items
- First poll returns full container, subsequent polls return only deltas
Architecture:
1. Session Tracking (consts.py):
- Added last_message_index dict to track per-session state
- Memory-based, resets on server restart (acceptable for dev)
2. New Template (status_item.html):
- Single status article with OOB swap attribute
- Reusable component for incremental updates
3. Backend Logic (router.py):
- First poll: full status.html with all messages
- Subsequent: only new messages with OOB attributes
- Empty response if no new messages
4. Frontend (home.html):
- Removed settle:200ms (no longer needed)
- Status timeline receives appended items
Benefits:
- Eliminates flashing during updates
- More efficient (only sends deltas)
- Smoother perceived performance
- No JavaScript state management required
- Automatic HTMX OOB handling
Technical Details:
- OOB swap: Items append to #status-timeline automatically
- Session index tracks progress per analysis
- First poll initializes container structure
- Graceful degradation if session tracking resets
Testing:
- Verify first poll shows container + all messages
- Verify subsequent polls append only new items
- Verify no flashing during status updates
- Verify empty responses when no new messages
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Fix poor contrast issues in hero title and executive summary text
to meet WCAG 2.1 AA standards (4.5:1 minimum ratio).
Problems:
1. Hero title: Purple gradient text on purple background (low contrast)
2. Executive summary: Dark gray text potentially hard to read
Root Cause:
- .hero-title used gradient with transparent text fill
- Gradient purple + purple background = poor visibility
- CSS custom properties (--neutral-700) may not resolve correctly
Solution:
1. Hero Title: Replace gradient with solid white (#FFFFFF)
- Adds subtle text shadow for depth
- High contrast on purple gradient background (21:1 ratio)
2. Executive Summary: Use explicit hex color
- Replace var(--neutral-700) with #374151
- Add font-size: 1rem for consistency
- Ensures readability on white background (10.6:1 ratio)
Changes:
- _typography.scss: Solid white hero title with text shadow
- result.html: Explicit color for executive summary
WCAG Compliance:
- Hero title: 21:1 ratio (AAA) ✅
- Executive summary: 10.6:1 ratio (AAA) ✅
- Both exceed 4.5:1 minimum for AA compliance
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add HTMX settle delay and CSS transitions to make status updates
less jarring when the entire container refreshes.
Problem:
- Status container innerHTML swap replaces entire timeline
- All status items re-render causing visible flash
- Jarring UX during updates
Solution:
- Add HTMX settle:200ms modifier for smoother swaps
- Add CSS transitions for .htmx-swapping and .htmx-settling classes
- HTMX automatically applies these classes during swap lifecycle
Changes:
- home.html: hx-swap="innerHTML settle:200ms"
- _animations.scss: Add .htmx-swapping and .htmx-settling transitions
- Smooth fade during swap (opacity 0.7) and settle (opacity 1)
Technical Details:
- HTMX swap lifecycle: swapping → settling (200ms each)
- CSS transition: 150ms ease for smooth opacity changes
- Still replaces full container but visually smoother
Result:
- Less jarring status updates
- Smooth fade during refresh
- Better perceived performance
- Maintains current architecture (no backend changes)
Future Enhancement:
Consider HTMX OOB swaps to append only new items instead of
replacing entire container for even better UX.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Remove double wrapping and add DOM-based polling stop condition to
prevent container flashing and endless polling.
Problems:
1. Status/results containers flash during updates
2. Polling continues forever even after results load
3. Double wrapping: home.html box + backend template section
Root Cause:
- home.html wrapped backend templates in <div class="box">
- Backend templates return complete <section> elements with styling
- No condition to stop polling after results appear
Solution:
- Remove class="box" wrapper from home.html (backend handles styling)
- Add DOM check to stop polling: [!document.querySelector('#result-container')]
- Polling stops once #result-container appears in DOM
Changes:
- Removed class="box" from status div
- Removed class="box" from results div
- Added polling stop condition to both divs
- HTMX checks DOM every second, stops when results exist
Result:
- No more flashing containers (single wrapper)
- Smooth content updates without re-rendering parent
- Polling stops automatically when analysis complete
- Better performance (no unnecessary requests)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Fix status and results not loading by removing HTMX conditions that
don't react to Alpine state changes and simplifying visibility logic.
Problems:
1. HTMX trigger conditions [analyzing] don't react to Alpine state
2. Status div hidden initially (x-show with hasStatus requirement)
3. Chicken-and-egg: hasStatus needed to show, but only set on response
4. HTMX doesn't poll hidden elements effectively
Solution:
- Remove HTMX conditional triggers [analyzing], [analyzing && !hasResults]
- Simplify status visibility: x-show="analyzing && !hasResults"
- Let HTMX poll unconditionally with "every 1s"
- Alpine x-show controls visibility, HTMX polls when visible
- Cleaner event handlers with explicit response checking
Changes:
- Status: removed hasStatus from x-show condition
- Status: hx-trigger="every 1s" (no conditions)
- Results: hx-trigger="every 1s" (no conditions)
- Better response validation in @htmx:after-request
Result:
- Status updates appear immediately when analyzing starts
- Status polls continuously until results arrive
- Results polling works correctly
- Proper state transitions: analyzing → hasResults
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add Alpine.js x-cloak directive and CSS to prevent spinner from
showing during Alpine initialization.
Problem:
- Spinner briefly visible on initial page load before Alpine.js initializes
- x-show directive not applied until Alpine loads
- Creates confusing FOUC (Flash of Unstyled Content)
Solution:
- Add x-cloak attribute to spinner div
- Add [x-cloak] { display: none !important; } CSS
- Alpine removes x-cloak after initialization, allowing x-show to work
Result:
- Spinner hidden on initial page load
- Only shows when analyzing state is true
- Clean page load experience
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Upgrade from Python 3.12.3 to Python 3.13.3 using deadsnakes PPA.
Changes:
- Add build.sh execution in Dockerfile to install Python 3.13
- Install Python 3.13 from deadsnakes PPA with dev packages
- Set Python 3.13 as default via update-alternatives
- Create venv explicitly with Python 3.13
- Update pyproject.toml to require Python >= 3.13
- Fix line endings in shell scripts (CRLF → LF)
Build process:
1. Adds deadsnakes PPA repository
2. Installs python3.13, python3.13-dev, python3.13-venv, python3.13-distutils
3. Sets as system default Python
4. UV creates venv with Python 3.13
5. All packages install successfully
Tested with FastAPI 0.128.0 - all dependencies working correctly.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Replace external IP-based server.url with internal port-based auto-discovery.
This allows Traefik to correctly communicate with the service via the Docker
proxy network instead of trying to route through external IPs.
Changes:
- Remove: traefik.http.services.pygentic_ai.loadbalancer.server.url
- Add: traefik.http.services.pygentic_ai.loadbalancer.server.port
- Use INTERNAL_PORT (5051) for container communication
This fixes the gateway timeout issues in Komodo deployments.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Replaces os.path.dirname/join chains with Path(__file__).resolve() and /
operator. Updated Settings field types from str to Path to satisfy
pydantic v2 strict coercion.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- result_type -> output_type on Agent (core.py)
- result_validator -> output_validator decorator (tools.py)
- BASE_DIR was operating on the string literal "__name__" instead of
__file__; all paths were relative to CWD and only worked in Docker
because the entrypoint cd's into src/ first (consts.py)
- url_for('static', filename=...) -> path=... to match Starlette's
StaticFiles param name; every other template already used path= (home.html)
Verified locally: all routes and static assets return 200.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
pydantic-ai 0.4.x removed the api_key kwarg from model constructors.
Pass credentials via OpenAIProvider instead.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Gunicorn crashes on container start when these env vars are missing from
stack.env — -w receives no argument and exits immediately. Defaults now
match .env.example values (WORKERS=4, TIMEOUT=120, PORT=5051), consistent
with the bash default syntax already used in compose.yaml.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Rename GitHub repo from Pygentic-AI to strategiq. Update all
user-facing references: README badges/links/prose, page <title>,
hero alt text, CLAUDE.md, system-prompt, justfile comments,
komodo deploy echo, SCSS header comments, and compiled CSS.
Intentionally left unchanged: Docker registry image name
(s3docker.francissecada.com/pygentic_ai), container paths
(/opt/pygentic_ai), DB schema, CSS filenames, Traefik labels,
and the production domain (pygenticai.francissecada.com) — all
operational names that would require infra changes.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add `search_web` tool backed by tavily-python for grounded research
- Extend SWOT pipeline to accept a primary entity plus optional comparison
entities; agent prompt drives comparative analysis when comparators are
present
- Add `primary_entity` / `comparison_entities` fields to SwotAnalysis model
- Wire new form fields (primary + comparison inputs) through router →
utils → run_agent
- Render entity badges ("vs" header) in result template; fix pre-existing
bug where iterating model.dict() leaked the `analysis` string into the
SWOT card grid
- Add comparison-input and entity-badge SCSS components; recompile CSS
- Pin requires-python >=3.12 in pyproject.toml; lock tavily-python 0.7.21
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Remove git clone in Dockerfile, use COPY instead
- Remove SSH agent setup from GitHub Actions workflow
- Remove --ssh and GIT_BRANCH build args
- Fix Unix line endings in shell scripts (dos2unix)
- Simplifies build process and removes SSH dependency
- Enables faster, more reliable CI/CD builds
✅ Local build tested and successful
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Changed .claude\system-prompt.md to .claude/system-prompt.md
Forward slashes work on all platforms (Windows, Linux, macOS)
Also streamlined the start-claude output messages
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Task Automation (justfile):
- Comprehensive justfile with 50+ recipes for all common tasks
- Dynamic argument passing for Docker commands
- Organized categories: dev, docker, testing, deployment, cleanup
- Environment variable substitution for flexible configuration
- Health checks and monitoring commands
- Database migration helpers
- Quality check automation (lint, format, security, test)
Development Workflow:
- just setup - One-command project initialization
- just dev/celery/scss-watch - Multi-terminal dev environment
- just build/deploy - Docker operations with custom tags
- just test/lint/check - Quality assurance automation
- just clean/prune - Cleanup utilities
Multi-Agent Claude Orchestration:
- .claude/system-prompt.md - Multi-agent orchestration system
* 5 specialized personas (🏗️ Architect, 🎨 Frontend, ⚙️ Backend, 🔒 Security, 🚀 DevOps)
* MCP server routing patterns (Sequential, Context7, Magic, Playwright, Morphllm, Serena)
* Task coordination workflows and decision frameworks
* Code quality standards and project-specific patterns
- CLAUDE.md - Project initialization guide
* Technology stack overview
* Project structure documentation
* Key workflows and commands
* Environment configuration guide
* Multi-persona activation patterns
* Quick reference for common tasks
Documentation:
- Updated README.md with comprehensive justfile documentation
* Installation instructions for just
* Quick start guide using justfile
* Complete command reference organized by category
* Claude AI assistance section
* Improved project overview and features
* Development and production workflows
Benefits:
- Consistent command interface across all operations
- Reduced cognitive load - no need to remember complex Docker commands
- Self-documenting workflows with `just --list`
- Claude can intelligently coordinate across multiple domains
- Improved onboarding with clear documentation
Usage:
just # List all commands
just setup # Initialize project
just dev # Start development
just start-claude # View Claude context
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
