mirror of
https://github.com/MervinPraison/PraisonAIUI.git
synced 2026-11-07 13:56:36 -10:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 MervinPraison
|
ea615f9d88 |
No files matched your search
@@ -1,375 +0,0 @@
|
||||
---
|
||||
description: Comprehensive analysis workflow that produces a detailed GitHub issue — combines deep codebase analysis with issue creation for implementation-ready tickets
|
||||
---
|
||||
|
||||
# Analysis → GitHub Issue Workflow
|
||||
|
||||
Deep Analysis → Gap Analysis → Critical Review → Plan → Create GitHub Issue.
|
||||
|
||||
> **When to use this:** You need to analyze a feature, integration, or system deeply and produce a GitHub issue that another agent/developer can implement immediately without asking follow-up questions.
|
||||
> **When NOT to use this:** Use `/analysis` for analysis-only (no issue). Use `/local-fix` if you're implementing yourself.
|
||||
|
||||
---
|
||||
|
||||
## PRINCIPLES (apply throughout)
|
||||
|
||||
- **Agent-centric**: Agents, workflows, sessions, tools, memory, multi-agent safety.
|
||||
- **Protocol-driven core**: praisonaiagents = lightweight, protocol-first (protocols/hooks/adapters only).
|
||||
- **DRY**: identify reuse; avoid duplication.
|
||||
- **No perf impact**: preserve import-time and hot-path; heavy deps optional + lazy.
|
||||
- **Async-safe + multi-agent safe** by default.
|
||||
- **Easy for non-developers**: "Few lines of code to do the task!"
|
||||
- **No competitor names in public surfaces**: Never mention competitor product, company, or project names in GitHub issues, PRs, commit messages, release notes, docs, or any other public-facing content. Refer to capabilities generically (e.g., "self-improving agent pattern", "external agent framework").
|
||||
|
||||
---
|
||||
|
||||
## CANONICAL PATHS
|
||||
|
||||
```
|
||||
UI Repo: /Users/praison/praisonaiui (praisonaiui)
|
||||
SDK Core: /Users/praison/praisonai-package/src/praisonai-agents (praisonaiagents)
|
||||
Docs: /Users/praison/PraisonAIDocs
|
||||
Extension: src/praisonaiui/*, docs/*, tests/*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Acceptance Criteria
|
||||
|
||||
Translate the request into testable criteria:
|
||||
- API expectations (classes, methods, signatures)
|
||||
- CLI expectations (commands, flags, help text)
|
||||
- Documentation expectations (pages, examples)
|
||||
- Test expectations (unit, integration, smoke, real agentic)
|
||||
- Performance constraints (import time, hot-path)
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — External Research (if applicable)
|
||||
|
||||
### 2a. Read official sources
|
||||
|
||||
If analyzing an external integration, research from primary sources:
|
||||
|
||||
```bash
|
||||
# Use read_url_content tool for:
|
||||
# - Official site / announcement pages
|
||||
# - GitHub README and docs
|
||||
# - Framework documentation
|
||||
# - Third-party write-ups
|
||||
```
|
||||
|
||||
**Capture:**
|
||||
- What is it? Purpose and design goals
|
||||
- Key terminology and concepts
|
||||
- Architecture overview
|
||||
- Current ecosystem state
|
||||
- References list (all URLs)
|
||||
|
||||
### 2b. Clone & analyze external codebase (if applicable)
|
||||
|
||||
```bash
|
||||
git clone <repo-url> ~/<repo-name> --depth=1
|
||||
ls -la ~/<repo-name>/
|
||||
```
|
||||
|
||||
Key files to read:
|
||||
- `AGENTS.md` / `README.md` — architecture overview
|
||||
- Base class files (abstract methods, signatures)
|
||||
- Factory / registry files (registration pattern)
|
||||
- Model/config files (data structures)
|
||||
- Example implementations (minimal + full-featured)
|
||||
- `pyproject.toml` / `package.json` — dependencies
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — PraisonAI Codebase Inventory
|
||||
|
||||
### 3a. Inventory with evidence
|
||||
|
||||
Go through ALL relevant files, understand current logic end-to-end.
|
||||
|
||||
```bash
|
||||
# UI repo
|
||||
ls /Users/praison/praisonaiui/src/praisonaiui/
|
||||
ls /Users/praison/praisonaiui/tests/
|
||||
ls /Users/praison/praisonaiui/docs/
|
||||
|
||||
# Optional cross-check against SDK only when needed
|
||||
ls /Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/
|
||||
```
|
||||
|
||||
**Document:**
|
||||
- Public APIs: modules/classes/functions and exports
|
||||
- Protocols/adapters/hooks and extension points
|
||||
- CLI commands, options, help text
|
||||
- Integrations (db/observability/tools)
|
||||
- Tests (unit/integration), fixtures, CI config
|
||||
- Docs (Mintlify), examples, recipes
|
||||
|
||||
Provide: **file paths + key symbols + grep counts + entry points**.
|
||||
|
||||
### 3b. Identify DRY opportunities
|
||||
|
||||
- Existing abstractions that can be reused
|
||||
- Duplicated code that should be consolidated
|
||||
- Existing protocols before creating new ones
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Detailed Analysis
|
||||
|
||||
### 4a. Architecture and behavior
|
||||
|
||||
- Control flow and data flow
|
||||
- Concurrency model (sync/async)
|
||||
- Multi-agent interactions
|
||||
- Dependency boundaries (core/wrapper/tools)
|
||||
- Failure modes and error handling
|
||||
|
||||
### 4b. Invariants check
|
||||
|
||||
Verify these are preserved:
|
||||
- [ ] Protocol-driven core (no heavy impls in praisonaiagents)
|
||||
- [ ] Lazy imports (optional deps never at module level)
|
||||
- [ ] Backward compatible (public API changes need deprecation)
|
||||
- [ ] Safe defaults (new features opt-in)
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Gap Analysis
|
||||
|
||||
Compare acceptance criteria vs current state.
|
||||
|
||||
### Checklist
|
||||
|
||||
| Area | Current State | Gap | Severity | Impact | Placement |
|
||||
|------|---------------|-----|----------|--------|-----------|
|
||||
| Core SDK | | | | | |
|
||||
| Wrapper | | | | | |
|
||||
| Tools/plugins | | | | | |
|
||||
| CLI | | | | | |
|
||||
| Docs | | | | | |
|
||||
| Tests | | | | | |
|
||||
| Exports | | | | | |
|
||||
| Perf | | | | | |
|
||||
| Multi-agent + async | | | | | |
|
||||
|
||||
### Gap severity levels
|
||||
- **Critical**: Blocks functionality
|
||||
- **High**: Significant limitation
|
||||
- **Medium**: Missing feature
|
||||
- **Low**: Nice-to-have
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — Critical Review
|
||||
|
||||
### 6a. Risks and footguns
|
||||
|
||||
- API ambiguity or edge cases
|
||||
- Backward compatibility concerns
|
||||
- Coupling violations
|
||||
- Performance regressions
|
||||
- Concurrency hazards
|
||||
- Misuse risks
|
||||
- Operational concerns
|
||||
|
||||
### 6b. Mitigation strategies
|
||||
|
||||
For each risk, document:
|
||||
- "Safe by default" recommendation
|
||||
- Explicit opt-in for dangerous behavior
|
||||
- Documentation warnings
|
||||
|
||||
---
|
||||
|
||||
## Phase 7 — Implementation Plan
|
||||
|
||||
Step-by-step plan (DO NOT implement):
|
||||
|
||||
### 7a. Test-first (TDD)
|
||||
|
||||
1. Unit tests for new functionality
|
||||
2. Integration tests for cross-component behavior
|
||||
3. Smoke tests for quick validation
|
||||
4. **Real agentic tests** (REQUIRED):
|
||||
```python
|
||||
from praisonaiagents import Agent
|
||||
agent = Agent(name="test", instructions="You are helpful")
|
||||
result = agent.start("Say hello in one sentence")
|
||||
print(result) # Must call LLM and produce response
|
||||
```
|
||||
|
||||
### 7b. Implementation order
|
||||
|
||||
1. Tests (TDD)
|
||||
2. Core implementation
|
||||
3. CLI integration
|
||||
4. Documentation
|
||||
5. Verification
|
||||
|
||||
### 7c. Files to change/create
|
||||
|
||||
| File | Action | Purpose |
|
||||
|------|--------|---------|
|
||||
| | | |
|
||||
|
||||
### 7d. Verification commands
|
||||
|
||||
```bash
|
||||
# Unit tests
|
||||
pytest tests/unit/test_<feature>.py -v
|
||||
|
||||
# Integration tests
|
||||
pytest tests/integration/test_<feature>.py -v
|
||||
|
||||
# Smoke test
|
||||
python -c "from praisonaiagents import <Feature>; print('OK')"
|
||||
|
||||
# Real agentic test
|
||||
python examples/<feature>_example.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 8 — Draft GitHub Issue
|
||||
|
||||
The issue must be **self-contained**. Another agent must be able to implement by reading only the issue.
|
||||
|
||||
### Required sections
|
||||
|
||||
```markdown
|
||||
## Overview
|
||||
One paragraph: what, why, and the end goal.
|
||||
|
||||
## Background
|
||||
- Purpose and design goals
|
||||
- Why this is valuable
|
||||
- Current state / ecosystem
|
||||
|
||||
## Architecture Analysis
|
||||
### Current Implementation
|
||||
- Key files and their purposes
|
||||
- Integration points
|
||||
- Data flow
|
||||
|
||||
### Key File Locations
|
||||
| File | Purpose | Lines |
|
||||
|------|---------|-------|
|
||||
|
||||
## Gap Analysis Summary
|
||||
### Critical Gaps
|
||||
| Gap | Impact | Effort |
|
||||
|-----|--------|--------|
|
||||
|
||||
### Feature Gaps
|
||||
| Feature | Current Support | Gap |
|
||||
|---------|-----------------|-----|
|
||||
|
||||
## Proposed Implementation
|
||||
### Phase 1: Minimal
|
||||
Working code example.
|
||||
|
||||
### Phase 2: Production
|
||||
Working code example.
|
||||
|
||||
## Files to Create / Modify
|
||||
### New files
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
|
||||
### Modified files
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
|
||||
## Technical Considerations
|
||||
- Dependencies
|
||||
- Performance impact
|
||||
- Safety / approval
|
||||
- Multi-agent safety
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Verifiable checkbox list
|
||||
|
||||
## Implementation Notes
|
||||
### Key Files to Read First
|
||||
1. `path/to/file.py` (N lines) — purpose
|
||||
|
||||
### Critical Integration Points
|
||||
1. Where X connects to Y
|
||||
|
||||
### Testing Commands
|
||||
```bash
|
||||
# Copy-pastable commands
|
||||
```
|
||||
|
||||
## References
|
||||
- [Link](url)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 9 — Create GitHub Issue
|
||||
|
||||
### 9a. Create via `gh` CLI
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--repo MervinPraison/PraisonAIUI \
|
||||
--title "<Type>: <Descriptive Title>" \
|
||||
--body "<issue body>"
|
||||
```
|
||||
|
||||
**Title formats:**
|
||||
- `Feature: <What>` — new functionality
|
||||
- `Analysis: <Topic>` — analysis/research
|
||||
- `Integration: <External System>` — external integration
|
||||
- `Fix: <Problem>` — bug fix proposal
|
||||
|
||||
### 9b. Verify issue created
|
||||
|
||||
```bash
|
||||
gh issue view <number> --repo MervinPraison/PraisonAIUI | head -20
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist — Before Creating Issue
|
||||
|
||||
- [ ] Acceptance criteria defined and testable
|
||||
- [ ] All relevant PraisonAI files read (not skimmed)
|
||||
- [ ] External sources researched (if applicable)
|
||||
- [ ] Gap analysis completed with severity ratings
|
||||
- [ ] Critical review identifies risks and mitigations
|
||||
- [ ] Implementation plan is step-by-step with file list
|
||||
- [ ] Issue body has working code examples (not pseudocode)
|
||||
- [ ] All file paths are absolute and verified
|
||||
- [ ] CLI commands are copy-pastable
|
||||
- [ ] Acceptance criteria are verifiable (not vague)
|
||||
- [ ] References section includes all URLs
|
||||
- [ ] Issue is self-contained — no "see docs" without details
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference — Common Mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---------|-----|
|
||||
| Pseudocode in examples | Use real, runnable code with imports |
|
||||
| Vague file paths | Use absolute paths |
|
||||
| Skipping gap analysis | Every gap needs severity + impact |
|
||||
| Missing real agentic test | Include `agent.start()` test, not just construction |
|
||||
| No verification commands | Include copy-pastable pytest/python commands |
|
||||
| Claiming "done" without evidence | Every claim references specific files/symbols |
|
||||
| Implementing instead of analyzing | This workflow produces issues, not code |
|
||||
|
||||
---
|
||||
|
||||
## Hard Rules
|
||||
|
||||
1. **DO NOT implement** — this workflow produces analysis and issues only
|
||||
2. **DO NOT claim done** without evidence
|
||||
3. **Every claim must reference** specific files/symbols
|
||||
4. **Issue must be self-contained** — implementer needs no follow-up questions
|
||||
5. **Working code examples required** — no pseudocode
|
||||
@@ -1,104 +0,0 @@
|
||||
---
|
||||
description: analysis
|
||||
---
|
||||
|
||||
You are an expert AI engineer in the PraisonAI ecosystem.
|
||||
Your job: produce ONLY (1) analysis, (2) review, (3) gap analysis, (4) critical review, (5) plan, (6) proposal.
|
||||
Do NOT implement. Do NOT write code. Do NOT update docs. Do NOT run tests beyond discovery.
|
||||
Be precise, evidence-based, and agent-centric.
|
||||
|
||||
PRINCIPLES (apply in all analysis/proposals):
|
||||
- Agent-centric: Agents, workflows, sessions, tools, memory, multi-agent safety.
|
||||
- Protocol-driven core: praisonaiagents = lightweight, protocol-first (protocols/hooks/adapters only).
|
||||
- DRY: identify reuse; avoid duplication.
|
||||
- No perf impact: preserve import-time and hot-path; heavy deps optional + lazy.
|
||||
- Async-safe + multi-agent safe by default.
|
||||
- Clear paid upgrade path (support/cloud/services) without restricting core.
|
||||
- Easy for non-developers. "Few lines of code to do the task!"
|
||||
|
||||
CANONICAL PATHS:
|
||||
- UI Repo: /Users/praison/praisonaiui (praisonaiui)
|
||||
- SDK Core (reference): /Users/praison/praisonai-package/src/praisonai-agents (praisonaiagents)
|
||||
- Docs: /Users/praison/PraisonAIDocs (JS: docs/js, Rust: docs/rust)
|
||||
- Extension points: src/praisonaiui/*, docs/*, tests/*
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
MANDATORY PROCESS (NO IMPLEMENTATION)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
STEP 1 — Acceptance Criteria
|
||||
- Translate request into testable criteria: API, CLI, docs, test expectations, perf constraints.
|
||||
|
||||
STEP 2 — Repo Inventory (evidence-based)
|
||||
- Go through ALL relevant files, understand current logic end-to-end.
|
||||
- Inventory with evidence:
|
||||
- Public APIs: modules/classes/functions and exports
|
||||
- Protocols/adapters/hooks and extension points
|
||||
- CLI commands, options, help text
|
||||
- Integrations (db/observability/tools)
|
||||
- Tests (unit/integration), fixtures, CI config
|
||||
- Docs (Mintlify), examples, recipes
|
||||
- Provide: file paths + key symbols + grep counts + entry points.
|
||||
- Identify DRY opportunities.
|
||||
|
||||
STEP 3 — Detailed Analysis
|
||||
- Architecture and behavior: control flow, data flow, concurrency (sync/async), multi-agent interactions, dependency boundaries (core/wrapper/tools), failure modes.
|
||||
- Highlight invariants: protocol-driven core, lazy imports, optional deps.
|
||||
|
||||
STEP 4 — Detailed Review
|
||||
- Evaluate against principles: agent-centricity, API simplicity, DRY, perf, optional deps + lazy imports, async/multi-agent safety, test coverage, CLI parity, docs clarity.
|
||||
- Concrete evidence for each judgment.
|
||||
|
||||
STEP 5 — Gap Analysis
|
||||
- Compare acceptance criteria vs current state. Checklist:
|
||||
- UI Core, CLI, Docs, Tests, Exports, Perf, Multi-agent + async
|
||||
- Each gap: severity, impact, risk, recommended location (core/wrapper/tools).
|
||||
|
||||
STEP 6 — Critical Review
|
||||
- Risks, footguns, maintenance concerns:
|
||||
- API ambiguity, edge cases, backward compat
|
||||
- Coupling violations, perf regressions, concurrency hazards
|
||||
- Misuse risks, operational concerns
|
||||
- Mitigation strategies and "safe by default" recommendations.
|
||||
|
||||
STEP 7 — Plan
|
||||
- Step-by-step (do not implement): tests (TDD) → implementation → CLI → docs → verification
|
||||
- Exact files to change/create. Migration/compat plan. Rollback plan. Verification commands. Perf checks. Multi-agent + async test strategy.
|
||||
|
||||
REAL AGENTIC TEST definition (MUST include in every verification plan):
|
||||
- A "real agentic test" = agent ACTUALLY RUNS and calls the LLM:
|
||||
1. Create Agent with the feature being tested
|
||||
2. Call `agent.start("a real task prompt")` — NOT just constructing the object
|
||||
3. Agent MUST call LLM and produce text response
|
||||
4. Print full output so dev can see it worked end-to-end
|
||||
- Example:
|
||||
```python
|
||||
from praisonaiagents import Agent
|
||||
agent = Agent(name="test", instructions="You are a helpful assistant")
|
||||
result = agent.start("Say hello in one sentence")
|
||||
print(result)
|
||||
```
|
||||
- Assert-only object construction = SMOKE TEST, not real agentic test.
|
||||
- Both smoke AND real agentic tests required.
|
||||
|
||||
STEP 8 — Proposal
|
||||
- Minimal, agent-centric design and API/CLI surface:
|
||||
- protocols/hooks in core; implementations in wrapper/tools
|
||||
- Clear defaults and explicit overrides
|
||||
- Multi-agent resource isolation/sharing
|
||||
- Error model and observability hooks
|
||||
- Include: "Simple API" examples, CLI UX, docs outline, paid upgrade path.
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
REQUIRED OUTPUT (in order):
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
1) Acceptance Criteria
|
||||
2) Inventory (evidence: paths/symbols/exports/grep counts)
|
||||
3) Detailed Analysis (architecture + flows + invariants)
|
||||
4) Detailed Review (quality vs principles, evidence-based)
|
||||
5) Gap Analysis (checklist + severity/impact/placement)
|
||||
6) Critical Review (risks + mitigations)
|
||||
7) Plan (step-by-step + file list + verification strategy)
|
||||
8) Proposal (agent-centric design + API/CLI/docs outline)
|
||||
|
||||
Hard rules: DO NOT implement. DO NOT write code. DO NOT claim done. Every claim must reference specific files/symbols.
|
||||
@@ -1,228 +0,0 @@
|
||||
---
|
||||
description: Audit existing docs against live code, then create a comprehensive GitHub issue in PraisonAIDocs with correct, tested information ready for a writer/agent to implement immediately
|
||||
---
|
||||
|
||||
# Create PraisonAIDocs Issue Workflow
|
||||
|
||||
Audit code → Compare with existing docs → Draft correct content → Create issue.
|
||||
|
||||
> **When to use this:** A feature is already implemented in PraisonAI but the docs are missing, outdated, or wrong. You need to file a self-contained docs issue in `MervinPraison/PraisonAIDocs` that a writer or agent can act on without asking follow-up questions.
|
||||
> **When NOT to use this:** Use `@[/create-github-issue]` for new integrations that need external research. Use `@[/local-fix]` if you are writing the docs yourself.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Identify the Feature & Existing Docs
|
||||
|
||||
### 1a. Find the relevant doc file
|
||||
|
||||
```bash
|
||||
ls /Users/praison/PraisonAIDocs/docs/<section>/
|
||||
cat /Users/praison/PraisonAIDocs/docs/<section>/<feature>.mdx
|
||||
```
|
||||
|
||||
Key doc sections:
|
||||
- `docs/observability/` — tracing providers (Langfuse, LangSmith, etc.)
|
||||
- `docs/tools/` — tool integrations
|
||||
- `docs/features/` — agent features
|
||||
- `docs/cli/` — CLI commands
|
||||
- `docs/guides/` — how-to guides
|
||||
|
||||
### 1b. Read the existing doc fully
|
||||
|
||||
Note every claim that needs verification:
|
||||
- Install commands
|
||||
- Import statements
|
||||
- API method names and signatures
|
||||
- Environment variable names
|
||||
- CLI commands
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Audit the Live Code
|
||||
|
||||
### 2a. Find the source implementation
|
||||
|
||||
```bash
|
||||
# Search praisonaiagents core SDK
|
||||
grep -rn "<feature>" /Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/ 2>&1 | grep -v ".pyc"
|
||||
|
||||
# Search praisonai wrapper (CLI, integrations)
|
||||
grep -rn "<feature>" /Users/praison/praisonai-package/src/praisonai/praisonai/ 2>&1 | grep -v ".pyc"
|
||||
|
||||
# Search praisonai-tools
|
||||
grep -rn "<feature>" /Users/praison/PraisonAI-tools/ 2>&1 | grep -v ".pyc"
|
||||
```
|
||||
|
||||
### 2b. Read all relevant source files end-to-end
|
||||
|
||||
Read every file that implements the feature. For each file capture:
|
||||
- Actual class/function names and signatures
|
||||
- Required vs optional parameters
|
||||
- Environment variables read (exact names)
|
||||
- What gets called internally (trace the call chain)
|
||||
- Any version-specific behavior
|
||||
|
||||
Key files to always check:
|
||||
| File pattern | What to look for |
|
||||
|---|---|
|
||||
| `praisonaiagents/obs/__init__.py` | `_LazyObsModule`, factory methods, `auto()` |
|
||||
| `praisonai_tools/observability/providers/<name>_provider.py` | `init()`, `is_available()`, `shutdown()`, `flush()` |
|
||||
| `praisonai/observability/<name>.py` | CLI sink adapter, event handling |
|
||||
| `praisonai/cli/commands/<name>.py` | All CLI sub-commands and options |
|
||||
| `praisonai/__init__.py` | Global env var overrides that may interfere |
|
||||
|
||||
### 2c. Test the feature live
|
||||
|
||||
Run minimal test scripts to verify the actual behavior:
|
||||
|
||||
```bash
|
||||
# Test the import works
|
||||
python3 -c "from praisonaiagents.obs import obs; provider = obs.<name>(); print(type(provider).__name__, provider._initialized)"
|
||||
|
||||
# Test CLI commands
|
||||
praisonai <feature> --help
|
||||
praisonai <feature> <subcommand>
|
||||
|
||||
# Verify traces/output appear
|
||||
timeout 30 praisonai <feature> <subcommand> --limit 5
|
||||
```
|
||||
|
||||
### 2d. Build a "What's Wrong" table
|
||||
|
||||
For each doc claim that is incorrect, record:
|
||||
|
||||
| Current Doc (Wrong) | Correct |
|
||||
|---|---|
|
||||
| wrong install command | correct install |
|
||||
| wrong import | correct import |
|
||||
| non-existent method | actual method |
|
||||
| wrong env var name | actual env var |
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Draft the Issue
|
||||
|
||||
The issue body must be **self-contained and implementation-ready**. A writer should be able to update the doc by reading only the issue — no follow-up questions.
|
||||
|
||||
### Required sections:
|
||||
|
||||
```markdown
|
||||
## Overview
|
||||
One paragraph: what doc file needs updating, why it's wrong, and the end goal.
|
||||
State explicitly: "All code in this issue has been tested and verified working."
|
||||
|
||||
## What's Wrong With the Current Docs
|
||||
Table: Current (Wrong) | Correct
|
||||
Cover: install commands, imports, API methods, env vars, missing sections.
|
||||
|
||||
## Correct Architecture (How It Actually Works)
|
||||
Explain the actual internal call chain so the writer understands context.
|
||||
Include a text diagram if helpful.
|
||||
|
||||
## Required Install
|
||||
Exact pip commands, nothing more.
|
||||
|
||||
## Environment Variables
|
||||
Table: Variable | Required | Description
|
||||
Show bash export examples for both cloud and self-hosted.
|
||||
|
||||
## Python Usage
|
||||
|
||||
### Quickstart (Recommended)
|
||||
Full working code with correct imports, init, agent run, and flush.
|
||||
|
||||
### Auto-Detection
|
||||
Document obs.auto() or equivalent if applicable.
|
||||
|
||||
### Additional Patterns
|
||||
Any other valid usage patterns (explicit provider, multi-agent, etc.).
|
||||
|
||||
## CLI Usage (if applicable)
|
||||
All sub-commands with flags and examples.
|
||||
Include an end-to-end CLI session example.
|
||||
|
||||
## Configuration File (if applicable)
|
||||
Document any config files that are auto-created or auto-read.
|
||||
|
||||
## What Output Looks Like
|
||||
Show what traces/output actually look like after a successful run.
|
||||
|
||||
## Version Compatibility Notes
|
||||
Document any breaking changes between SDK versions that affect usage.
|
||||
|
||||
## Files to Update
|
||||
Table: File | Change
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Checkbox list — each item must be specific and verifiable
|
||||
|
||||
## References
|
||||
List all source files read (with absolute paths).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Create the Issue
|
||||
|
||||
### 4a. Write body to a temp file
|
||||
|
||||
```bash
|
||||
cat > /tmp/docs_issue_<feature>.md << 'EOF'
|
||||
<issue body>
|
||||
EOF
|
||||
```
|
||||
|
||||
### 4b. Create via `gh` CLI
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--repo MervinPraison/PraisonAIDocs \
|
||||
--title "Docs: <action verb> <feature> page — <one-line summary of what's wrong>" \
|
||||
--label "documentation" \
|
||||
--body-file /tmp/docs_issue_<feature>.md
|
||||
```
|
||||
|
||||
**Title format:** `Docs: Rewrite/Update/Add <Feature> page — <what's wrong or missing>`
|
||||
|
||||
Examples:
|
||||
- `Docs: Rewrite Langfuse integration page with correct Langfuse v4 API and CLI commands`
|
||||
- `Docs: Add obs.auto() documentation to observability overview`
|
||||
- `Docs: Fix LangSmith install command and update import paths`
|
||||
|
||||
### 4c. Verify
|
||||
|
||||
```bash
|
||||
gh issue view <number> --repo MervinPraison/PraisonAIDocs | head -30
|
||||
```
|
||||
|
||||
Confirm the URL: `https://github.com/MervinPraison/PraisonAIDocs/issues/<number>`
|
||||
|
||||
---
|
||||
|
||||
## Checklist — Before Creating the Issue
|
||||
|
||||
- [ ] Existing doc file read completely
|
||||
- [ ] All source files implementing the feature read end-to-end (not skimmed)
|
||||
- [ ] Feature tested live — not just code-read
|
||||
- [ ] "What's Wrong" table is complete and specific
|
||||
- [ ] All code examples in the issue are copy-pastable and tested
|
||||
- [ ] All env var names are verified against source (not guessed)
|
||||
- [ ] All CLI commands verified with `--help` and live run
|
||||
- [ ] Acceptance criteria are specific and verifiable (not vague)
|
||||
- [ ] References list includes all source file paths read
|
||||
- [ ] Issue is self-contained — writer needs no follow-up
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference — Common Mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---|---|
|
||||
| Documenting what the code *should* do, not what it *does* | Run it. Test it. Document the actual behavior. |
|
||||
| Copying import paths from docs being replaced | Always verify imports against source files |
|
||||
| Missing the "What's Wrong" table | This is the most important section — be explicit |
|
||||
| Vague acceptance criteria like "docs are updated" | Write specific, testable criteria: "install command is `pip install langfuse`" |
|
||||
| Not checking for interfering globals (e.g. `OTEL_SDK_DISABLED`) | Always grep `__init__.py` files for env var overrides |
|
||||
| Forgetting `provider.flush()` in examples | Async buffers need explicit flush before process exit |
|
||||
| Not testing with a real API key | Code-reading alone misses runtime errors |
|
||||
| Using `timeout` too short for first-run (downloads, auth) | Use `timeout 120` for agent runs, `timeout 30` for CLI |
|
||||
@@ -1,308 +0,0 @@
|
||||
---
|
||||
description: Research a topic in-depth, analyze both external and local codebases, and create a comprehensive GitHub issue — ready for another agent/developer to act on immediately
|
||||
---
|
||||
|
||||
# Create GitHub Issue Workflow
|
||||
|
||||
Research → Clone & Analyze → PraisonAI Analysis → Draft → Create Issue.
|
||||
|
||||
> **When to use this:** You need to create a detailed, implementation-ready GitHub issue for a new integration, feature, or benchmark. The issue must contain enough context that another agent or developer can implement it without asking further questions.
|
||||
> **When NOT to use this:** Use `@[/local-fix]` if you are implementing the change yourself, not just filing an issue.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Online Research
|
||||
|
||||
### 1a. Read official sources
|
||||
|
||||
Research the topic from all primary sources: official site, GitHub repo, documentation, blog posts.
|
||||
|
||||
```bash
|
||||
# Example searches (adapt to your topic)
|
||||
# - Official site / announcement pages
|
||||
# - GitHub README and docs
|
||||
# - Third-party write-ups (e.g. Snorkel AI, Epoch AI)
|
||||
# - Framework documentation (core concepts, agents, running)
|
||||
```
|
||||
|
||||
URLs to read for each source (use `read_url_content` tool):
|
||||
- Official announcement / news page
|
||||
- GitHub repository README (multiple chunks if large)
|
||||
- Framework/integration documentation pages
|
||||
- Any relevant blog posts or analysis
|
||||
|
||||
**Capture for the issue:**
|
||||
- What is it? Purpose and design goals
|
||||
- Key terminology and concepts (with definitions)
|
||||
- Architecture overview
|
||||
- Current leaderboard / ecosystem state
|
||||
- References list (all URLs)
|
||||
|
||||
### 1b. Read paginated content
|
||||
|
||||
For large pages, read additional chunks:
|
||||
|
||||
```
|
||||
view_content_chunk(document_id=<url>, position=2)
|
||||
view_content_chunk(document_id=<url>, position=3)
|
||||
view_content_chunk(document_id=<url>, position=4)
|
||||
```
|
||||
|
||||
Continue until all relevant sections are read (core concepts, agent types, running instructions, integration API).
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Clone & Analyze External Codebase
|
||||
|
||||
### 2a. Clone the repository
|
||||
|
||||
```bash
|
||||
git clone <repo-url> ~/<repo-name> --depth=1
|
||||
```
|
||||
|
||||
### 2b. Explore structure
|
||||
|
||||
```bash
|
||||
ls -la ~/<repo-name>/
|
||||
ls -la ~/<repo-name>/src/
|
||||
```
|
||||
|
||||
Key files to read (adapt paths to repo):
|
||||
- `AGENTS.md` / `CLAUDE.md` / `README.md` — architecture overview
|
||||
- Base class files (e.g. `base.py` for agents, environments)
|
||||
- Factory / registry files (how things are registered)
|
||||
- Model/config files (data structures agents must populate)
|
||||
- Enum files (valid names, types)
|
||||
- Example agent implementations (minimal + full-featured)
|
||||
- `pyproject.toml` — Python version, dependencies
|
||||
|
||||
**Capture for the issue:**
|
||||
- Repository structure diagram
|
||||
- Key file paths with line counts
|
||||
- Base class interface (all abstract methods with signatures)
|
||||
- How to register a new agent (enum + factory pattern)
|
||||
- Data models the agent must populate (`AgentContext`, etc.)
|
||||
- Example agent implementations (minimal and production)
|
||||
- CLI commands to run the integration
|
||||
- Environment variables required
|
||||
|
||||
### 2c. Read base classes end-to-end
|
||||
|
||||
Read every relevant base class completely. For agent integrations:
|
||||
|
||||
```
|
||||
read_file(base.py) # BaseAgent / BaseInstalledAgent
|
||||
read_file(factory.py) # AgentFactory registration
|
||||
read_file(models/agent/name.py) # AgentName enum
|
||||
read_file(models/agent/context.py) # AgentContext fields
|
||||
read_file(examples/agents/minimal_agent.py) # Minimal example
|
||||
read_file(agents/installed/reference_agent.py) # Full example
|
||||
```
|
||||
|
||||
### 2d. Read a reference implementation
|
||||
|
||||
Pick the most complete existing agent implementation (e.g. `codex.py`, `gemini_cli.py`) and read it fully. This reveals:
|
||||
- Install pattern (system packages → user packages)
|
||||
- Version detection (`get_version_command` / `parse_version`)
|
||||
- `@with_prompt_template` decorator usage
|
||||
- `populate_context_post_run` for token tracking
|
||||
- ATIF trajectory support (`SUPPORTS_ATIF`)
|
||||
- `CliFlag` / `EnvVar` declarative config
|
||||
- `exec_as_root` vs `exec_as_agent` usage
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Analyze PraisonAI Codebase
|
||||
|
||||
### 3a. Identify relevant components
|
||||
|
||||
```bash
|
||||
ls /Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/
|
||||
ls /Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/tools/
|
||||
ls /Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/agent/
|
||||
```
|
||||
|
||||
Key files to read for agent integration issues:
|
||||
|
||||
| File | What to look for |
|
||||
|------|-----------------|
|
||||
| `praisonaiagents/tools/shell_tools.py` | `execute_command`, approval decorators |
|
||||
| `praisonaiagents/agent/agent.py` | `Agent.start()`, `Agent.chat()`, token tracking |
|
||||
| `praisonaiagents/approval/` | `@require_approval`, auto-approval backend |
|
||||
| `praisonaiagents/eval/` | Evaluation framework hooks |
|
||||
| `praisonaiagents/agents/agents.py` | `AgentTeam` multi-agent |
|
||||
| `pyproject.toml` | Current version, optional dependencies |
|
||||
|
||||
### 3b. Map integration points
|
||||
|
||||
For each PraisonAI component, document:
|
||||
- What it does
|
||||
- How it maps to the external system's interface
|
||||
- What needs bridging (e.g. wrapping `environment.exec()` as a tool)
|
||||
- Known gotchas (e.g. `@require_approval` must be bypassed in containers)
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Draft the Issue
|
||||
|
||||
The issue body must be self-contained. Another agent must be able to implement the feature by reading only the issue — no follow-up questions.
|
||||
|
||||
### Required sections:
|
||||
|
||||
```markdown
|
||||
## Overview
|
||||
One paragraph: what, why, and the end goal.
|
||||
|
||||
## Background: What is <X>?
|
||||
- Purpose and design goals
|
||||
- Key statistics (task count, solve rates, etc.)
|
||||
- Why <X> + PraisonAI is valuable
|
||||
- Current ecosystem / leaderboard state
|
||||
|
||||
## <X> Architecture (Codebase Analysis)
|
||||
> Repo analyzed locally: `~/<repo-name>` (cloned at `~/<repo-name>`)
|
||||
|
||||
### Core Concepts
|
||||
Table: Concept | Description
|
||||
|
||||
### Two (or N) Integration Types
|
||||
Code examples for each type with full signatures.
|
||||
|
||||
### Key File Locations in <X> Codebase
|
||||
Directory tree with annotations for each important file.
|
||||
|
||||
### Data Models
|
||||
Full class definitions the agent must populate.
|
||||
|
||||
### How to Run (CLI)
|
||||
All relevant CLI commands with flags and examples.
|
||||
|
||||
## PraisonAI Architecture (Relevant to This Integration)
|
||||
Table: Component | Location | Relevance
|
||||
|
||||
### PraisonAI Execution Model
|
||||
How PraisonAI currently handles the relevant operations, and what must be adapted.
|
||||
|
||||
## Proposed Implementation Plan
|
||||
### Approach: <Recommended> (with justification)
|
||||
|
||||
### Phase 1: Minimal Proof-of-Concept
|
||||
Full working code example.
|
||||
|
||||
### Phase 2: Production Implementation
|
||||
Full working code example.
|
||||
|
||||
### Phase N: Advanced Features
|
||||
(ATIF, multi-agent, etc.)
|
||||
|
||||
## Files to Create / Modify
|
||||
### New files (praisonai-package)
|
||||
Table: File | Purpose
|
||||
|
||||
### Modifications to <External Repo> (PR upstream)
|
||||
Table: File | Change
|
||||
|
||||
## Technical Considerations
|
||||
Subsections for:
|
||||
- Container/environment dependencies
|
||||
- API key forwarding
|
||||
- Safety/approval bypass
|
||||
- Token tracking
|
||||
- Parallel execution safety
|
||||
|
||||
## Job / Config Example
|
||||
Working YAML config + CLI invocation.
|
||||
|
||||
## Use Cases Unlocked
|
||||
Table: Use Case | How
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Checkbox list of verifiable outcomes
|
||||
|
||||
## Implementation Notes for the Assigned Agent/Developer
|
||||
### Key <X> Files to Read First
|
||||
Numbered list with file paths and line counts.
|
||||
|
||||
### Key PraisonAI Files to Read
|
||||
Numbered list with file paths.
|
||||
|
||||
### Critical Integration Points
|
||||
Numbered list of the exact code-level bridges needed.
|
||||
|
||||
### Architecture Decision
|
||||
Why the chosen approach (installed vs external, etc.) with trade-offs.
|
||||
|
||||
### Installation & Testing Commands
|
||||
Copy-pastable commands to install, verify, and run.
|
||||
|
||||
### Upstream PR
|
||||
What to submit upstream and where.
|
||||
|
||||
## References
|
||||
Bullet list of all URLs used.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Create the Issue
|
||||
|
||||
### 5a. Create via `gh` CLI
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--repo <org>/<repo> \
|
||||
--title "Feature: <Descriptive Title>" \
|
||||
--label "enhancement" \
|
||||
--body "<issue body>"
|
||||
```
|
||||
|
||||
**Title format:** `Feature: <What> with <Integration> (<Framework/Version>)`
|
||||
|
||||
Example:
|
||||
```bash
|
||||
gh issue create \
|
||||
--repo MervinPraison/PraisonAI \
|
||||
--title "Feature: Integrate PraisonAI Agents with Terminal-Bench 2.0 (Harbor Framework)" \
|
||||
--label "enhancement" \
|
||||
--body "..."
|
||||
```
|
||||
|
||||
### 5b. Verify the issue was created
|
||||
|
||||
```bash
|
||||
gh issue view <issue-number> --repo <org>/<repo> | head -20
|
||||
```
|
||||
|
||||
The output URL confirms success: `https://github.com/<org>/<repo>/issues/<number>`
|
||||
|
||||
---
|
||||
|
||||
## Checklist — Before Creating the Issue
|
||||
|
||||
- [ ] All primary documentation URLs read (including paginated chunks)
|
||||
- [ ] External repo cloned locally and analyzed
|
||||
- [ ] Base classes read end-to-end (not just skimmed)
|
||||
- [ ] At least one reference implementation read fully
|
||||
- [ ] PraisonAI codebase analyzed for integration points
|
||||
- [ ] Issue body has working code examples (not pseudocode)
|
||||
- [ ] All file paths are absolute and verified to exist
|
||||
- [ ] CLI commands are copy-pastable and complete
|
||||
- [ ] Acceptance criteria are verifiable (not vague)
|
||||
- [ ] References section includes all URLs used
|
||||
- [ ] Issue is self-contained — no "see docs for details" without the details
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference — Common Mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---------|-----|
|
||||
| Pseudocode in examples | Use real, runnable code with imports |
|
||||
| Vague file paths like `agents/` | Use absolute paths like `~/harbor/src/harbor/agents/base.py` |
|
||||
| Missing `--depth=1` on clone | Large repos take forever; always use shallow clone |
|
||||
| Only reading chunk 0 of a URL | Read chunks 1–4+ for paginated content |
|
||||
| Skipping the factory/registry file | This is where registration happens; always read it |
|
||||
| Not reading a reference agent | Pattern is not obvious from base class alone |
|
||||
| Forgetting API key forwarding section | Always document how secrets are passed to containers |
|
||||
| Skipping `populate_context_post_run` | Harbor uses this for token tracking and leaderboard data |
|
||||
| Missing upstream PR instructions | Specify exact files to modify upstream for first-class support |
|
||||
@@ -1,190 +0,0 @@
|
||||
---
|
||||
description: create and publish a post on mer.vin using praisonaiwp
|
||||
---
|
||||
|
||||
## Config
|
||||
|
||||
- Server: `default` → `https://mer.vin`
|
||||
- Config: `~/.praisonaiwp/config.yaml`
|
||||
- Category for PraisonAI features: `PraisonAI`
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Compose the content
|
||||
|
||||
Structure every post as:
|
||||
1. **Intro paragraph** — one sentence, what the feature solves
|
||||
2. **Mermaid diagram** — architecture/flow (see block format below)
|
||||
3. **Sections** — H2 headings, tables > prose, code blocks for usage
|
||||
4. **Performance/summary** — table with concrete numbers
|
||||
|
||||
Keep it technical. Lead with diagrams and tables, not paragraphs.
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Mermaid block format (merpress)
|
||||
|
||||
> **Creating merpress:** Install the [Merpress – Mermaid for WordPress](https://wordpress.org/plugins/merpress/) plugin via `wp plugin install merpress --activate --allow-root` on the server. It adds the `wp:merpress/mermaidjs` block used below.
|
||||
|
||||
All posts use the native `wp:merpress/mermaidjs` block. Use this exact format:
|
||||
|
||||
```
|
||||
<!-- wp:merpress/mermaidjs {"align":"full"} -->
|
||||
<div class="wp-block-merpress-mermaidjs diagram-source-mermaid alignfull"><pre class="mermaid">%%{init: {"theme": "base", "themeVariables": {"background": "transparent", "lineColor": "#000000"}}}%%
|
||||
graph TD
|
||||
A[Input] --> B[Agent]
|
||||
B --> C[Tool]
|
||||
C --> D[Output]
|
||||
|
||||
classDef hook fill:#189AB4,color:#fff
|
||||
classDef agent fill:#8B0000,color:#fff
|
||||
classDef decision fill:#444,color:#fff
|
||||
|
||||
class B agent
|
||||
class C hook
|
||||
</pre></div>
|
||||
<!-- /wp:merpress/mermaidjs -->
|
||||
```
|
||||
|
||||
**Do NOT use:** `[mermaid]...[/mermaid]` shortcode — that is the wrong format.
|
||||
|
||||
Color scheme:
|
||||
- `#8B0000` (dark red) — agents, inputs, outputs
|
||||
- `#189AB4` (teal) — tools, hooks
|
||||
- `#444` — decisions/conditionals
|
||||
|
||||
---
|
||||
|
||||
## Step 2a — SVG/image upload via SSH
|
||||
|
||||
`praisonaiwp media upload` correctly SFTPs the file to `/tmp/` on the server, but
|
||||
`_execute_wp()` in `~/praisonaiwp-cli/praisonaiwp/core/wp_client.py` never appends
|
||||
`--allow-root`. Use direct SSH instead.
|
||||
|
||||
**SVG upload (Safe SVG plugin active on mer.vin):**
|
||||
|
||||
```bash
|
||||
# 1. SCP SVG to server
|
||||
scp -i ~/.ssh/id_ed25519 /path/to/diagram.svg <SSH_USER>@<SERVER_IP>:/tmp/
|
||||
|
||||
# 2. Import via WP-CLI — must pass --user=<admin> so Safe SVG capability check passes
|
||||
ssh -i ~/.ssh/id_ed25519 <SSH_USER>@<SERVER_IP> \
|
||||
"cd <WP_ROOT> && \
|
||||
wp media import /tmp/diagram.svg --post_id=<POST_ID> \
|
||||
--title='Title' --alt='Alt' --user=praison --allow-root --porcelain"
|
||||
# → returns media ID
|
||||
|
||||
# 3. Get the URL
|
||||
ssh -i ~/.ssh/id_ed25519 <SSH_USER>@<SERVER_IP> \
|
||||
"cd <WP_ROOT> && \
|
||||
wp post get <MEDIA_ID> --field=guid --allow-root"
|
||||
```
|
||||
|
||||
> **Key:** `--user=praison` is required — Safe SVG checks upload capability against the
|
||||
> current WP user. Without it, even with the plugin active, SVG imports are blocked.
|
||||
|
||||
**PNG fallback (if Safe SVG not available):**
|
||||
|
||||
```bash
|
||||
rsvg-convert -w 1360 /path/to/diagram.svg -o /tmp/diagram_2x.png
|
||||
# Then follow the same SSH steps above using the .png file (no --user needed)
|
||||
```
|
||||
|
||||
Use this Gutenberg image block in the post content:
|
||||
|
||||
```
|
||||
<!-- wp:image {"id":<MEDIA_ID>,"sizeSlug":"full","linkDestination":"none"} -->
|
||||
<figure class="wp-block-image size-full"><img src="<IMAGE_URL>" alt="Alt text" class="wp-image-<MEDIA_ID>"/></figure>
|
||||
<!-- /wp:image -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3 — Create the post
|
||||
|
||||
```bash
|
||||
praisonaiwp create "Post Title" \
|
||||
--status publish \
|
||||
--content '<FULL GUTENBERG CONTENT>'
|
||||
```
|
||||
|
||||
Note the returned **Post ID** from the output.
|
||||
|
||||
---
|
||||
|
||||
## Step 4 — Set category
|
||||
|
||||
```bash
|
||||
praisonaiwp update <POST_ID> --category "PraisonAI"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — Validate mermaid format
|
||||
|
||||
```bash
|
||||
ssh -i ~/.ssh/id_ed25519 <SSH_USER>@<SERVER_IP> \
|
||||
"cd <WP_ROOT> && \
|
||||
wp post get <POST_ID> --field=post_content --allow-root | grep -i mermaid"
|
||||
```
|
||||
|
||||
Expected output must contain `wp:merpress/mermaidjs`, not `[mermaid]`.
|
||||
|
||||
---
|
||||
|
||||
## Key Gutenberg blocks reference
|
||||
|
||||
```
|
||||
<!-- wp:paragraph --><p>text</p><!-- /wp:paragraph -->
|
||||
|
||||
<!-- wp:heading --><h2 class="wp-block-heading">Title</h2><!-- /wp:heading -->
|
||||
|
||||
<!-- wp:heading {"level":3} --><h3 class="wp-block-heading">Sub</h3><!-- /wp:heading -->
|
||||
|
||||
<!-- wp:code --><pre class="wp-block-code"><code>code here</code></pre><!-- /wp:code -->
|
||||
|
||||
<!-- wp:table -->
|
||||
<figure class="wp-block-table"><table>
|
||||
<thead><tr><th>Col</th></tr></thead>
|
||||
<tbody><tr><td>Val</td></tr></tbody>
|
||||
</table></figure>
|
||||
<!-- /wp:table -->
|
||||
|
||||
<!-- wp:list --><ul class="wp-block-list"><li>item</li></ul><!-- /wp:list -->
|
||||
|
||||
<!-- wp:separator --><hr class="wp-block-separator has-alpha-channel-opacity"/><!-- /wp:separator -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Full example command
|
||||
|
||||
```bash
|
||||
praisonaiwp create "Feature Name: What It Does" \
|
||||
--status publish \
|
||||
--content '<!-- wp:paragraph -->
|
||||
<p>One sentence intro.</p>
|
||||
<!-- /wp:paragraph -->
|
||||
|
||||
<!-- wp:heading -->
|
||||
<h2 class="wp-block-heading">Architecture</h2>
|
||||
<!-- /wp:heading -->
|
||||
|
||||
<!-- wp:merpress/mermaidjs {"align":"full"} -->
|
||||
<div class="wp-block-merpress-mermaidjs diagram-source-mermaid alignfull"><pre class="mermaid">%%{init: {"theme": "base", "themeVariables": {"background": "transparent", "lineColor": "#000000"}}}%%
|
||||
graph TD
|
||||
A[Start] --> B[Agent]
|
||||
class B agent
|
||||
classDef agent fill:#8B0000,color:#fff
|
||||
</pre></div>
|
||||
<!-- /wp:merpress/mermaidjs -->
|
||||
|
||||
<!-- wp:code -->
|
||||
<pre class="wp-block-code"><code>from praisonaiagents import Agent
|
||||
agent = Agent(name="example")
|
||||
result = agent.start("task")</code></pre>
|
||||
<!-- /wp:code -->'
|
||||
|
||||
# Then set category:
|
||||
praisonaiwp update <ID> --category "PraisonAI"
|
||||
```
|
||||
@@ -1,670 +0,0 @@
|
||||
---
|
||||
description: End-to-end workflow — deep analysis → GitHub issue → wait for implementing agents → create PR if missing → wait for reviewing agents → review PR locally → feedback to @claude → merge to main when robust per AGENTS.md
|
||||
---
|
||||
|
||||
# End-to-End: Analysis → Issue → PR → Review → Merge
|
||||
|
||||
Deep Analysis → Gap Analysis → Critical Review → Plan → Create Issue → **Wait for implementing agents** → **Create PR if missing** → **Wait for reviewers** → **Validate PR locally** → **Feedback to @claude** → **Re-review after fixes** → **Merge to main if robust**.
|
||||
|
||||
> **When to use this:** You want a fully hands-off delivery loop. You describe a feature/integration/fix; this workflow produces the issue, monitors implementation by other agents (Claude, Copilot, CodeRabbit), validates their PR locally against `AGENTS.md` principles, loops feedback until the PR is robust, and merges to `main`.
|
||||
> **When NOT to use this:** Use `/analysis-github-issue-create` if you only want the issue (no PR/merge). Use `/local-fix` if you are the implementer.
|
||||
|
||||
---
|
||||
|
||||
## PRINCIPLES (apply throughout)
|
||||
|
||||
- **Agent-centric**: Agents, workflows, sessions, tools, memory, multi-agent safety.
|
||||
- **Protocol-driven core**: `praisonaiagents` = lightweight, protocol-first (protocols/hooks/adapters only).
|
||||
- **DRY**: identify reuse; avoid duplication.
|
||||
- **No perf impact**: preserve import-time and hot-path; heavy deps optional + lazy.
|
||||
- **Async-safe + multi-agent safe** by default.
|
||||
- **Easy for non-developers**: "Few lines of code to do the task!"
|
||||
- **No competitor names in public surfaces**: Never mention competitor product, company, or project names in GitHub issues, PRs, commit messages, release notes, docs, or any other public-facing content. Refer to capabilities generically (e.g., "self-improving agent pattern", "external agent framework").
|
||||
- **Test before merge**: never merge unvalidated PRs. Always clone the branch locally and run the tests.
|
||||
- **Minimal code change**: prefer upstream one-line fixes over downstream workarounds.
|
||||
|
||||
---
|
||||
|
||||
## CANONICAL PATHS
|
||||
|
||||
```
|
||||
Core SDK: /Users/praison/praisonai-package/src/praisonai-agents (praisonaiagents)
|
||||
Wrapper: /Users/praison/praisonai-package/src/praisonai (praisonai)
|
||||
Tools: /Users/praison/PraisonAI-tools
|
||||
Docs: /Users/praison/PraisonAIDocs
|
||||
TypeScript: /Users/praison/praisonai-package/src/praisonai-ts
|
||||
AGENTS.md: /Users/praison/praisonai-package/src/praisonai-agents/AGENTS.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# PART A — ANALYSIS & ISSUE (Phases 1–9)
|
||||
|
||||
These phases are identical to `/analysis-github-issue-create`. Execute them in order. **Do not implement any code** in these phases — they produce analysis and an issue only.
|
||||
|
||||
## Phase 1 — Acceptance Criteria
|
||||
|
||||
Translate the request into testable criteria:
|
||||
- API expectations (classes, methods, signatures)
|
||||
- CLI expectations (commands, flags, help text)
|
||||
- Documentation expectations (pages, examples)
|
||||
- Test expectations (unit, integration, smoke, real agentic)
|
||||
- Performance constraints (import time, hot-path)
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — External Research (if applicable)
|
||||
|
||||
### 2a. Read official sources
|
||||
|
||||
If analyzing an external integration, research from primary sources:
|
||||
|
||||
```bash
|
||||
# Use read_url_content tool for:
|
||||
# - Official site / announcement pages
|
||||
# - GitHub README and docs
|
||||
# - Framework documentation
|
||||
# - Third-party write-ups
|
||||
```
|
||||
|
||||
**Capture:**
|
||||
- What is it? Purpose and design goals
|
||||
- Key terminology and concepts
|
||||
- Architecture overview
|
||||
- Current ecosystem state
|
||||
- References list (all URLs)
|
||||
|
||||
### 2b. Clone & analyze external codebase (if applicable)
|
||||
|
||||
```bash
|
||||
git clone <repo-url> ~/<repo-name> --depth=1
|
||||
ls -la ~/<repo-name>/
|
||||
```
|
||||
|
||||
Key files to read:
|
||||
- `AGENTS.md` / `README.md` — architecture overview
|
||||
- Base class files (abstract methods, signatures)
|
||||
- Factory / registry files (registration pattern)
|
||||
- Model/config files (data structures)
|
||||
- Example implementations (minimal + full-featured)
|
||||
- `pyproject.toml` / `package.json` — dependencies
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — PraisonAI Codebase Inventory
|
||||
|
||||
### 3a. Inventory with evidence
|
||||
|
||||
Go through ALL relevant files, understand current logic end-to-end.
|
||||
|
||||
```bash
|
||||
# Core SDK
|
||||
ls /Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/
|
||||
grep -r "class.*Protocol" praisonaiagents/ --include="*.py" | wc -l
|
||||
|
||||
# Wrapper
|
||||
ls /Users/praison/praisonai-package/src/praisonai/praisonai/
|
||||
ls /Users/praison/praisonai-package/src/praisonai/praisonai/cli/commands/
|
||||
|
||||
# TypeScript
|
||||
ls /Users/praison/praisonai-package/src/praisonai-ts/src/
|
||||
```
|
||||
|
||||
**Document:**
|
||||
- Public APIs: modules/classes/functions and exports
|
||||
- Protocols/adapters/hooks and extension points
|
||||
- CLI commands, options, help text
|
||||
- Integrations (db/observability/tools)
|
||||
- Tests (unit/integration), fixtures, CI config
|
||||
- Docs (Mintlify), examples, recipes
|
||||
|
||||
Provide: **file paths + key symbols + grep counts + entry points**.
|
||||
|
||||
### 3b. Identify DRY opportunities
|
||||
|
||||
- Existing abstractions that can be reused
|
||||
- Duplicated code that should be consolidated
|
||||
- Existing protocols before creating new ones
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Detailed Analysis
|
||||
|
||||
### 4a. Architecture and behavior
|
||||
|
||||
- Control flow and data flow
|
||||
- Concurrency model (sync/async)
|
||||
- Multi-agent interactions
|
||||
- Dependency boundaries (core/wrapper/tools)
|
||||
- Failure modes and error handling
|
||||
|
||||
### 4b. Invariants check
|
||||
|
||||
Verify these are preserved:
|
||||
- [ ] Protocol-driven core (no heavy impls in `praisonaiagents`)
|
||||
- [ ] Lazy imports (optional deps never at module level)
|
||||
- [ ] Backward compatible (public API changes need deprecation)
|
||||
- [ ] Safe defaults (new features opt-in)
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Gap Analysis
|
||||
|
||||
Compare acceptance criteria vs current state.
|
||||
|
||||
### Checklist
|
||||
|
||||
| Area | Current State | Gap | Severity | Impact | Placement |
|
||||
|------|---------------|-----|----------|--------|-----------|
|
||||
| Core SDK | | | | | |
|
||||
| Wrapper | | | | | |
|
||||
| Tools/plugins | | | | | |
|
||||
| CLI | | | | | |
|
||||
| Docs | | | | | |
|
||||
| Tests | | | | | |
|
||||
| Exports | | | | | |
|
||||
| Perf | | | | | |
|
||||
| Multi-agent + async | | | | | |
|
||||
|
||||
### Gap severity levels
|
||||
- **Critical**: Blocks functionality
|
||||
- **High**: Significant limitation
|
||||
- **Medium**: Missing feature
|
||||
- **Low**: Nice-to-have
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — Critical Review
|
||||
|
||||
### 6a. Risks and footguns
|
||||
|
||||
- API ambiguity or edge cases
|
||||
- Backward compatibility concerns
|
||||
- Coupling violations
|
||||
- Performance regressions
|
||||
- Concurrency hazards
|
||||
- Misuse risks
|
||||
- Operational concerns
|
||||
|
||||
### 6b. Mitigation strategies
|
||||
|
||||
For each risk, document:
|
||||
- "Safe by default" recommendation
|
||||
- Explicit opt-in for dangerous behavior
|
||||
- Documentation warnings
|
||||
|
||||
---
|
||||
|
||||
## Phase 7 — Implementation Plan
|
||||
|
||||
Step-by-step plan (DO NOT implement):
|
||||
|
||||
### 7a. Test-first (TDD)
|
||||
|
||||
1. Unit tests for new functionality
|
||||
2. Integration tests for cross-component behavior
|
||||
3. Smoke tests for quick validation
|
||||
4. **Real agentic tests** (REQUIRED):
|
||||
```python
|
||||
from praisonaiagents import Agent
|
||||
agent = Agent(name="test", instructions="You are helpful")
|
||||
result = agent.start("Say hello in one sentence")
|
||||
print(result) # Must call LLM and produce response
|
||||
```
|
||||
|
||||
### 7b. Implementation order
|
||||
|
||||
1. Tests (TDD)
|
||||
2. Core implementation
|
||||
3. CLI integration
|
||||
4. Documentation
|
||||
5. Verification
|
||||
|
||||
### 7c. Files to change/create
|
||||
|
||||
| File | Action | Purpose |
|
||||
|------|--------|---------|
|
||||
| | | |
|
||||
|
||||
### 7d. Verification commands
|
||||
|
||||
```bash
|
||||
# Unit tests
|
||||
pytest tests/unit/test_<feature>.py -v
|
||||
|
||||
# Integration tests
|
||||
pytest tests/integration/test_<feature>.py -v
|
||||
|
||||
# Smoke test
|
||||
python -c "from praisonaiagents import <Feature>; print('OK')"
|
||||
|
||||
# Real agentic test
|
||||
python examples/<feature>_example.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 8 — Draft GitHub Issue
|
||||
|
||||
The issue must be **self-contained**. Another agent must be able to implement by reading only the issue.
|
||||
|
||||
### Required sections
|
||||
|
||||
```markdown
|
||||
## Overview
|
||||
One paragraph: what, why, and the end goal.
|
||||
|
||||
## Background
|
||||
- Purpose and design goals
|
||||
- Why this is valuable
|
||||
- Current state / ecosystem
|
||||
|
||||
## Architecture Analysis
|
||||
### Current Implementation
|
||||
- Key files and their purposes
|
||||
- Integration points
|
||||
- Data flow
|
||||
|
||||
### Key File Locations
|
||||
| File | Purpose | Lines |
|
||||
|------|---------|-------|
|
||||
|
||||
## Gap Analysis Summary
|
||||
### Critical Gaps
|
||||
| Gap | Impact | Effort |
|
||||
|-----|--------|--------|
|
||||
|
||||
### Feature Gaps
|
||||
| Feature | Current Support | Gap |
|
||||
|---------|-----------------|-----|
|
||||
|
||||
## Proposed Implementation
|
||||
### Phase 1: Minimal
|
||||
Working code example.
|
||||
|
||||
### Phase 2: Production
|
||||
Working code example.
|
||||
|
||||
## Files to Create / Modify
|
||||
### New files
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
|
||||
### Modified files
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
|
||||
## Technical Considerations
|
||||
- Dependencies
|
||||
- Performance impact
|
||||
- Safety / approval
|
||||
- Multi-agent safety
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Verifiable checkbox list
|
||||
|
||||
## Implementation Notes
|
||||
### Key Files to Read First
|
||||
1. `path/to/file.py` (N lines) — purpose
|
||||
|
||||
### Critical Integration Points
|
||||
1. Where X connects to Y
|
||||
|
||||
### Testing Commands
|
||||
```bash
|
||||
# Copy-pastable commands
|
||||
```
|
||||
|
||||
## References
|
||||
- [Link](url)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 9 — Create GitHub Issue
|
||||
|
||||
### 9a. Create via `gh` CLI
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--repo MervinPraison/PraisonAI \
|
||||
--title "<Type>: <Descriptive Title>" \
|
||||
--body-file /tmp/issue-body.md
|
||||
```
|
||||
|
||||
**Title formats:**
|
||||
- `Feature: <What>` — new functionality
|
||||
- `Integration: <External System>` — external integration
|
||||
- `Fix: <Problem>` — bug fix proposal
|
||||
|
||||
### 9b. Record the issue number
|
||||
|
||||
```bash
|
||||
ISSUE_NUM=$(gh issue view <number> --repo MervinPraison/PraisonAI --json number --jq '.number')
|
||||
echo "Tracking issue #$ISSUE_NUM"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# PART B — IMPLEMENTATION MONITORING (Phases 10–15)
|
||||
|
||||
After the issue is filed, other agents (`@claude`, GitHub Copilot agent, CodeRabbit) pick it up automatically. This part watches, shepherds, validates, and merges.
|
||||
|
||||
## Phase 10 — Wait ~10 min for implementing agents
|
||||
|
||||
After `gh issue create`, Claude and Copilot typically start work within seconds and finish a first pass in 5–15 minutes.
|
||||
|
||||
```bash
|
||||
echo "Waiting 10 minutes for implementing agents..."
|
||||
echo "Start: $(date)"
|
||||
sleep 600
|
||||
echo "End: $(date)"
|
||||
```
|
||||
|
||||
### Then check: did they open a PR?
|
||||
|
||||
```bash
|
||||
REPO=MervinPraison/PraisonAI
|
||||
ISSUE_NUM=<number>
|
||||
|
||||
# Check for PRs that reference the issue
|
||||
gh pr list --repo $REPO --state open --search "fixes #$ISSUE_NUM OR closes #$ISSUE_NUM" --json number,title,headRefName
|
||||
|
||||
# Also check for branches matching claude/issue-<N>-* naming convention
|
||||
gh api repos/$REPO/branches --paginate --jq ".[] | select(.name | startswith(\"claude/issue-$ISSUE_NUM\")) | .name"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 11 — Create PR if none exists
|
||||
|
||||
If Claude pushed a branch but did not open a PR, open one yourself.
|
||||
|
||||
```bash
|
||||
REPO=MervinPraison/PraisonAI
|
||||
ISSUE_NUM=<number>
|
||||
BRANCH=$(gh api repos/$REPO/branches --paginate --jq ".[] | select(.name | startswith(\"claude/issue-$ISSUE_NUM\")) | .name" | head -1)
|
||||
|
||||
if [ -n "$BRANCH" ]; then
|
||||
TITLE=$(gh api repos/$REPO/commits/$BRANCH --jq '.commit.message' | head -1)
|
||||
gh pr create --repo $REPO --head "$BRANCH" --base main \
|
||||
--title "$TITLE" \
|
||||
--body "Automated PR from Claude's work on issue #$ISSUE_NUM.
|
||||
|
||||
Branch: \`$BRANCH\`
|
||||
|
||||
Closes #$ISSUE_NUM"
|
||||
fi
|
||||
```
|
||||
|
||||
### If no branch exists after 10 minutes
|
||||
|
||||
Re-trigger Claude by commenting on the issue, then wait another 10 minutes and re-check:
|
||||
|
||||
```bash
|
||||
gh issue comment $ISSUE_NUM --repo $REPO \
|
||||
--body "@claude please pick up this issue — full analysis and plan are in the issue body."
|
||||
sleep 600
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 12 — Wait ~10 min for reviewing agents
|
||||
|
||||
Once a PR exists, `CodeRabbit`, `Copilot`, and CI pipelines run. Give them time to complete.
|
||||
|
||||
```bash
|
||||
echo "Waiting 10 minutes for PR reviewers and CI..."
|
||||
sleep 600
|
||||
```
|
||||
|
||||
### Collect status
|
||||
|
||||
```bash
|
||||
PR=<pr-number>
|
||||
gh pr view $PR --repo $REPO --json state,mergeable,mergeStateStatus,updatedAt,commits,files \
|
||||
| python -c "
|
||||
import json,sys
|
||||
d=json.load(sys.stdin)
|
||||
print(f\" State: {d['state']} Mergeable: {d['mergeable']} MergeState: {d['mergeStateStatus']}\")
|
||||
print(f\" Commits: {len(d['commits'])}\")
|
||||
for f in d['files']:
|
||||
print(f\" {f['path']}: +{f['additions']} -{f['deletions']}\")
|
||||
"
|
||||
|
||||
# CI & review checks
|
||||
gh pr view $PR --repo $REPO --json statusCheckRollup > /tmp/pr-checks.json
|
||||
python -c "
|
||||
import json
|
||||
for c in json.load(open('/tmp/pr-checks.json'))['statusCheckRollup']:
|
||||
s = c.get('conclusion') or c.get('status','?')
|
||||
name = c.get('name') or c.get('context','?')
|
||||
if s and s not in ('SKIPPED',):
|
||||
print(f' {name}: {s}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 13 — Validate the PR locally
|
||||
|
||||
**Never merge an unvalidated PR.** Always clone the branch and run tests.
|
||||
|
||||
```bash
|
||||
REPO_URL=https://github.com/MervinPraison/PraisonAI.git
|
||||
BRANCH=<branch-name>
|
||||
WORKDIR=/tmp/pr-validate
|
||||
|
||||
rm -rf $WORKDIR
|
||||
git clone --depth 1 --branch "$BRANCH" $REPO_URL $WORKDIR
|
||||
cd $WORKDIR
|
||||
|
||||
# Files touched by the PR
|
||||
gh pr view $PR --repo $REPO --json files --jq '.files[].path'
|
||||
|
||||
# Run the tests for changed files — ALWAYS use timeout (user global rule)
|
||||
timeout 120 python -m pytest <test-paths> -v --tb=short
|
||||
|
||||
# Critical invariant checks (adapt per feature):
|
||||
# 1) Lazy-import: heavy deps never imported at module level
|
||||
timeout 30 python - <<'PY'
|
||||
import sys
|
||||
from praisonai.observability import <NewThing> # example
|
||||
assert 'heavy_dep' not in sys.modules, "eager import — violates AGENTS.md §4.2"
|
||||
print("OK: lazy import preserved")
|
||||
PY
|
||||
|
||||
# 2) Cold-import benchmark (no regression)
|
||||
timeout 30 python -c "import time; t=time.time(); import praisonaiagents; print(f'{(time.time()-t)*1000:.1f} ms')"
|
||||
```
|
||||
|
||||
### Mergeability gate
|
||||
|
||||
A PR is **ready to merge only if ALL of these are true**:
|
||||
|
||||
- [ ] `gh pr view` reports `mergeable=MERGEABLE` and `mergeStateStatus` in `CLEAN`/`UNSTABLE` (not `DIRTY`/`BLOCKED`).
|
||||
- [ ] All `test (3.x)` matrix jobs report `SUCCESS`.
|
||||
- [ ] Local `pytest` on the changed test files passes with **zero failures** (skipped/xfailed tests are OK).
|
||||
- [ ] Lazy-import invariant preserved (if the feature adds an optional dep).
|
||||
- [ ] Cold-import time within ±2 % of `main` (AGENTS.md §4.2).
|
||||
- [ ] No files outside the issue's declared scope were changed.
|
||||
- [ ] The diff respects all invariants in AGENTS.md §4.6.
|
||||
|
||||
If **any** is false → go to Phase 14 (feedback). Do not merge.
|
||||
|
||||
---
|
||||
|
||||
## Phase 14 — Feedback to `@claude` when issues found
|
||||
|
||||
When validation fails, post a precise, actionable comment tagging `@claude`, referencing the exact test name, error, file, and the AGENTS.md principle violated.
|
||||
|
||||
```bash
|
||||
gh pr comment $PR --repo $REPO --body "$(cat <<'EOF'
|
||||
Hold on merge: validated locally on HEAD `<short-sha>` and found these issues:
|
||||
|
||||
**Test failures:**
|
||||
```
|
||||
FAILED tests/.../test_x.py::TestY::test_z
|
||||
AssertionError: <actual-message>
|
||||
```
|
||||
|
||||
**Root cause:** <one-line diagnosis referencing the exact file and line>.
|
||||
|
||||
**AGENTS.md violation(s):**
|
||||
- §<section>: <principle>
|
||||
|
||||
**Requested fix (minimal):**
|
||||
- Change `<file>:<line>` to `<what>`.
|
||||
- Or update the test assertion to `<what>` (if the test is wrong, not the code).
|
||||
|
||||
**What already passes:**
|
||||
- N/M tests pass.
|
||||
- Lazy-import invariant preserved ✅ (or not — state explicitly).
|
||||
|
||||
@claude please push a fix. Follow AGENTS.md principles: minimal change, protocol-driven, no perf impact, lazy imports, backward-compatible, safe defaults. Make sure the PR is robust — run the tests locally before force-pushing.
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
### Loop
|
||||
|
||||
After commenting:
|
||||
|
||||
```bash
|
||||
echo "Waiting 10 minutes for Claude to push fixes..."
|
||||
sleep 600
|
||||
# → return to Phase 12 (fetch new commits, re-run checks)
|
||||
```
|
||||
|
||||
Repeat Phases 12 → 13 → 14 until the mergeability gate in Phase 13 is fully green, or escalate to a human after 3 failed rounds.
|
||||
|
||||
### When the PR has merge conflicts
|
||||
|
||||
If `mergeStateStatus=DIRTY`, ask Claude to rebase rather than resolving conflicts yourself on non-trivial logic:
|
||||
|
||||
```bash
|
||||
gh pr comment $PR --repo $REPO --body "@claude this PR has merge conflicts with \`main\` (PR #<X> was merged, touching the same regions). Please rebase onto latest \`main\`, re-run \`pytest <paths>\`, and force-push."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 15 — Merge to `main`
|
||||
|
||||
Once Phase 13's gate is fully green:
|
||||
|
||||
### 15a. Final diff review against AGENTS.md
|
||||
|
||||
```bash
|
||||
gh pr diff $PR --repo $REPO | less
|
||||
```
|
||||
|
||||
**Hard gate — every box must be ticked before merge:**
|
||||
|
||||
- [ ] **Protocol-driven core (§4.1)**: no heavy implementations leaked into `praisonaiagents`.
|
||||
- [ ] **No perf impact (§4.2)**: lazy imports confirmed; import benchmark within ±2 %.
|
||||
- [ ] **DRY (§4.3)**: no new duplication; existing protocols/adapters reused where possible.
|
||||
- [ ] **Agent-centric (§4.4)**: API centers on agents/sessions/tools/memory.
|
||||
- [ ] **Async-safe + multi-agent safe (§4.5)**: no shared mutable globals; locks where needed.
|
||||
- [ ] **Invariants preserved (§4.6)**: backward compatible, safe defaults, deterministic tests.
|
||||
- [ ] **Naming conventions (§4.9)**: `XProtocol` for interfaces, `XAdapter` for impls, `add_*`/`get_*`/`save`/`load` verbs.
|
||||
- [ ] No `.md` files added beyond those explicitly requested (per user global rule).
|
||||
- [ ] Tests run locally with `timeout` — never hang (per user global rule).
|
||||
|
||||
### 15b. Merge
|
||||
|
||||
```bash
|
||||
gh pr merge $PR --repo $REPO --squash --delete-branch
|
||||
# --squash preserves linear main; --delete-branch keeps the repo clean
|
||||
```
|
||||
|
||||
### 15c. Verify
|
||||
|
||||
```bash
|
||||
gh pr view $PR --repo $REPO --json state,mergedAt,mergeCommit
|
||||
gh issue view $ISSUE_NUM --repo $REPO --json state # should auto-close
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Orchestration Snippet (one-shot reference)
|
||||
|
||||
For a single end-to-end invocation, chain Part B phases:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
REPO=MervinPraison/PraisonAI
|
||||
ISSUE_NUM=<fill>
|
||||
|
||||
# Phase 10: wait for implementing agents
|
||||
sleep 600
|
||||
|
||||
# Phase 11: ensure PR exists
|
||||
BRANCH=$(gh api repos/$REPO/branches --paginate \
|
||||
--jq ".[] | select(.name | startswith(\"claude/issue-$ISSUE_NUM\")) | .name" | head -1)
|
||||
PR=$(gh pr list --repo $REPO --state open --head "$BRANCH" --json number --jq '.[0].number' 2>/dev/null || true)
|
||||
if [ -z "$PR" ] && [ -n "$BRANCH" ]; then
|
||||
TITLE=$(gh api repos/$REPO/commits/$BRANCH --jq '.commit.message' | head -1)
|
||||
gh pr create --repo $REPO --head "$BRANCH" --base main \
|
||||
--title "$TITLE" --body "Closes #$ISSUE_NUM"
|
||||
PR=$(gh pr list --repo $REPO --state open --head "$BRANCH" --json number --jq '.[0].number')
|
||||
fi
|
||||
echo "Tracking PR #$PR"
|
||||
|
||||
# Phase 12: wait for reviewers + CI
|
||||
sleep 600
|
||||
|
||||
# Phases 13–14: validate + feedback loop (cap at 3 rounds)
|
||||
for round in 1 2 3; do
|
||||
echo "=== Validation round $round ==="
|
||||
# clone + pytest (per feature) — if green break; else gh pr comment + sleep 600
|
||||
break # placeholder
|
||||
done
|
||||
|
||||
# Phase 15: merge
|
||||
gh pr merge $PR --repo $REPO --squash --delete-branch
|
||||
gh issue view $ISSUE_NUM --repo $REPO --json state
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist — Before Merging
|
||||
|
||||
- [ ] Issue exists and describes the work
|
||||
- [ ] PR exists and references the issue (`Closes #N`)
|
||||
- [ ] Branch was fetched and tests were run **locally** — not just CI-trusted
|
||||
- [ ] All PR-relevant tests pass with zero failures
|
||||
- [ ] CI matrix (3.10 / 3.11 / 3.12) is all green
|
||||
- [ ] Lazy-import / cold-import invariants verified if optional deps added
|
||||
- [ ] Diff reviewed against every AGENTS.md §4 principle
|
||||
- [ ] `mergeStateStatus` in `CLEAN`/`UNSTABLE`, never `DIRTY`/`BLOCKED`
|
||||
- [ ] No files outside the issue's scope were changed
|
||||
- [ ] If feedback was given, `@claude` had a chance to respond and fixed everything
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference — Common Mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---------|-----|
|
||||
| Merging without running tests locally | Always `git clone` the branch and run `pytest` |
|
||||
| Resolving complex conflicts manually | Ask `@claude` to rebase instead |
|
||||
| Trusting CI alone | CI jobs can be skipped / out-of-date; local validation is source of truth |
|
||||
| Vague feedback to `@claude` | Every comment must cite file, line, test name, error, and AGENTS.md section |
|
||||
| Waiting forever | Cap loops at 3 rounds, then escalate to a human |
|
||||
| Running commands without `timeout` | Always `timeout 60 ...` per user global rule |
|
||||
| Creating `.md` docs proactively | Don't — user rule forbids unrequested `.md` files |
|
||||
| Skipping diff review | Every merge needs a full-diff AGENTS.md pass |
|
||||
|
||||
---
|
||||
|
||||
## Hard Rules
|
||||
|
||||
1. **Never merge without local test validation.**
|
||||
2. **Never merge when `mergeStateStatus = DIRTY` or `BLOCKED`.**
|
||||
3. **Every `@claude` comment must be actionable** — file, line, exact fix, AGENTS.md ref.
|
||||
4. **Cap feedback loops at 3 rounds** — escalate after that, don't spin forever.
|
||||
5. **Use `--squash --delete-branch`** to keep `main` linear and the repo clean.
|
||||
6. **Always verify** the issue auto-closed after merge.
|
||||
7. **All `run_command` calls use `timeout`** to avoid hangs (user global rule).
|
||||
8. **No proactive `.md` creation** beyond this workflow file (user global rule).
|
||||
@@ -1,63 +0,0 @@
|
||||
---
|
||||
description: Project information and deployment reference for PraisonAIUI
|
||||
---
|
||||
|
||||
## Project: PraisonAIUI
|
||||
|
||||
YAML-driven website/docs generator. One YAML file, one docs folder, one command — ship a beautiful documentation site.
|
||||
|
||||
**Aim**: AIUI is a standardised, protocol-driven UI framework for building *any* AI-powered interface — not hardcoded to PraisonAI.
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `aiui.template.yaml` | Site configuration (theme, nav, routes, components) |
|
||||
| `docs/` | Markdown content directory |
|
||||
| `src/praisonaiui/` | Python source (CLI, compiler, server, providers) |
|
||||
| `src/praisonaiui/compiler/` | Build pipeline: config → static site |
|
||||
| `src/praisonaiui/templates/frontend/` | Bundled React SPA (index.html + assets) |
|
||||
| `.github/workflows/ci.yml` | CI (lint, test) + GitHub Pages deployment |
|
||||
| `pyproject.toml` | Package metadata, dependencies, entry points |
|
||||
| `CNAME` | Custom domain: `ui.praison.ai` |
|
||||
|
||||
## CLI Commands
|
||||
|
||||
```bash
|
||||
aiui init # Scaffold new project
|
||||
aiui build # Compile → static site in ./aiui/
|
||||
aiui build --output site --minify # For GitHub Pages
|
||||
aiui serve # Serve built site locally
|
||||
aiui dev # Dev mode with hot reload
|
||||
aiui validate # Validate aiui.template.yaml
|
||||
```
|
||||
|
||||
## Build Output
|
||||
|
||||
`aiui build` produces a fully static SPA:
|
||||
- `index.html` + `assets/` — React frontend bundle
|
||||
- `ui-config.json` — compiled site configuration
|
||||
- `docs-nav.json` — navigation tree from docs folder
|
||||
- `route-manifest.json` — route definitions
|
||||
- `docs/` — copied markdown content
|
||||
|
||||
## Deployment
|
||||
|
||||
- **CI**: On push to `main`, GitHub Actions runs `aiui build --output site --minify`
|
||||
- **Deploy**: `peaceiris/actions-gh-pages@v4` pushes `./site/` to `gh-pages` branch
|
||||
- **Domain**: `ui.praison.ai` via CNAME file copied into build output
|
||||
- **No server required** — everything is static
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
pip install -e .[dev]
|
||||
pytest tests/unit tests/integration -v
|
||||
ruff check src/praisonaiui
|
||||
```
|
||||
|
||||
## Package
|
||||
|
||||
- PyPI name: `aiui`
|
||||
- Entry points: `aiui` and `praisonaiui` (both map to `praisonaiui.cli:app`)
|
||||
- Python: ≥3.9
|
||||
@@ -1,839 +0,0 @@
|
||||
---
|
||||
description: Update install.sh and deploy PraisonAI to Kubernetes via Helm (CI/CD Pipeline)
|
||||
---
|
||||
|
||||
# Install.sh Update & Helm Deployment Workflow
|
||||
|
||||
Complete guide for updating the PraisonAI install script and deploying to Kubernetes via the full CI/CD pipeline.
|
||||
|
||||
**⚠️ CRITICAL**: This workflow contains **NO SECRETS**. All sensitive values (tokens, passwords) must be passed via environment variables or external secret management.
|
||||
|
||||
## 📁 Key Locations (MUST KNOW)
|
||||
|
||||
### Scripts
|
||||
| File/Resource | Absolute Path | Purpose |
|
||||
|---------------|---------------|----------|
|
||||
| **install.sh** | `/Users/praison/praisonai-package/src/praisonai/scripts/install.sh` | Main bash installer |
|
||||
| **install.ps1** | `/Users/praison/praisonai-package/src/praisonai/scripts/install.ps1` | PowerShell installer |
|
||||
|
||||
### CI/CD Pipeline (GitHub → ACR → Helm → K8s)
|
||||
| File/Resource | Absolute Path | Purpose |
|
||||
|---------------|---------------|----------|
|
||||
| **GitHub Workflow** | `/Users/praison/Sites/localhost/praisonai/.github/workflows/azure-pipeline.yaml` | CI/CD pipeline triggered on git push |
|
||||
| **Dockerfile.php** | `/Users/praison/Sites/localhost/praisonai/Dockerfile.php` | PHP container build |
|
||||
| **Dockerfile.nginx** | `/Users/praison/Sites/localhost/praisonai/Dockerfile.nginx` | Nginx container build |
|
||||
| **Dockerfile.init** | `/Users/praison/Sites/localhost/praisonai/Dockerfile.init` | Init container build |
|
||||
|
||||
### Helm Deployment
|
||||
| File/Resource | Absolute Path | Purpose |
|
||||
|---------------|---------------|----------|
|
||||
| **Helm Charts** | `/Users/praison/repos/person/helmcharts/` | All Kubernetes deployments |
|
||||
| **wb_azure Chart** | `/Users/praison/repos/person/helmcharts/charts/wb_azure/` | PraisonAI WordPress deployment |
|
||||
| **Production Values** | `/Users/praison/Sites/localhost/praisonai/values-praisonai-production.yaml` | Production Helm config |
|
||||
| **Local Values** | `/Users/praison/Sites/localhost/praisonai/values-local.yaml` | Local development config |
|
||||
| **Deployment Docs** | `/Users/praison/Sites/localhost/praisonai/DEPLOYMENT.md` | Deployment documentation |
|
||||
| **Deployment Makefile** | `/Users/praison/Sites/localhost/praisonai/Makefile` | Deployment automation |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Full CI/CD Pipeline Overview
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ Git Push │────▶│ GitHub Actions │────▶│ Azure ACR │
|
||||
│ (master) │ │ azure-pipeline │ │ Image Build │
|
||||
└─────────────────┘ └──────────────────┘ └────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ Kubernetes │◀────│ Helm Upgrade │◀────│ Update Image │
|
||||
│ Deployment │ │ (values.yaml) │ │ Tag in Values │
|
||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
### Pipeline Steps:
|
||||
1. **Git push** to master branch
|
||||
2. **GitHub Actions** triggers (`.github/workflows/azure-pipeline.yaml`)
|
||||
3. **Build** Docker images (nginx, php, init)
|
||||
4. **Push** to Azure Container Registry (ACR)
|
||||
5. **Update** Helm values with new image tag
|
||||
6. **Deploy** using Helm upgrade
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Phase 0 - Fully Automated CI/CD Pipeline
|
||||
|
||||
### Complete Auto-Deploy Architecture
|
||||
|
||||
```
|
||||
Git Push ──▶ Build Images ──▶ Trigger Deploy ──▶ Helm Upgrade ──▶ Production
|
||||
│ │ │ │
|
||||
│ ▼ ▼ ▼
|
||||
│ ACR Push helmcharts wb_azure chart
|
||||
│ (pa-php:SHA) repository (K8s deploy)
|
||||
│
|
||||
└─── install.sh ────────────────────────────────────────────────▶ praison.ai/install.sh
|
||||
```
|
||||
|
||||
### Step 0.1: Build Workflow (Automatic on Git Push)
|
||||
|
||||
**File**: `/Users/praison/Sites/localhost/praisonai/.github/workflows/azure-pipeline.yaml`
|
||||
|
||||
**Repository**: `https://github.com/MervinPraison/praison.ai`
|
||||
|
||||
This workflow triggers on every push to `master`:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [master]
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
1. **Syncs install.sh** from PraisonAI repository (only if changed!)
|
||||
- Checks out `MervinPraison/PraisonAI`
|
||||
- Compares `install.sh` and `install.ps1` with existing web files
|
||||
- **Only copies if files have actually changed** (avoids unnecessary redeploys)
|
||||
- This ensures `https://praison.ai/install.sh` is always latest
|
||||
2. Downloads env files from Azure Storage
|
||||
3. Builds multi-arch Docker images (linux/amd64, linux/arm64)
|
||||
4. Pushes to Azure Container Registry: `praison.azurecr.io/pa/`
|
||||
5. **Triggers Helm deployment** via `repository_dispatch` event
|
||||
|
||||
**Key Step - Automatic Deploy Trigger:**
|
||||
```yaml
|
||||
- name: Trigger Helm Deployment
|
||||
run: |
|
||||
SHORT_SHA=$(git rev-parse --short HEAD)
|
||||
curl -X POST \
|
||||
-H "Authorization: token ${{ secrets.HELM_REPO_TOKEN }}" \
|
||||
-d '{
|
||||
"event_type": "deploy_wb_azure",
|
||||
"client_payload": {
|
||||
"image_tag": "'"$SHORT_SHA"'",
|
||||
"source_repo": "'"${{ github.repository }}"'",
|
||||
"source_commit": "'"${{ github.sha }}"'"
|
||||
}
|
||||
}' \
|
||||
https://api.github.com/repos/praison/helmcharts/dispatches
|
||||
```
|
||||
|
||||
### Step 0.2: Deploy Workflow (Triggered Automatically)
|
||||
|
||||
**File**: `/Users/praison/repos/person/helmcharts/.github/workflows/helm-upgrade-with-image.yml`
|
||||
|
||||
Listens for `repository_dispatch` events:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
repository_dispatch:
|
||||
types: [deploy_wb_azure, deploy_tcs_azure, deploy_tamilmanna_azure]
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
1. Receives image tag from build workflow
|
||||
2. Runs `helm upgrade --install wb_azure` with new image tag
|
||||
3. Waits for rollout to complete
|
||||
4. Verifies deployment
|
||||
|
||||
**Result**: Every git push automatically builds AND deploys!
|
||||
|
||||
### Required GitHub Secrets
|
||||
|
||||
For the automated CI/CD to work, you need these secrets configured:
|
||||
|
||||
**In praisonai site repository** (`https://github.com/MervinPraison/praison.ai`):
|
||||
| Secret | Purpose |
|
||||
|--------|---------|
|
||||
| `AZURE_CREDENTIALS` | Azure login for ACR and AKS |
|
||||
| `AZURE_USERNAME` | ACR username |
|
||||
| `AZURE_PASSWORD` | ACR password |
|
||||
| `AZURE_STORAGE_KEY` | Download env files from Azure Storage |
|
||||
| `HELM_REPO_TOKEN` | **NEW**: Trigger deploy workflow in helmcharts repo |
|
||||
|
||||
**In helmcharts repository** (`/Users/praison/repos/person/helmcharts/.github/workflows/`):
|
||||
| Secret | Purpose |
|
||||
|--------|---------|
|
||||
| `AZURE_CREDENTIALS` | Azure login for AKS |
|
||||
| `AKS_CLUSTER_NAME` | Kubernetes cluster name |
|
||||
| `AKS_RESOURCE_GROUP` | Azure resource group |
|
||||
|
||||
**To add HELM_REPO_TOKEN**:
|
||||
1. Go to GitHub Settings → Developer settings → Personal access tokens
|
||||
2. Create token with `repo` scope
|
||||
3. Add as secret `HELM_REPO_TOKEN` in https://github.com/MervinPraison/praison.ai
|
||||
|
||||
**Current status**: ✅ Already configured (set via `gh secret set`)!
|
||||
|
||||
**Images built:**
|
||||
- `praison.azurecr.io/pa/pa-nginx:SHORT_SHA`
|
||||
- `praison.azurecr.io/pa/pa-nginx:master`
|
||||
- `praison.azurecr.io/pa/pa-php:SHORT_SHA`
|
||||
- `praison.azurecr.io/pa/pa-php:master`
|
||||
- `praison.azurecr.io/pa/pa-init:SHORT_SHA`
|
||||
- `praison.azurecr.io/pa/pa-init:master`
|
||||
|
||||
### Step 0.2: Update Helm Values with New Image Tag
|
||||
|
||||
After the ACR build completes, update the Helm values file to use the new image:
|
||||
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
|
||||
# Get the short SHA from the latest commit (matches the Docker tag)
|
||||
SHORT_SHA=$(git rev-parse --short HEAD)
|
||||
|
||||
# Update values file with new image tag
|
||||
helm upgrade praisonai /Users/praison/repos/person/helmcharts/charts/wb_azure \
|
||||
-f values-praisonai-production.yaml \
|
||||
--set image.tag=$SHORT_SHA \
|
||||
--namespace default \
|
||||
--timeout 10m
|
||||
```
|
||||
|
||||
**Alternative**: Update values file permanently:
|
||||
|
||||
```bash
|
||||
# Edit values-praisonai-production.yaml to set image.tag
|
||||
sed -i "s/tag: \".*\"/tag: \"$SHORT_SHA\"/" values-praisonai-production.yaml
|
||||
|
||||
# Then commit and push the updated values
|
||||
git add values-praisonai-production.yaml
|
||||
git commit -m "ci: update image tag to $SHORT_SHA"
|
||||
git push origin master
|
||||
```
|
||||
|
||||
### Step 0.3: Full Automated Script (For CI/CD Integration)
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# deploy-after-build.sh - Run after ACR build completes
|
||||
|
||||
set -e
|
||||
|
||||
SHORT_SHA=$(git rev-parse --short HEAD)
|
||||
NAMESPACE=default
|
||||
RELEASE_NAME=praisonai
|
||||
CHART_PATH=/Users/praison/repos/person/helmcharts/charts/wb_azure
|
||||
VALUES_FILE=/Users/praison/Sites/localhost/praisonai/values-praisonai-production.yaml
|
||||
|
||||
echo "🚀 Deploying PraisonAI with image tag: $SHORT_SHA"
|
||||
|
||||
# Update Helm deployment with new image tag
|
||||
helm upgrade --install $RELEASE_NAME $CHART_PATH \
|
||||
-f $VALUES_FILE \
|
||||
--set image.tag=$SHORT_SHA \
|
||||
--namespace $NAMESPACE \
|
||||
--timeout 10m \
|
||||
--atomic
|
||||
|
||||
echo "✅ Deployment complete!"
|
||||
echo ""
|
||||
echo "Verify with:"
|
||||
echo " kubectl get pods -n $NAMESPACE -l app.kubernetes.io/instance=$RELEASE_NAME"
|
||||
echo " helm status $RELEASE_NAME -n $NAMESPACE"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 0.4: Extend GitHub Actions for Automatic Helm Deployment
|
||||
|
||||
To make the CI/CD fully automated (build → deploy), extend the GitHub Actions workflow:
|
||||
|
||||
**File to edit**: `/Users/praison/Sites/localhost/praisonai/.github/workflows/azure-pipeline.yaml`
|
||||
|
||||
Add a new job after the `build` job:
|
||||
|
||||
```yaml
|
||||
deploy:
|
||||
needs: build # Wait for build to complete
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v2
|
||||
|
||||
- name: Azure Login
|
||||
uses: azure/login@v1
|
||||
with:
|
||||
creds: ${{ secrets.AZURE_CREDENTIALS }}
|
||||
|
||||
- name: Setup kubectl
|
||||
uses: azure/setup-kubectl@v3
|
||||
with:
|
||||
version: 'v1.28.0'
|
||||
|
||||
- name: Setup Helm
|
||||
uses: azure/setup-helm@v3
|
||||
with:
|
||||
version: 'v3.13.0'
|
||||
|
||||
- name: Get AKS credentials
|
||||
run: |
|
||||
az aks get-credentials \
|
||||
--resource-group your-resource-group \
|
||||
--name your-aks-cluster-name \
|
||||
--overwrite-existing
|
||||
|
||||
- name: Deploy with Helm
|
||||
run: |
|
||||
SHORT_SHA=$(git rev-parse --short HEAD)
|
||||
helm upgrade --install praisonai \
|
||||
/Users/praison/repos/person/helmcharts/charts/wb_azure \
|
||||
-f values-praisonai-production.yaml \
|
||||
--set image.tag=$SHORT_SHA \
|
||||
--namespace default \
|
||||
--timeout 10m \
|
||||
--atomic
|
||||
|
||||
- name: Verify deployment
|
||||
run: |
|
||||
kubectl rollout status deployment/php-nginx -n default
|
||||
helm status praisonai -n default
|
||||
```
|
||||
|
||||
**Requirements for automatic deploy:**
|
||||
1. GitHub repository secrets configured:
|
||||
- `AZURE_CREDENTIALS` - Azure service principal credentials
|
||||
- `AZURE_STORAGE_KEY` - For downloading env files
|
||||
- `AZURE_USERNAME` / `AZURE_PASSWORD` - ACR login
|
||||
2. AKS cluster access configured in Azure
|
||||
3. Helm and kubectl available in GitHub Actions runner
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Phase 1 — Update install.sh (Manual, When Needed)
|
||||
|
||||
### When to Update
|
||||
- New PraisonAI version released
|
||||
- New dependency requirements
|
||||
- New OS support needed
|
||||
- Bug fixes in installation process
|
||||
|
||||
### Step 1: Read Current install.sh
|
||||
|
||||
```bash
|
||||
# View the install script
|
||||
cat /Users/praison/praisonai-package/src/praisonai/scripts/install.sh
|
||||
```
|
||||
|
||||
Key sections in install.sh:
|
||||
- **Lines 1-50**: Header, usage, environment variables documentation
|
||||
- **Lines 51-150**: OS detection (macOS, Linux, Windows/WSL)
|
||||
- **Lines 151-300**: Python installation (version checks, package managers)
|
||||
- **Lines 301-450**: Virtual environment setup
|
||||
- **Lines 451-550**: PraisonAI package installation
|
||||
- **Lines 551-637**: PATH configuration, shell integration, verification
|
||||
|
||||
### Step 2: Make Changes
|
||||
|
||||
**Common Changes:**
|
||||
|
||||
#### Update Default Version
|
||||
```bash
|
||||
# Find this line (around line 70):
|
||||
PRAISONAI_VERSION="${PRAISONAI_VERSION:-latest}"
|
||||
|
||||
# Change to specific version if needed:
|
||||
PRAISONAI_VERSION="${PRAISONAI_VERSION:-1.5.0}"
|
||||
```
|
||||
|
||||
#### Add New Environment Variable
|
||||
```bash
|
||||
# Add to header section (after line 10, in the comment block):
|
||||
# PRAISONAI_NEW_FEATURE - Description (default: value)
|
||||
|
||||
# Add to actual code (around line 75):
|
||||
export PRAISONAI_NEW_FEATURE="${PRAISONAI_NEW_FEATURE:-default_value}"
|
||||
```
|
||||
|
||||
#### Update Python Version Requirements
|
||||
```bash
|
||||
# Find Python version check (around line 100-120):
|
||||
PYTHON_MIN_VERSION="3.9"
|
||||
|
||||
# Update if needed:
|
||||
PYTHON_MIN_VERSION="3.10"
|
||||
```
|
||||
|
||||
### Step 3: Test Changes
|
||||
|
||||
```bash
|
||||
# Test locally (dry run)
|
||||
cd /Users/praison/praisonai-package/src/praisonai/scripts
|
||||
bash install.sh --dry-run
|
||||
|
||||
# Test in Docker (full test)
|
||||
bash /Users/praison/praisonai-package/src/praisonai/scripts/test-install-smoke.sh
|
||||
```
|
||||
|
||||
### Step 4: Verify Both Scripts
|
||||
|
||||
```bash
|
||||
# Check install.sh syntax
|
||||
bash -n /Users/praison/praisonai-package/src/praisonai/scripts/install.sh
|
||||
|
||||
# Check install.ps1 syntax (if pwsh available)
|
||||
pwsh -Command "Get-Command /Users/praison/praisonai-package/src/praisonai/scripts/install.ps1"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Phase 2 — Deploy to Kubernetes (Helm)
|
||||
|
||||
### Pre-Deployment Checklist
|
||||
|
||||
```bash
|
||||
# 1. Verify kubectl connection
|
||||
kubectl get nodes
|
||||
|
||||
# 2. Check current Helm releases
|
||||
helm list -n default
|
||||
|
||||
# 3. Verify chart exists
|
||||
ls /Users/praison/repos/person/helmcharts/charts/wb_azure/
|
||||
```
|
||||
|
||||
### Deployment Types
|
||||
|
||||
#### A. Fresh Deployment (First Time)
|
||||
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
|
||||
# Option 1: Using Makefile
|
||||
make deploy
|
||||
|
||||
# Option 2: Manual helm command
|
||||
helm upgrade --install praisonai /Users/praison/repos/person/helmcharts/charts/wb_azure \
|
||||
-f values-praisonai-production.yaml \
|
||||
--namespace default \
|
||||
--timeout 10m \
|
||||
--atomic
|
||||
```
|
||||
|
||||
#### B. Update Existing Deployment
|
||||
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
|
||||
# Edit values file first
|
||||
vim values-praisonai-production.yaml
|
||||
|
||||
# Then apply
|
||||
make upgrade
|
||||
|
||||
# Or manually:
|
||||
helm upgrade praisonai /Users/praison/repos/person/helmcharts/charts/wb_azure \
|
||||
-f values-praisonai-production.yaml \
|
||||
--namespace default \
|
||||
--timeout 10m
|
||||
```
|
||||
|
||||
#### C. Local Development Deployment
|
||||
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
make local-deploy
|
||||
```
|
||||
|
||||
### Values File Structure
|
||||
|
||||
```yaml
|
||||
# /Users/praison/Sites/localhost/praisonai/values-praisonai-production.yaml
|
||||
|
||||
# Core settings
|
||||
replicaCount: 2
|
||||
|
||||
# Database
|
||||
dbHost: "10.0.0.11"
|
||||
dbUser: "bible_4"
|
||||
dbPassword: "changeme" # Override via --set
|
||||
|
||||
# OpenAI tokens (for plugin verification)
|
||||
openaiVerificationToken: "token-here"
|
||||
|
||||
# Feature toggles
|
||||
praisonai:
|
||||
enabled: true
|
||||
domain: praison.ai
|
||||
|
||||
whiteboard:
|
||||
enabled: true
|
||||
domain: whiteboard.gallery
|
||||
|
||||
# Disable other sites
|
||||
bible: { enabled: false }
|
||||
music: { enabled: false }
|
||||
save: { enabled: false }
|
||||
|
||||
# Resources
|
||||
resources:
|
||||
requests:
|
||||
cpu: 800m
|
||||
memory: 1024Mi
|
||||
limits:
|
||||
cpu: 2000m
|
||||
memory: 2048Mi
|
||||
|
||||
# Auto-scaling
|
||||
autoscaling:
|
||||
enabled: true
|
||||
minReplicas: 2
|
||||
maxReplicas: 10
|
||||
|
||||
# Ingress
|
||||
ingress:
|
||||
enabled: true
|
||||
className: nginx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Phase 3 — Verify Deployment
|
||||
|
||||
### Check Deployment Status
|
||||
|
||||
```bash
|
||||
# Using Makefile
|
||||
make status
|
||||
|
||||
# Manual checks
|
||||
helm status praisonai -n default
|
||||
kubectl get pods -l app.kubernetes.io/instance=praisonai -n default
|
||||
kubectl get svc -l app.kubernetes.io/instance=praisonai -n default
|
||||
```
|
||||
|
||||
### Verify All Resources
|
||||
|
||||
```bash
|
||||
# Pods should be Running
|
||||
kubectl get pods -n default | grep praisonai
|
||||
|
||||
# Services should be Active
|
||||
kubectl get svc -n default | grep praisonai
|
||||
|
||||
# Ingress should exist
|
||||
kubectl get ingress -n default | grep praisonai
|
||||
|
||||
# ConfigMaps
|
||||
kubectl get configmap -n default | grep nginx-config
|
||||
|
||||
# Secrets
|
||||
kubectl get secret -n default | grep db-password
|
||||
```
|
||||
|
||||
### Check Application Health
|
||||
|
||||
```bash
|
||||
# Port forward and test
|
||||
echo "Visit http://127.0.0.1:8080"
|
||||
kubectl port-forward svc/php-nginx 8080:80 -n default
|
||||
|
||||
# In another terminal:
|
||||
curl http://127.0.0.1:8080/test.php
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Phase 4 — Rollback (If Needed)
|
||||
|
||||
```bash
|
||||
# View revision history
|
||||
make history
|
||||
|
||||
# Rollback to previous revision
|
||||
make rollback
|
||||
|
||||
# Or manually:
|
||||
helm rollback praisonai 1 -n default
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Phase 5 — Troubleshooting
|
||||
|
||||
### Problem: "Resource exists and cannot be imported"
|
||||
|
||||
**Cause**: Existing Kubernetes resources not managed by Helm.
|
||||
|
||||
**Solution**: Adopt resources into Helm
|
||||
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
./scripts/adopt-resources.sh praisonai default
|
||||
```
|
||||
|
||||
Or manually annotate:
|
||||
|
||||
```bash
|
||||
# For any resource type
|
||||
kubectl annotate <resource-type> <name> \
|
||||
meta.helm.sh/release-name=praisonai \
|
||||
meta.helm.sh/release-namespace=default
|
||||
|
||||
kubectl label <resource-type> <name> \
|
||||
app.kubernetes.io/managed-by=Helm
|
||||
```
|
||||
|
||||
### Problem: Pods Not Starting
|
||||
|
||||
```bash
|
||||
# Check events
|
||||
kubectl get events -n default --sort-by='.lastTimestamp' | tail -20
|
||||
|
||||
# Check pod logs
|
||||
kubectl logs -l app.kubernetes.io/instance=praisonai -n default
|
||||
|
||||
# Describe pod for details
|
||||
kubectl describe pod <pod-name> -n default
|
||||
```
|
||||
|
||||
### Problem: Image Pull Errors
|
||||
|
||||
```bash
|
||||
# Check image pull secrets
|
||||
kubectl get secret acr-auth -n default
|
||||
|
||||
# Verify ACR auth exists
|
||||
kubectl create secret docker-registry acr-auth \
|
||||
--docker-server=praison.azurecr.io \
|
||||
--docker-username=<username> \
|
||||
--docker-password=<password> \
|
||||
-n default
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Phase 6 — Post-Deployment
|
||||
|
||||
### Update Documentation
|
||||
|
||||
If install.sh changed, update:
|
||||
1. `/Users/praison/PraisonAIDocs/docs/installation.mdx` — Installation docs
|
||||
2. `/Users/praison/praisonai-package/src/praisonai/scripts/README.md` — Script docs (if exists)
|
||||
|
||||
### Verify Website
|
||||
|
||||
```bash
|
||||
# Check praison.ai is accessible
|
||||
curl -I https://praison.ai
|
||||
|
||||
# Check whiteboard.gallery
|
||||
curl -I https://whiteboard.gallery
|
||||
```
|
||||
|
||||
### Monitor
|
||||
|
||||
```bash
|
||||
# Watch pods
|
||||
kubectl get pods -l app.kubernetes.io/instance=praisonai -n default -w
|
||||
|
||||
# Check resource usage
|
||||
kubectl top pods -l app.kubernetes.io/instance=praisonai -n default
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Reference: Helm Chart Structure
|
||||
|
||||
```
|
||||
/Users/praison/repos/person/helmcharts/charts/wb_azure/
|
||||
├── Chart.yaml # Chart metadata (name: wb, version: 1.0.1)
|
||||
├── values.yaml # Default values (fallback)
|
||||
├── templates/
|
||||
│ ├── deployment.yaml # Main php-nginx deployment
|
||||
│ ├── service.yaml # NodePort service
|
||||
│ ├── ingress.yaml # TLS + routing
|
||||
│ ├── nginx-configMap.yaml # Server configs
|
||||
│ ├── db-password-secret.yaml # DB credentials
|
||||
│ ├── pdb.yaml # Pod disruption budget
|
||||
│ ├── autoscalar.yml # HPA
|
||||
│ ├── cert-manager.yaml # TLS certificates
|
||||
│ └── _helpers.tpl # Template helpers
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Commands Reference
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| Deploy | `make deploy` |
|
||||
| Update | `make upgrade` |
|
||||
| Status | `make status` |
|
||||
| History | `make history` |
|
||||
| Rollback | `make rollback` |
|
||||
| Logs | `make logs` |
|
||||
| Restart | `make restart` |
|
||||
| Local dev | `make local-deploy` |
|
||||
| Dry run | `make dry-run` |
|
||||
| Lint | `make lint` |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Critical Rules
|
||||
|
||||
1. **Never commit SQL dumps**: `.gitignore` already excludes `*.sql` files
|
||||
2. **Never commit secrets**: Use `--set` or external secret management
|
||||
3. **Always test install.sh** after changes (use test-install-smoke.sh)
|
||||
4. **Always verify deployment** with `make status` after Helm operations
|
||||
5. **Use Infrastructure as Code**: All changes via Helm values files, never manual kubectl
|
||||
6. **Version control**: Commit values files (without secrets), never commit generated manifests
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Getting Help
|
||||
|
||||
If stuck:
|
||||
|
||||
1. Check `/Users/praison/Sites/localhost/praisonai/DEPLOYMENT.md` for detailed docs
|
||||
2. Check `/Users/praison/Sites/localhost/praisonai/INFRASTRUCTURE_AS_CODE_SUMMARY.md` for quick reference
|
||||
3. Run `helm status praisonai -n default` for deployment status
|
||||
4. Run `kubectl get events -n default` for cluster events
|
||||
5. View install.sh comments for usage examples (lines 1-50)
|
||||
|
||||
---
|
||||
|
||||
## 🔄 CI/CD Pipeline Summary (For New Agents)
|
||||
|
||||
### Complete Workflow (Fully Automated!)
|
||||
|
||||
```
|
||||
Developer Push ──────────────────────────────────────────────▶ Production
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐
|
||||
│ 1. Git Push to │───▶│ 2. GitHub Actions │───▶│ 3. Sync │
|
||||
│ master │ │ Trigger │ │ install.sh │
|
||||
└─────────────────┘ └──────────────────┘ └────────┬─────────┘
|
||||
│
|
||||
┌────────────────────────┘
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ 4. Azure ACR │
|
||||
│ Build Images │
|
||||
│ + Push │
|
||||
└────────┬─────────┘
|
||||
│
|
||||
──────▶┌──────────────────┐
|
||||
│ 5. Trigger Deploy│
|
||||
│ (repository_ │
|
||||
│ dispatch) │
|
||||
└────────┬─────────┘
|
||||
│
|
||||
┌─────────────────┐ ┌──────────────────┐ │
|
||||
│ 7. Production │◀───│ 6. Helm Upgrade │◀──┘
|
||||
│ Running │ │ Deploy │
|
||||
│ (includes │ │ │
|
||||
│ install.sh) │ │ │
|
||||
└─────────────────┘ └──────────────────┘
|
||||
```
|
||||
|
||||
**🎉 Fully Automated**: Git push → Build → Deploy (No manual steps!)
|
||||
|
||||
### Automatic install.sh Sync
|
||||
|
||||
**Key Point**: The workflow automatically syncs `install.sh` from `MervinPraison/PraisonAI` repository **only if changed**:
|
||||
|
||||
```yaml
|
||||
- name: Checkout PraisonAI for install.sh
|
||||
uses: actions/checkout@v2
|
||||
with:
|
||||
repository: MervinPraison/PraisonAI
|
||||
path: praisonai-package
|
||||
|
||||
- name: Sync install.sh to web folder (if changed)
|
||||
run: |
|
||||
# Only sync if files have actually changed
|
||||
if ! diff -q praisonai-package/src/praisonai/scripts/install.sh ./web/install.sh; then
|
||||
cp praisonai-package/src/praisonai/scripts/install.sh ./web/install.sh
|
||||
fi
|
||||
```
|
||||
|
||||
**Optimization**: Uses `diff` to compare files - only copies when install.sh or install.ps1 have actually changed. This avoids unnecessary Docker layer rebuilds and deployments.
|
||||
|
||||
**Result**: `https://praison.ai/install.sh` is automatically updated **only when the source files change**!
|
||||
|
||||
### How install.sh is Served
|
||||
|
||||
The `web/install.sh` file is copied into the Docker image at `/var/www/html/web/install.sh` and served by nginx:
|
||||
|
||||
```nginx
|
||||
# In nginx-config, requests to praison.ai/install.sh
|
||||
# are served from /var/www/html/web/install.sh
|
||||
location / {
|
||||
root /var/www/html/web;
|
||||
try_files $uri $uri/ =404;
|
||||
}
|
||||
```
|
||||
|
||||
**URL Mapping**:
|
||||
| File in Repo | URL |
|
||||
|--------------|-----|
|
||||
| `web/install.sh` | `https://praison.ai/install.sh` |
|
||||
| `web/install.ps1` | `https://praison.ai/install.ps1` |
|
||||
|
||||
### What Files to Edit
|
||||
|
||||
| To Change | Edit File |
|
||||
|-----------|-----------|
|
||||
| Application code | `/Users/praison/Sites/localhost/praisonai/` (PHP files) |
|
||||
| Docker images | `Dockerfile.php`, `Dockerfile.nginx`, `Dockerfile.init` |
|
||||
| CI/CD pipeline | `.github/workflows/azure-pipeline.yaml` |
|
||||
| Helm deployment config | `values-praisonai-production.yaml` |
|
||||
| Install script | `/Users/praison/praisonai-package/src/praisonai/scripts/install.sh` |
|
||||
|
||||
### Common Tasks
|
||||
|
||||
**Task 1: Deploy new code**
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
git add .
|
||||
git commit -m "feat: new feature"
|
||||
git push origin master
|
||||
# CI/CD automatically builds and deploys
|
||||
```
|
||||
|
||||
**Task 2: Update install.sh and deploy**
|
||||
```bash
|
||||
# 1. Update install.sh
|
||||
vim /Users/praison/praisonai-package/src/praisonai/scripts/install.sh
|
||||
|
||||
# 2. Test install.sh
|
||||
bash /Users/praison/praisonai-package/src/praisonai/scripts/install.sh --dry-run
|
||||
|
||||
# 3. Commit and push
|
||||
git add /Users/praison/praisonai-package/src/praisonai/scripts/install.sh
|
||||
git commit -m "fix: update install script"
|
||||
git push origin main
|
||||
|
||||
# 4. Deploy website (if needed)
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
make upgrade
|
||||
```
|
||||
|
||||
**Task 3: Rollback deployment**
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
make rollback
|
||||
# Or: helm rollback praisonai 1 -n default
|
||||
```
|
||||
|
||||
### Architecture
|
||||
|
||||
| Layer | Technology | Purpose |
|
||||
|-------|------------|---------|
|
||||
| Source Control | Git/GitHub | Code repository |
|
||||
| CI/CD | GitHub Actions | Automated build/deploy |
|
||||
| Container Registry | Azure ACR | Docker image storage |
|
||||
| Orchestration | Kubernetes (AKS) | Container management |
|
||||
| Deployment | Helm | K8s package management |
|
||||
| Ingress | NGINX Ingress + cert-manager | Traffic routing + TLS |
|
||||
|
||||
### Security Notes
|
||||
|
||||
- **No secrets in workflow files** - All tokens/passwords via env vars
|
||||
- **ACR authentication** - Uses `acr-auth` secret in Kubernetes
|
||||
- **GitHub Secrets** - `AZURE_CREDENTIALS`, `AZURE_USERNAME`, `AZURE_PASSWORD`
|
||||
- **Never commit** `.env` files, SQL dumps, or credentials
|
||||
@@ -1,181 +0,0 @@
|
||||
---
|
||||
description: instruction
|
||||
---
|
||||
|
||||
Create multiple TODOs and sub-TODOs, get all things done.
|
||||
First: detailed analysis, plan, and gap analysis. Go through all files, understand current logic. Search if needed.
|
||||
Then: implement, fix, test (TDD, Agent-Centric, no perf impact, DRY). praisonaiagents is protocol-driven. Run unit, integration, smoke, and real agentic tests.
|
||||
After: re-do detailed analysis/plan to find remaining gaps and propose fixes.
|
||||
|
||||
Docs: beginner-friendly, for non-developers. Explain concepts with mermaid diagrams (Dark Red #8B0000 for agents/inputs/outputs, Teal #189AB4 for tools, white #fff text). Less descriptive, more interactive. Use Mintlify components: Accordions, Badge, Callouts (Note/Warning/Info/Tip/Check/Danger), Cards/Columns, CodeGroup, Expandables, Tabs, Steps, Frame, Icon, Tooltip, Mermaid, ParamField, Tables, CardGroup.
|
||||
|
||||
You are an expert AI engineer in the PraisonAI ecosystem.
|
||||
Production-quality code, zero regressions, full verification. Make PraisonAI the best agent framework.
|
||||
|
||||
### Core Philosophy
|
||||
```
|
||||
Simpler • More extensible • Faster • Agent-centric
|
||||
```
|
||||
|
||||
| Principle | Rule |
|
||||
|---|---|
|
||||
| Agent-Centric | Design centers on Agents, workflows, sessions, tools, memory |
|
||||
| Protocol-Driven | Core SDK: protocols/hooks/adapters only; heavy code in wrapper/tools |
|
||||
| Minimal API | Fewer params, sensible defaults, explicit overrides |
|
||||
| Performance-First | Lazy loading, optional deps, no hot-path regressions |
|
||||
| Production-Ready | Safe by default, multi-agent safe, async-safe |
|
||||
|
||||
- Powerful, lightweight, reliable. Easy for non-developers.
|
||||
- "Few lines of code to do the task!" — SDK and docs must feel this way.
|
||||
- Each feature runs 3 ways: CLI, YAML, Python.
|
||||
- Open source, developer-first. Core free, clear upgrade path to paid (support/cloud/services).
|
||||
- Simple to adopt, hard to misuse, safe by default.
|
||||
- Prioritise time saved, reduced risk, and operational confidence.
|
||||
- Reduce production friction, not just add functionality.
|
||||
- All features must have CLI integration. Agent-first naming and ergonomics.
|
||||
|
||||
ENGINEERING PRINCIPLES (MUST)
|
||||
- DRY: reuse abstractions, no duplication.
|
||||
- Protocol-driven core: protocols/hooks in core; heavy impl in wrapper/tools.
|
||||
- No perf impact: lazy imports, optional deps, no global singletons, no heavy module-level work.
|
||||
- TDD mandatory: tests first.
|
||||
- Multi-agent + async safe by default.
|
||||
- AGENTS.md is not for documentation.
|
||||
|
||||
CRITICAL REQUIREMENTS
|
||||
- EXECUTE + VERIFY mode. No guessing. Proof for "done."
|
||||
- Optional deps only; lazy import everything heavy.
|
||||
- Every feature/fix: Python + CLI + docs/examples.
|
||||
- Any core change must be justified: simpler client API, measurable benefit, NO perf regression.
|
||||
- If TypeScript parity required: update praisonai-ts, but never at cost of Python core performance.
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
CANONICAL PATHS (MUST use these)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
- Core SDK: /Users/praison/praisonai-package/src/praisonai-agents → praisonaiagents
|
||||
- Wrapper: /Users/praison/praisonai-package/src/praisonai → praisonai
|
||||
- Tools: /Users/praison/PraisonAI-tools → praisonai-tools
|
||||
- Docs: /Users/praison/PraisonAIDocs (read AGENTS.md first before updating docs)
|
||||
- Docs JS: /Users/praison/PraisonAIDocs/docs/js | Rust: docs/rust
|
||||
- Examples: /Users/praison/praisonai-package/examples/
|
||||
- TypeScript: /Users/praison/praisonai-package/src/praisonai-ts
|
||||
- Rust: /Users/praison/praisonai-package/src/praisonai-rust (follow praisonai-ts/AGENTS.md)
|
||||
- UI (this repo): /Users/praison/praisonaiui → praisonaiui
|
||||
- Extension points: tools/base.py, tools/decorator.py, db/*
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
ARCHITECTURE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Core (praisonaiagents): protocol-driven, lightweight. No heavy imports. Only protocols/hooks/adapters.
|
||||
Wrapper (praisonai): real integrations (DBs, observability, CLI). Lazy imports, optional deps.
|
||||
Tools (PraisonAI-tools): pluggable, never overload core/wrapper.
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
MANDATORY EXECUTION FLOW
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
PHASE 1 — ANALYSIS (before writing code)
|
||||
|
||||
1.1 Acceptance Criteria — testable bullets for API, CLI, docs, tests, perf.
|
||||
|
||||
1.2 Repo Inventory — scan relevant files end-to-end:
|
||||
- modules/classes/APIs/exports, CLI commands, tests, docs/examples
|
||||
- Evidence: paths + symbols + grep counts. Identify DRY opportunities.
|
||||
|
||||
1.3 Gap Analysis — what exists vs what's needed:
|
||||
- Missing: core SDK, wrapper, tools, CLI, docs, tests, exports
|
||||
- Risks: perf, API breaks, optional deps, async, multi-agent
|
||||
|
||||
1.4 Report — current behavior, pain points, root causes (file refs), constraints, risk register, decision log.
|
||||
|
||||
1.5 Plan — step-by-step: tests → impl → CLI → docs → verify. Files to change. Compat/rollback/perf strategy.
|
||||
|
||||
1.6 Proposal — minimal agent-centric design. Protocols in core, impl in wrapper. Upgrade-path notes.
|
||||
|
||||
1.7 TODO Tree — granular, executable. Python + CLI + TDD + docs + perf.
|
||||
- Second-to-last: "Verify all changes end-to-end"
|
||||
- Last: "Implement remaining gaps (missing=0), re-verify" or "Final scan, confirm missing=0"
|
||||
|
||||
PHASE 2 — EXECUTE
|
||||
|
||||
2.1 TDD — write failing tests first. Deterministic and fast.
|
||||
2.2 Implement — DRY, agent-centric, protocol-driven. Heavy code in wrapper/tools. Multi-agent + async safe.
|
||||
2.3 CLI parity — add/extend CLI commands. Scriptable, clear help, proper exit codes.
|
||||
2.4 Docs — Mintlify pages (SDK="Module", API="API"). Copy-paste runnable examples.
|
||||
2.5 Verification:
|
||||
- Run tests (unit/integration), show results.
|
||||
- Smoke: `python3 -c "..."` + CLI help/run.
|
||||
- Optional deps graceful degradation.
|
||||
- Perf: no heavy core imports, import-time sanity.
|
||||
- Provide evidence for every claim.
|
||||
- dont use Sending termination request to command to terminate a process, kill port instead when terminating
|
||||
|
||||
REAL AGENTIC TEST (MANDATORY — not replaceable by smoke tests)
|
||||
- After unit/smoke tests, MUST run at least one REAL agent execution:
|
||||
1. Create Agent with the feature being tested
|
||||
2. Call `agent.start("a real task prompt")` — NOT just constructing the object
|
||||
3. Agent MUST call LLM and produce text response
|
||||
4. Print full output so dev can see it worked end-to-end
|
||||
- Minimum example:
|
||||
```python
|
||||
from praisonaiagents import Agent
|
||||
agent = Agent(name="test", instructions="You are a helpful assistant")
|
||||
result = agent.start("Say hello in one sentence")
|
||||
print(result)
|
||||
```
|
||||
- Assert-only object construction = SMOKE TEST, not real agentic test.
|
||||
- Both smoke AND real agentic tests required.
|
||||
|
||||
PHASE 3 — POST-IMPLEMENTATION ANALYSIS
|
||||
|
||||
3.1 Re-scan files, summarize final behavior/architecture.
|
||||
3.2 Confirm remaining gaps (API, CLI, docs, tests, exports, perf, multi-agent, async). If gaps exist, treat as required work until missing=0.
|
||||
3.3 Report: what changed, why, validation evidence, tradeoffs.
|
||||
3.4 Plan: close remaining gaps or maintenance plan.
|
||||
3.5 Proposal: refinements for UX, safety, perf, extensibility. Label: implemented vs out-of-scope.
|
||||
|
||||
Final rule: conclude only when evidence shows missing = 0.
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
PUBLISH WORKFLOW (reference)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GitHub Actions (recommended):
|
||||
GitHub → Actions → "PyPI Release" → Run workflow → bump: patch
|
||||
Requires repo secrets: PYPI_TOKEN, GH_TOKEN
|
||||
Requires GitHub Environment "pypi" with required reviewers (Settings → Environments)
|
||||
|
||||
Manual — Publish aiui (PraisonAIUI):
|
||||
cd /Users/praison/PraisonAIUI
|
||||
# Bump version in pyproject.toml and src/praisonaiui/__version__.py
|
||||
rm -rf dist && uv lock && uv build && uv publish --token "$PYPI_TOKEN"
|
||||
git add pyproject.toml uv.lock src/praisonaiui/__version__.py
|
||||
git commit -m "Release vX.Y.Z" && git tag vX.Y.Z && git push && git push --tags
|
||||
gh release create vX.Y.Z --title "PraisonAIUI vX.Y.Z" --notes "Release vX.Y.Z" --latest
|
||||
|
||||
PyPI package name: aiui
|
||||
Verify: pip index versions aiui | head -1
|
||||
|
||||
PraisonAI stack (separate repo — publish SDK before wrapper):
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents
|
||||
praisonai publish pypi
|
||||
# Uses uv internally: uv lock → uv build → uv publish
|
||||
# Auto-bumps patch version, requires PYPI_TOKEN env var
|
||||
|
||||
Step 2 — Publish praisonai (Wrapper):
|
||||
cd /Users/praison/praisonai-package/src/praisonai
|
||||
python scripts/bump_and_release.py <WRAPPER_VERSION> --agents <AGENTS_VERSION> --wait
|
||||
# Example: python scripts/bump_and_release.py 4.5.90 --agents 1.5.91 --wait
|
||||
# Waits for agents to be available on PyPI, bumps all version files,
|
||||
# runs uv lock, builds, commits, tags, pushes, creates GitHub release
|
||||
# Then: uv publish (from src/praisonai with clean dist/)
|
||||
|
||||
If bump_and_release published already, just verify:
|
||||
pip index versions praisonai | head -1
|
||||
|
||||
If uv publish fails with "File already exists", it means the version is already on PyPI — success.
|
||||
|
||||
Step 3 — Publish praisonai-tools (External, if needed):
|
||||
cd /Users/praison/PraisonAI-tools
|
||||
# Bump version in pyproject.toml, then:
|
||||
python3.13 -m build && uv run twine upload dist/*
|
||||
|
||||
PraisonAI PRs: NEVER merge automatically — user merges manually.
|
||||
@@ -1,223 +0,0 @@
|
||||
---
|
||||
description: Implement, fix, and test code changes locally — for when the agent IS the implementer
|
||||
---
|
||||
|
||||
# Local Fix Workflow
|
||||
|
||||
You are the implementer. Analyze → Plan → Implement → Test → Verify → PR.
|
||||
|
||||
> **When to use this:** The user explicitly asks you to fix something locally, or delegates a task that cannot be handled by the GitHub cloud agents.
|
||||
> **When NOT to use this:** If given an Issue URL, prefer `@[/pr-review]` Step 8d — delegate to cloud agents first.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Analysis (before writing ANY code)
|
||||
|
||||
### 1a. Understand the problem
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && git checkout main && git pull origin main
|
||||
```
|
||||
|
||||
Read all relevant source files end-to-end. Use `grep`, `view_file`, and code navigation.
|
||||
|
||||
- Identify root cause with **file paths and line numbers**
|
||||
- Trace the full code path (caller → callee → side effects)
|
||||
- Assess blast radius (what else could break)
|
||||
- Check for existing abstractions before creating new ones (DRY)
|
||||
|
||||
### 1b. Create TODO tree
|
||||
|
||||
Break work into granular, executable items:
|
||||
```
|
||||
- [ ] Write failing test(s)
|
||||
- [ ] Implement fix (file:line references)
|
||||
- [ ] CLI parity (if applicable)
|
||||
- [ ] Docs update (if applicable)
|
||||
- [ ] Run unit + integration tests
|
||||
- [ ] Run real agentic test
|
||||
- [ ] Verify end-to-end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Implement
|
||||
|
||||
### 2a. TDD — tests first
|
||||
|
||||
Write the failing test before touching implementation code.
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents && \
|
||||
python -m pytest tests/<relevant_test>.py -x -v --tb=short
|
||||
```
|
||||
|
||||
### 2b. Implement the fix
|
||||
|
||||
**Architecture rules (MUST follow):**
|
||||
|
||||
| Layer | What goes here | What does NOT go here |
|
||||
|-------|---------------|----------------------|
|
||||
| **Core SDK** (`praisonaiagents/`) | Protocols, hooks, adapters, base classes, decorators, dataclasses | Heavy implementations, optional deps at module level |
|
||||
| **Wrapper** (`praisonai/`) | CLI commands, integrations, heavy impls, DB adapters, UI | Core logic |
|
||||
| **Tools** (`PraisonAI-tools/`) | Pluggable tools, community extensions | Core or wrapper logic |
|
||||
|
||||
**Coding standards:**
|
||||
|
||||
- **Lazy imports**: Optional deps imported inside functions, never at module level
|
||||
- **DRY**: Reuse existing abstractions; refactor if duplication found
|
||||
- **Naming**: `add_X()`, `get_X()`, `XConfig`, `XProtocol`, `XAdapter`
|
||||
- **Async-safe**: No blocking I/O in async context; use asyncio primitives
|
||||
- **Multi-agent safe**: No shared mutable globals without `threading.Lock`
|
||||
- **Security**: No hardcoded secrets; `hmac.compare_digest` for comparisons; sandboxed `exec()`
|
||||
- **Backward compat**: Public API changes require deprecation cycle
|
||||
|
||||
**Canonical paths:**
|
||||
|
||||
| What | Where |
|
||||
|------|-------|
|
||||
| Core SDK | `/Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/` |
|
||||
| Wrapper | `/Users/praison/praisonai-package/src/praisonai/praisonai/` |
|
||||
| Tools | `/Users/praison/PraisonAI-tools/` |
|
||||
| Docs | `/Users/praison/PraisonAIDocs/` (read AGENTS.md first) |
|
||||
| Examples | `/Users/praison/praisonai-package/examples/` |
|
||||
| TypeScript | `/Users/praison/praisonai-package/src/praisonai-ts/` |
|
||||
|
||||
### 2c. CLI parity
|
||||
|
||||
Every feature must work 3 ways: **Python, CLI, YAML**. If your change adds or modifies a feature, ensure CLI support exists.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Test & Verify
|
||||
|
||||
### 3a. Unit + Integration tests
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents && \
|
||||
python -m pytest tests/ -x -q \
|
||||
--ignore=tests/integration/test_whatsapp_web_real.py \
|
||||
--ignore=tests/unit/tools/test_profiles.py \
|
||||
--tb=short 2>&1 | tail -20
|
||||
```
|
||||
|
||||
### 3b. Real agentic test (MANDATORY)
|
||||
|
||||
Unit tests alone are NOT sufficient. You MUST run at least one real agent execution:
|
||||
|
||||
```python
|
||||
from praisonaiagents import Agent
|
||||
agent = Agent(name="test", instructions="You are a helpful assistant")
|
||||
result = agent.start("Say hello in one sentence")
|
||||
print(result)
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Agent MUST call `agent.start()` with a real prompt
|
||||
- Agent MUST call the LLM and produce a text response
|
||||
- Print full output — assert-only object construction is a SMOKE test, not agentic
|
||||
- Both smoke AND real agentic tests required
|
||||
|
||||
### 3c. Security checks (if touching sensitive code)
|
||||
|
||||
```bash
|
||||
# Hardcoded secrets
|
||||
grep -rn "secret\|password\|token\|api_key" --include="*.py" <changed-files> | \
|
||||
grep -v "test_\|#\|environ\|getenv\|config"
|
||||
|
||||
# Timing attacks
|
||||
grep -rn "==.*api_key\|==.*secret\|==.*token" --include="*.py" <changed-files>
|
||||
|
||||
# Sandbox escapes
|
||||
grep -rn "exec(\|eval(" --include="*.py" <changed-files>
|
||||
```
|
||||
|
||||
### 3d. Performance sanity
|
||||
|
||||
```bash
|
||||
# Verify no heavy imports at module level
|
||||
python -c "import time; t=time.time(); import praisonaiagents; print(f'{(time.time()-t)*1000:.0f}ms')"
|
||||
```
|
||||
|
||||
Target: < 200ms package import time.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Post-implementation scan
|
||||
|
||||
Re-scan changed files. Confirm:
|
||||
- [ ] No remaining gaps (API, CLI, docs, tests, exports, perf)
|
||||
- [ ] No regressions introduced
|
||||
- [ ] All acceptance criteria met with evidence
|
||||
|
||||
If gaps remain → loop back to Phase 2. Conclude only when `missing = 0`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Submit
|
||||
|
||||
### 5a. Create branch and PR
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
git checkout -b <type>/<descriptive-name> && \
|
||||
git add -A && \
|
||||
git commit -m "<type>: <description>" && \
|
||||
git push origin <type>/<descriptive-name>
|
||||
```
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh pr create \
|
||||
--title "<type>: <description>" \
|
||||
--body '## Summary
|
||||
<what and why>
|
||||
|
||||
### Changes
|
||||
- <file>: <what changed>
|
||||
|
||||
### Testing
|
||||
- Unit tests: ✅
|
||||
- Agentic test: ✅
|
||||
- Security: ✅ (if applicable)' \
|
||||
--head <type>/<descriptive-name> \
|
||||
--base main
|
||||
```
|
||||
|
||||
**Commit prefixes:** `fix:`, `feat:`, `security:`, `refactor:`, `docs:`, `test:`
|
||||
|
||||
> **Do NOT merge automatically** — user merges manually unless explicitly told otherwise.
|
||||
|
||||
### 5b. Verify PR state
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && gh pr view --json state,title,url | cat
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Publish (only when user requests)
|
||||
|
||||
```bash
|
||||
# Core SDK
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents && praisonai publish pypi
|
||||
|
||||
# Wrapper
|
||||
cd /Users/praison/praisonai-package/src/praisonai && \
|
||||
python scripts/bump_and_release.py <VERSION> --agents <AGENTS_VERSION> --wait
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference — Red Flags
|
||||
|
||||
| Red Flag | Fix |
|
||||
|----------|-----|
|
||||
| Module-level `import chromadb` | Move inside function with `try/except ImportError` |
|
||||
| `exec(user_input)` without sandbox | Use `RestrictedPython` or sandbox module |
|
||||
| `if token == secret:` | Use `hmac.compare_digest(token, secret)` |
|
||||
| Shared mutable global `_cache = {}` | Add `threading.Lock`, or make per-agent |
|
||||
| `debug=True` in production path | Remove or gate behind env var |
|
||||
| Missing `async` variant for I/O | Add async version, wrap for sync callers |
|
||||
@@ -1,275 +0,0 @@
|
||||
---
|
||||
description: Review, validate, and merge GitHub pull requests or triage issues
|
||||
---
|
||||
|
||||
# PR / Issue Review Workflow
|
||||
|
||||
When given a GitHub PR or Issue URL, follow this procedure end-to-end.
|
||||
|
||||
---
|
||||
|
||||
## Step 0 — Determine Type
|
||||
|
||||
Parse the URL to identify whether it is a **Pull Request** or an **Issue**.
|
||||
|
||||
```
|
||||
https://github.com/MervinPraison/PraisonAI/pull/<NUMBER> → PR
|
||||
https://github.com/MervinPraison/PraisonAI/issues/<NUMBER> → Issue
|
||||
```
|
||||
|
||||
- **PR** → go to Step 1
|
||||
- **Issue** → go to Step 8
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Fetch PR Metadata
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh pr view <NUMBER> --json title,body,author,state,additions,deletions,changedFiles,headRefName,baseRefName,labels
|
||||
```
|
||||
|
||||
Record: title, author, branch, file count, +/- lines.
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Read the Full Diff
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && gh pr diff <NUMBER>
|
||||
```
|
||||
|
||||
If the diff is very large (>500 lines), pipe through `head -500` first, then read remaining chunks.
|
||||
|
||||
---
|
||||
|
||||
## Step 3 — Review the Diff
|
||||
|
||||
For each changed file, evaluate against **PraisonAI engineering principles** (from AGENTS.md):
|
||||
|
||||
| Principle | What to Check |
|
||||
|-----------|---------------|
|
||||
| **Protocol-driven core** | No heavy implementations in `praisonaiagents/` (core SDK) |
|
||||
| **Lazy imports** | Optional deps imported inside functions, not at module level |
|
||||
| **DRY** | No code duplication; reuse existing abstractions |
|
||||
| **Naming conventions** | `add_X()`, `get_X()`, `XConfig`, `XProtocol`, `XAdapter` |
|
||||
| **Async-safe** | No blocking I/O in async context; asyncio primitives used |
|
||||
| **Multi-agent safe** | No shared mutable global state without locks |
|
||||
| **Thread safety** | Double-checked locking for lazy caches; `threading.Lock` for mutables |
|
||||
| **Security** | No hardcoded secrets; `hmac.compare_digest` for comparisons; restricted `exec()` |
|
||||
| **Backward compat** | Public API changes require deprecation cycle |
|
||||
| **Test coverage** | Tests included; TDD pattern; both unit + agentic tests |
|
||||
|
||||
**Red flags to catch:**
|
||||
- Module-level imports of optional deps (chromadb, litellm, etc.)
|
||||
- Hardcoded credentials or `debug=True` in production paths
|
||||
- Direct string comparison for secrets (timing attacks)
|
||||
- `exec()`/`eval()` without sandbox
|
||||
- Shared mutable globals without `threading.Lock`
|
||||
- Missing error handling or swallowed exceptions
|
||||
|
||||
---
|
||||
|
||||
## Step 4 — Checkout and Run Tests Locally
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && git checkout main && git pull origin main
|
||||
```
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && gh pr checkout <NUMBER>
|
||||
```
|
||||
|
||||
Run targeted tests for changed files first:
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents && \
|
||||
python -m pytest tests/ -x -q \
|
||||
--ignore=tests/integration/test_whatsapp_web_real.py \
|
||||
--ignore=tests/unit/tools/test_profiles.py \
|
||||
--tb=short 2>&1 | tail -20
|
||||
```
|
||||
|
||||
For PRs touching security-sensitive code, also run:
|
||||
|
||||
```bash
|
||||
# Sandbox tests
|
||||
python -m pytest tests/unit/tools/test_python_tools_sandbox.py -v
|
||||
|
||||
# CWE-78 env injection tests
|
||||
python -m pytest src/praisonai/tests/unit/test_cwe78_env_injection.py -v
|
||||
|
||||
# Thread-safety tests
|
||||
python -m pytest tests/unit/test_thread_safety.py -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — Verify No Regressions
|
||||
|
||||
Run the full test suite:
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents && \
|
||||
python -m pytest tests/ -q \
|
||||
--ignore=tests/integration/test_whatsapp_web_real.py \
|
||||
--ignore=tests/unit/tools/test_profiles.py \
|
||||
--tb=no 2>&1 | tail -5
|
||||
```
|
||||
|
||||
**Acceptable result:** All tests pass, or only pre-existing flaky tests fail (e.g., `test_file_memory.py::test_memory_persistence_across_agent_instances`).
|
||||
|
||||
**Unacceptable:** Any NEW failure introduced by the PR.
|
||||
|
||||
---
|
||||
|
||||
## Step 6 — Approve or Request Changes
|
||||
|
||||
**If the PR is good:**
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh pr review <NUMBER> --approve --body "LGTM — reviewed diff, tests pass, follows PraisonAI engineering principles."
|
||||
```
|
||||
|
||||
**If changes are needed:**
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh pr review <NUMBER> --request-changes --body "Requesting changes: <specific feedback>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7 — Merge
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh pr merge <NUMBER> --merge --subject "<PR title>"
|
||||
```
|
||||
|
||||
Verify merge:
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && gh pr view <NUMBER> --json state,mergedAt
|
||||
```
|
||||
|
||||
Then return to main:
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && git checkout main && git pull origin main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 8 — Issue Triage (if URL is an Issue)
|
||||
|
||||
### 8a. Fetch issue details
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh issue view <NUMBER> --json title,body,author,state,labels,comments
|
||||
```
|
||||
|
||||
### 8b. Classify severity
|
||||
|
||||
| Tier | Criteria | Examples |
|
||||
|------|----------|---------|
|
||||
| **Tier 1 — Critical** | Security vuln, data loss, crash in hot path | exec() without sandbox, hardcoded secrets, unprotected globals |
|
||||
| **Tier 2 — High** | Performance regression, broken feature, wrong output | Duplicate API calls, memory leak, silent failure |
|
||||
| **Tier 3 — Medium** | DX issue, missing validation, doc gap | Bad error messages, missing CLI parity, stale docs |
|
||||
| **Tier 4 — Low** | Cosmetic, code style, minor refactor | Trailing whitespace, naming inconsistency |
|
||||
|
||||
### 8c. Deep analysis (for Tier 1-2)
|
||||
|
||||
1. Read ALL relevant source files end-to-end
|
||||
2. Trace the code path that the issue describes
|
||||
3. Identify root cause with file paths and line numbers
|
||||
4. Assess blast radius (what else could be affected)
|
||||
5. Determine if the issue is **actually what it claims** (re-classify if needed)
|
||||
|
||||
### 8d. Delegate Implementation to GitHub Workflow Agents
|
||||
|
||||
> **KEY PHILOSOPHY: We act as the Manager, GitHub Actions execute the Workflow.**
|
||||
|
||||
**DO NOT implement the fix yourself locally.** PraisonAI uses autonomous GitHub Action workflows (such as `gemini-issue-review.yml` and `claude.yml`) to automatically resolve issues and create PRs. Your job as the local agent is to supervise, analyze gaps, and trigger these cloud agents to do the heavy lifting. If there is a gap (e.g. strict test violations), provide detailed relevant information in the PR/Issue and trigger the agents again.
|
||||
|
||||
1. Issue the command to trigger the cloud agent on the issue:
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh issue comment <NUMBER> --body "@gemini please review and fix this issue"
|
||||
```
|
||||
*(Note: You can use `@claude` or `@gemini` depending on preference or active bots).*
|
||||
|
||||
2. Check the GitHub Actions logs (`gh run list`) and wait for the cloud agent to open a Pull Request (`gh pr list`).
|
||||
3. Once the cloud bot opens a Pull Request for the issue, return to **Step 1** to review the PR, test the branch locally, and merge it if it passes the checks.
|
||||
|
||||
---
|
||||
|
||||
## Step 9 — (Skipped) Local PR Creation
|
||||
|
||||
> **Note:** As the local agent, you should delegate code fixes to the cloud agents. Only implement code locally and create a PR if the USER explicitly forces you to bypass the cloud agents. If forced, use standard prefixes: `fix:`, `feat:`, `security:`, `refactor:`, `docs:`, `test:`.
|
||||
|
||||
---
|
||||
|
||||
## Step 10 — Security-Specific Checks
|
||||
|
||||
When reviewing security-related PRs, additionally verify:
|
||||
|
||||
### Credentials / Secrets
|
||||
```bash
|
||||
# Check for hardcoded secrets
|
||||
grep -rn "secret\|password\|token\|api_key" --include="*.py" <changed-files> | \
|
||||
grep -v "test_\|#\|environ\|getenv\|config"
|
||||
```
|
||||
|
||||
### Timing Attacks
|
||||
```bash
|
||||
# Ensure hmac.compare_digest for secret comparisons
|
||||
grep -rn "==.*api_key\|==.*secret\|==.*token" --include="*.py" <changed-files>
|
||||
```
|
||||
|
||||
### Authentication & Workflow Secrets
|
||||
When reviewing GitHub Actions workflows (especially ones using cloud actions like `claude-code-action`):
|
||||
- **OIDC Validation**: Any workflow using OIDC to authenticate with a cloud provider (e.g. AWS Bedrock for Claude, GCP for Vertex) **MUST** include `id-token: write` in the job's `permissions`. Without it, you will see `Could not fetch an OIDC token` errors.
|
||||
- **Valid PAT Usage**: When injecting tokens into workflows via `github_token:`, ensure you use `secrets.GH_TOKEN`. `secrets.PAT_TOKEN` has been known to be invalid or cause `401 Bad credentials` errors when curling GitHub resources. By design, `@copilot` mentions also strictly require `GH_TOKEN`.
|
||||
|
||||
### Supply Chain
|
||||
```bash
|
||||
# Check dependency versions
|
||||
pip show <package-name>
|
||||
# Check for known compromised versions
|
||||
pip install <package>==999 2>&1 | grep "from versions"
|
||||
```
|
||||
|
||||
### IoC Scanning
|
||||
```bash
|
||||
# Check for known malicious files
|
||||
find $(python -c "import site; print(site.getsitepackages()[0])") -name "<suspicious-file>" 2>/dev/null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference — Common Commands
|
||||
|
||||
| Action | Command |
|
||||
|--------|---------|
|
||||
| View PR | `gh pr view <N> --json title,body,state,additions,deletions` |
|
||||
| View diff | `gh pr diff <N>` |
|
||||
| Checkout PR | `gh pr checkout <N>` |
|
||||
| List open PRs | `gh pr list` |
|
||||
| List open issues | `gh issue list` |
|
||||
| View issue | `gh issue view <N>` |
|
||||
| Approve PR | `gh pr review <N> --approve` |
|
||||
| Request changes | `gh pr review <N> --request-changes --body "..."` |
|
||||
| Merge PR | `gh pr merge <N> --merge` |
|
||||
| Create PR | `gh pr create --title "..." --body "..." --head <branch> --base main` |
|
||||
| Run tests | `cd src/praisonai-agents && python -m pytest tests/ -q --tb=no` |
|
||||
| Check dep version | `pip show <package>` |
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
description: PR review chain — how automated reviews flow for every PR
|
||||
---
|
||||
|
||||
## Review Chain (Sequential)
|
||||
|
||||
> **KEY PHILOSOPHY: We act as the Manager, GitHub Actions execute the Workflow.**
|
||||
> As the local agent, our job is to analyze, supervise, and coordinate the cloud bots. If we identify a gap in the review chain or code (e.g., missing tests), provide detailed relevant information and trigger the agents (like `@claude`) again.
|
||||
```
|
||||
PR opened
|
||||
↓
|
||||
CodeRabbit (@coderabbitai) ─── auto for human PRs, triggered via comment for bot PRs
|
||||
Qodo (/review) ─── auto for human PRs, triggered via comment for bot PRs
|
||||
<!-- Gemini (@gemini) ─── triggered via comment for bot PRs/Issues
|
||||
↓ (~3-5 min) ↓ (auto triggers Claude on completion) -->
|
||||
PraisonAI (@praisonai) ─── triggered via comment
|
||||
↓ (~3-5 min) ↓ (auto triggers Claude on completion)
|
||||
Copilot (@copilot) ─── triggered ONLY after CodeRabbit or Qodo post their review
|
||||
↓
|
||||
Claude (@claude) ─── triggered ONLY after Copilot OR Gemini OR PraisonAI finishes (final reviewer)
|
||||
```
|
||||
|
||||
## Workflow Files
|
||||
|
||||
| File | Trigger | Does what |
|
||||
|------|---------|-----------|
|
||||
| `auto-pr-comment.yml` | `issue_comment`, `pull_request_review`, `pull_request:opened` | Triggers Copilot after CodeRabbit/Qodo finish. For bot PRs: triggers CodeRabbit+Qodo+Gemini first. |
|
||||
| `praisonai-pr-review.yml` | `issue_comment`, `workflow_dispatch` | PraisonAI multi-agent PR review triggered by @praisonai mentions. |
|
||||
| `chain-claude-after-copilot.yml` | `pull_request_review:submitted`, `issue_comment` | Triggers Claude after Copilot reviews, AND automatically after Gemini Code Assist finishes fixing issues/PRs. |
|
||||
| `claude.yml` | `issue_comment`, `pull_request_review_comment`, `issues:assigned/labeled` | Claude responds to @claude mentions. |
|
||||
|
||||
## Bot PR fix
|
||||
|
||||
CodeRabbit and Qodo skip `github-actions[bot]` authored PRs by default. The `bot-pr-trigger-reviews` job in `auto-pr-comment.yml` explicitly triggers them via comments.
|
||||
|
||||
## PraisonAI Integration
|
||||
|
||||
PraisonAI provides multi-agent PR review capabilities through the native PraisonAI agent framework. When triggered with `@praisonai`, it deploys a team of specialized agents:
|
||||
|
||||
- **Security Reviewer**: Analyzes for vulnerabilities, authentication issues, and unsafe code practices
|
||||
- **Performance Reviewer**: Identifies bottlenecks, inefficient algorithms, and resource usage issues
|
||||
- **Maintainability Reviewer**: Evaluates code quality, documentation, and adherence to best practices
|
||||
- **Lead Reviewer**: Synthesizes feedback and posts comprehensive review comments
|
||||
|
||||
The workflow uses the agent configuration at `.github/praisonai-reviewer.yaml` and leverages the `praisonai` CLI for execution.
|
||||
|
||||
## Key rules
|
||||
|
||||
- **Copilot ignores bot comments.** All `@copilot` mentions MUST use `GH_TOKEN` (not `GITHUB_TOKEN`) so comments post as `MervinPraison`.
|
||||
- Copilot NEVER triggers before CodeRabbit/Qodo complete.
|
||||
- Claude NEVER triggers before Copilot completes.
|
||||
- Duplicate `@copilot` comments are prevented by checking existing comments.
|
||||
- PraisonAI PRs: NEVER merge automatically — user merges manually.
|
||||
|
||||
## Security & Credentials
|
||||
|
||||
- **OIDC Configuration (`id-token: write`)**: Any workflow utilizing the `anthropics/claude-code-action@beta` (or similar actions requiring JWTs for AWS Bedrock/GCP Vertex) MUST define `id-token: write` under the job's `permissions` block. Missing this causes deep, opaque failures like "Could not fetch an OIDC token" paired with `Bad credentials` execution limits.
|
||||
- **Valid `github_token` Payload**: Always pass `secrets.GH_TOKEN` into `github_token` inputs rather than `secrets.PAT_TOKEN`, as the latter has historically proven invalid and caused silent 401 exceptions on curl requests behind the scenes.
|
||||
@@ -1,178 +0,0 @@
|
||||
// turbo-all
|
||||
|
||||
# OFFICIAL PROCEDURE (per GitHub docs)
|
||||
# Ref: https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory
|
||||
#
|
||||
# AGENT INSTRUCTION: When creating any security-related files, advisories, documentation,
|
||||
# or GitHub issues/PRs, you MUST include references to these official resources:
|
||||
# - Repository: https://github.com/MervinPraison/PraisonAI
|
||||
# - Documentation: https://docs.praison.ai
|
||||
# - Website: https://praison.ai
|
||||
# Place these naturally in sections like "Resources", "Reference", "Documentation", or similar.
|
||||
#
|
||||
# 1. Reporter submits draft advisory → state=triage
|
||||
# 2. Maintainer validates, collaborates on fix privately
|
||||
# 3. Maintainer sets affected/patched versions, credits reporter
|
||||
# 4. Maintainer publishes fix to PyPI BEFORE publishing advisory
|
||||
# 5. Maintainer publishes advisory → triggers Dependabot alerts
|
||||
# 6. Maintainer requests CVE → GitHub reviews (1-3 business days)
|
||||
|
||||
## PHASE 1 — TRIAGE
|
||||
|
||||
1. List all advisories:
|
||||
```bash
|
||||
gh api repos/MervinPraison/PraisonAI/security-advisories --jq '.[] | "\(.ghsa_id) \(.state) \(.severity) \(.summary | .[0:70])"'
|
||||
```
|
||||
|
||||
2. For each advisory, read full details:
|
||||
```bash
|
||||
gh api repos/MervinPraison/PraisonAI/security-advisories/<GHSA_ID> --jq '{ghsa: .ghsa_id, severity: .severity, state: .state, summary: .summary, description: .description, cwes: [.cwes[].cwe_id], credits: [.credits[].login], vulnerable: [.vulnerabilities[].vulnerable_version_range], patched: [.vulnerabilities[].patched_versions], package: [.vulnerabilities[].package.name]}'
|
||||
```
|
||||
|
||||
3. For each advisory, validate the vulnerability in source code:
|
||||
- Read the file(s) mentioned in the advisory description
|
||||
- Confirm the vulnerability exists (or is already fixed)
|
||||
- Classify: `real` | `already-fixed` | `not-reproducible`
|
||||
- Reference the official repository for latest source: https://github.com/MervinPraison/PraisonAI
|
||||
|
||||
## PHASE 2 — VALIDATE & FIX
|
||||
|
||||
4. **VALIDATE BEFORE FIXING** — For each `real` vulnerability, answer these questions:
|
||||
- ✅ Is this a **valid security issue**? (Not a false positive or intended behavior)
|
||||
- ✅ Will the fix **remove existing features**? (If yes, STOP and escalate)
|
||||
- ✅ Will the fix **bloat the SDK**? (Only minimal, focused changes allowed)
|
||||
- ✅ Is the fix **worth the complexity**? (Low-risk issues may not need fixing)
|
||||
|
||||
**ONLY PROCEED IF ALL CHECKS PASS.** If any check fails, document why and move to next advisory.
|
||||
|
||||
5. For each validated vulnerability, fix the code LOCALLY on `main` branch.
|
||||
- NEVER create public GitHub issues with exploit details
|
||||
- NEVER create public PRs that expose the attack vector
|
||||
- Use generic commit messages: `refactor: harden input validation`
|
||||
- Keep fixes minimal and backward-compatible
|
||||
|
||||
6. Run tests to verify fixes don't break anything:
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents
|
||||
PYTHONPATH=. pytest tests/unit/ -q --timeout=30
|
||||
```
|
||||
|
||||
7. Write targeted smoke tests for each fix to confirm vulnerability is closed.
|
||||
|
||||
8. Commit and push with generic message:
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package
|
||||
git add -A
|
||||
git commit -m "refactor: harden input validation and query parameterization"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
## PHASE 3 — PUBLISH PACKAGES (MUST complete before Phase 4)
|
||||
|
||||
9. Publish praisonaiagents (Core SDK):
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents
|
||||
praisonai publish pypi
|
||||
```
|
||||
Requires `PYPI_TOKEN` env var. Uses uv internally (uv lock → uv build → uv publish). Auto-bumps patch version.
|
||||
|
||||
10. Commit version bump, push:
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package
|
||||
git add -A && git commit -m "chore: bump praisonaiagents to <NEW_VERSION>" && git push origin main
|
||||
```
|
||||
|
||||
11. Publish praisonai (Wrapper):
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai
|
||||
python scripts/bump_and_release.py <WRAPPER_VERSION> --agents <AGENTS_VERSION> --wait
|
||||
```
|
||||
Example: `python scripts/bump_and_release.py 4.5.91 --agents 1.5.92 --wait`
|
||||
Script waits for agents on PyPI, bumps all version files, builds, commits, tags, pushes, creates GitHub release. Then if needed:
|
||||
```bash
|
||||
rm -rf dist/ && uv build && uv publish --token $PYPI_TOKEN
|
||||
```
|
||||
|
||||
12. Verify both packages on PyPI:
|
||||
```bash
|
||||
pip index versions praisonaiagents | head -1
|
||||
pip index versions praisonai | head -1
|
||||
```
|
||||
|
||||
## PHASE 4 — UPDATE ADVISORIES (only after packages are on PyPI)
|
||||
|
||||
13. For each advisory, reopen to draft state and set patched versions + credits:
|
||||
```bash
|
||||
gh api repos/MervinPraison/PraisonAI/security-advisories/<GHSA_ID> \
|
||||
--method PATCH \
|
||||
--input - <<'EOF'
|
||||
{
|
||||
"state": "draft",
|
||||
"credits": [{"login": "<REPORTER_LOGIN>", "type": "reporter"}],
|
||||
"vulnerabilities": [
|
||||
{
|
||||
"package": {"ecosystem": "pip", "name": "<PACKAGE_NAME>"},
|
||||
"vulnerable_version_range": "<= <LAST_VULNERABLE_VERSION>",
|
||||
"patched_versions": ">= <FIRST_PATCHED_VERSION>"
|
||||
}
|
||||
]
|
||||
}
|
||||
EOF
|
||||
```
|
||||
- `<PACKAGE_NAME>`: `praisonaiagents` for core SDK, `praisonai` for wrapper
|
||||
- `<LAST_VULNERABLE_VERSION>`: version before the fix
|
||||
- `<FIRST_PATCHED_VERSION>`: the version just published with the fix
|
||||
- Always include credits for the reporter
|
||||
|
||||
14. Publish each advisory:
|
||||
```bash
|
||||
gh api repos/MervinPraison/PraisonAI/security-advisories/<GHSA_ID> \
|
||||
--method PATCH --field state=published
|
||||
```
|
||||
|
||||
15. Request CVE for each published advisory:
|
||||
```bash
|
||||
gh api repos/MervinPraison/PraisonAI/security-advisories/<GHSA_ID>/cve --method POST
|
||||
```
|
||||
GitHub reviews and assigns CVE IDs within 1-3 business days.
|
||||
|
||||
16. Verify final state:
|
||||
```bash
|
||||
gh api repos/MervinPraison/PraisonAI/security-advisories --jq '.[] | "\(.ghsa_id) \(.state) \(.cve_id // "pending") \(.severity) \([.credits[].login] | join(",") ) \(.summary | .[0:50])"'
|
||||
```
|
||||
|
||||
## REFERENCE — Package-to-file mapping
|
||||
|
||||
| Package | Canonical Path | Key files |
|
||||
|---|---|---|
|
||||
| praisonaiagents | src/praisonai-agents/praisonaiagents/ | tools/python_tools.py, mcp/, memory/, agent/ |
|
||||
| praisonai | src/praisonai/praisonai/ | ui/sql_alchemy.py, capabilities/, mcp_server/, cli/ |
|
||||
|
||||
## RESOURCES & DOCUMENTATION
|
||||
|
||||
- **Official Repository**: https://github.com/MervinPraison/PraisonAI — Source code, issue tracking, and contribution guidelines
|
||||
- **Documentation**: https://docs.praison.ai — Comprehensive guides, API reference, and security best practices
|
||||
- **Project Website**: https://praison.ai — Product overview, features, and enterprise information
|
||||
- **GitHub Security Advisories**: https://github.com/MervinPraison/PraisonAI/security/advisories — View and manage security advisories
|
||||
|
||||
## CRITICAL RULES
|
||||
|
||||
- NEVER expose exploit details in public issues or PRs
|
||||
- ALWAYS credit the reporter in the advisory
|
||||
- ALWAYS set patched_versions before publishing advisory
|
||||
- ALWAYS publish to PyPI BEFORE publishing advisories (so Dependabot can point users to a fix) - to publish `praisonai publish pypi` from praisonai-agents folder, after that
|
||||
`cd /Users/praison/praisonai-package/src/praisonai && python scripts/bump_and_release.py 4.5.125 --agents 1.5.125 --wait`. 4.5.125 is praisonai version number and 1.5.125 is praisonaiagents version number. Last 2 numbers will be same 4/1.xx.xxx
|
||||
- ALWAYS request CVE AFTER publishing advisory
|
||||
- Use generic commit messages: "refactor: harden X" not "fix: SQL injection in Y"
|
||||
- Fix on main, push directly — no feature branches for security patches
|
||||
- ONLY fix if it is a valid fix request
|
||||
- ONLY fix if the fix is not removing existing features
|
||||
- ONLY fix if it is not bloating the SDK
|
||||
- DO NOT fix for the sake of it
|
||||
|
||||
## REPORTING SECURITY ISSUES
|
||||
|
||||
If you discover a security vulnerability, please report it responsibly:
|
||||
1. Open a draft security advisory at https://github.com/MervinPraison/PraisonAI/security/advisories/new
|
||||
2. Include detailed reproduction steps and impact assessment
|
||||
3. Allow time for the maintainers to address the issue before public disclosure
|
||||
@@ -1,64 +0,0 @@
|
||||
---
|
||||
description: Trigger Claude to fix an issue using the full architectural prompt
|
||||
---
|
||||
|
||||
Use this workflow when you want to manually trigger Claude on an issue (especially for external users) using the complete, strict set of architectural rules.
|
||||
|
||||
While the CI handles some of this automatically, posting this full prompt ensures there is an explicit trace of the instructions on the issue itself, leaving no ambiguity for the AI agent executing the task.
|
||||
|
||||
### 1. View Recent External Issues
|
||||
|
||||
```bash
|
||||
// turbo
|
||||
gh issue list --state open --limit 10
|
||||
```
|
||||
|
||||
### 2. Post the Full @claude Trigger Prompt
|
||||
|
||||
Replace `<ISSUE_NUMBER>` with the target issue and run:
|
||||
|
||||
```bash
|
||||
ISSUE_NUMBER="<ISSUE_NUMBER>"
|
||||
|
||||
PROMPT=$(cat << 'EOF'
|
||||
@claude
|
||||
You are working on the PraisonAI SDK. Follow AGENTS.md strictly.
|
||||
|
||||
STEP 0 — SETUP GIT IDENTITY:
|
||||
git config user.name "MervinPraison"
|
||||
git config user.email "[email protected]"
|
||||
|
||||
STEP 1 — READ GUIDELINES:
|
||||
Read AGENTS.md to understand the architecture rules.
|
||||
|
||||
STEP 2 — ARCHITECTURE VALIDATION & ROUTING (MANDATORY before writing code):
|
||||
Before implementing anything, answer these questions:
|
||||
- CORE vs WRAPPER vs TOOLS ROUTING:
|
||||
1. Core SDK (praisonaiagents/): Only core protocols, base classes, decorators. No heavy implementations.
|
||||
2. Wrapper (praisonai/): CLI, heavy implementations, optional dependencies.
|
||||
3. Tools (PraisonAI-Tools): Specific integrations, external tools (e.g. SurrealDB, Slack), and community extensions MUST go to the `MervinPraison/PraisonAI-Tools` repository. If the feature is a tool, clone `https://github.com/MervinPraison/PraisonAI-Tools`, implement it there, and create the PR using `gh pr create -R MervinPraison/PraisonAI-Tools`.
|
||||
- Does it duplicate existing functionality? Check if Agent already supports this via existing params (reflection, planning, tools, hooks, memory).
|
||||
- Does it inherit from Agent properly? New agent types MUST inherit Agent, not wrap it with composition.
|
||||
- Does it add new dependencies? Only optional deps allowed, must be lazy-imported.
|
||||
- Will agent.py grow larger? If the change adds >50 lines to agent.py, find a way to extract instead.
|
||||
- Is there a name collision with existing exports in `__init__.py`?
|
||||
If ANY of these conceptual checks fail (excluding routing), add a comment to the issue explaining why and close it. Do NOT create a PR.
|
||||
|
||||
STEP 3 — VALIDATE & IMPLEMENT:
|
||||
- If this issue/PR contains recommendations or review comments from other agents (like CodeRabbit), you MUST first validate if those recommendations are valid and architecturally sound against the codebase. Explain your findings.
|
||||
- Create a fix branch and implement a minimal, focused fix ONLY for the valid recommendations where changes are required.
|
||||
- Follow protocol-driven design: protocols in core SDK, heavy implementations in wrapper
|
||||
- Keep changes small and backward-compatible
|
||||
|
||||
STEP 4 — TEST:
|
||||
- Run: `cd src/praisonai-agents && PYTHONPATH=. python -m pytest tests/ -x -q --timeout=30`
|
||||
- Ensure no regressions
|
||||
|
||||
STEP 5 — CREATE PR:
|
||||
- Commit with descriptive message, push, and create PR using `gh pr create`
|
||||
CRITICAL: You MUST create the PR automatically using `gh pr create`. Do NOT just provide a link.
|
||||
EOF
|
||||
)
|
||||
|
||||
gh issue comment $ISSUE_NUMBER -b "$PROMPT"
|
||||
```
|
||||
@@ -1,31 +0,0 @@
|
||||
.git
|
||||
.github
|
||||
__pycache__
|
||||
*.pyc
|
||||
.pytest_cache
|
||||
.ruff_cache
|
||||
node_modules
|
||||
.venv
|
||||
*.egg-info
|
||||
dist
|
||||
build
|
||||
tests
|
||||
docs
|
||||
examples
|
||||
*.md
|
||||
!README.md
|
||||
.windsurf
|
||||
.cursor
|
||||
.agent
|
||||
.praisonai
|
||||
.vscode
|
||||
_site
|
||||
site
|
||||
aiui
|
||||
uv.lock
|
||||
prd.md
|
||||
AGENTS.md
|
||||
CNAME
|
||||
mkdocs.yml
|
||||
.env
|
||||
.DS_Store
|
||||
@@ -1,290 +0,0 @@
|
||||
name: "Claude Code Action"
|
||||
description: "Run Claude Code in GitHub Actions workflows"
|
||||
|
||||
inputs:
|
||||
anthropic_api_key:
|
||||
description: "Anthropic API key"
|
||||
required: false
|
||||
claude_code_oauth_token:
|
||||
description: "Claude Code OAuth Token for Claude Pro"
|
||||
required: false
|
||||
github_token:
|
||||
description: "GitHub token for Claude to operate with"
|
||||
required: false
|
||||
default: ${{ github.token }}
|
||||
trigger_phrase:
|
||||
description: "The trigger phrase to look for in comments, issue/PR bodies, and issue titles"
|
||||
required: false
|
||||
default: "@claude"
|
||||
assignee_trigger:
|
||||
description: "The assignee username that triggers the action (e.g. @claude). Only used for issue assignment"
|
||||
required: false
|
||||
max_turns:
|
||||
description: "Maximum number of conversation turns Claude can take"
|
||||
required: false
|
||||
timeout_minutes:
|
||||
description: "Timeout in minutes for execution"
|
||||
required: false
|
||||
default: "30"
|
||||
model:
|
||||
description: "Model to use (provider-specific format required for Bedrock/Vertex)"
|
||||
required: false
|
||||
use_bedrock:
|
||||
description: "Use Amazon Bedrock with OIDC authentication instead of direct Anthropic API"
|
||||
required: false
|
||||
default: "false"
|
||||
use_vertex:
|
||||
description: "Use Google Vertex AI with OIDC authentication instead of direct Anthropic API"
|
||||
required: false
|
||||
default: "false"
|
||||
allowed_tools:
|
||||
description: "Additional tools for Claude to use (the base GitHub tools will always be included)"
|
||||
required: false
|
||||
default: ""
|
||||
disallowed_tools:
|
||||
description: "Tools that Claude should never use"
|
||||
required: false
|
||||
default: ""
|
||||
custom_instructions:
|
||||
description: "Additional custom instructions to include in the prompt for Claude"
|
||||
required: false
|
||||
default: ""
|
||||
mcp_config:
|
||||
description: "Additional MCP configuration (JSON string) that merges with the built-in GitHub MCP servers"
|
||||
required: false
|
||||
default: ""
|
||||
claude_env:
|
||||
description: "Custom environment variables to pass to Claude Code execution (YAML format)"
|
||||
required: false
|
||||
default: ""
|
||||
direct_prompt:
|
||||
description: "Direct prompt for Claude to execute automatically without needing a trigger (for automated workflows)"
|
||||
required: false
|
||||
|
||||
runs:
|
||||
using: "composite"
|
||||
steps:
|
||||
- name: Install Claude Code
|
||||
shell: bash
|
||||
run: npm install -g @anthropic-ai/claude-code
|
||||
|
||||
- name: Install GitHub MCP Server
|
||||
shell: bash
|
||||
run: |
|
||||
claude mcp add-json github '{
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"-i",
|
||||
"--rm",
|
||||
"-e",
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN",
|
||||
"ghcr.io/github/github-mcp-server:sha-ff3036d"
|
||||
],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "${{ inputs.github_token }}"
|
||||
}
|
||||
}'
|
||||
|
||||
- name: Extract GitHub Context and Create Prompt
|
||||
shell: bash
|
||||
id: prepare_context
|
||||
env:
|
||||
# Pass user-controlled inputs via environment variables to prevent script injection (GHSL-2025-093)
|
||||
EVENT_COMMENT_BODY: ${{ github.event.comment.body }}
|
||||
EVENT_ISSUE_TITLE: ${{ github.event.issue.title }}
|
||||
EVENT_ISSUE_BODY: ${{ github.event.issue.body }}
|
||||
EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
|
||||
EVENT_PR_TITLE: ${{ github.event.pull_request.title }}
|
||||
EVENT_PR_NUMBER: ${{ github.event.pull_request.number }}
|
||||
EVENT_REVIEW_BODY: ${{ github.event.review.body }}
|
||||
EVENT_ASSIGNEE_LOGIN: ${{ github.event.assignee.login }}
|
||||
INPUT_TRIGGER_PHRASE: ${{ inputs.trigger_phrase }}
|
||||
INPUT_ASSIGNEE_TRIGGER: ${{ inputs.assignee_trigger }}
|
||||
INPUT_DIRECT_PROMPT: ${{ inputs.direct_prompt }}
|
||||
EVENT_ACTION: ${{ github.event.action }}
|
||||
EVENT_NAME: ${{ github.event_name }}
|
||||
REPO_NAME: ${{ github.repository }}
|
||||
run: |
|
||||
echo "🔍 Extracting GitHub context from event: $EVENT_NAME"
|
||||
|
||||
# Function to check for trigger phrase
|
||||
check_trigger() {
|
||||
local text="$1"
|
||||
local trigger="$INPUT_TRIGGER_PHRASE"
|
||||
if [[ "$text" == *"$trigger"* ]]; then
|
||||
return 0
|
||||
fi
|
||||
return 1
|
||||
}
|
||||
|
||||
# Extract context based on event type
|
||||
TRIGGER_FOUND="false"
|
||||
USER_REQUEST=""
|
||||
CONTEXT_INFO=""
|
||||
|
||||
case "$EVENT_NAME" in
|
||||
"issue_comment")
|
||||
COMMENT_BODY="$EVENT_COMMENT_BODY"
|
||||
ISSUE_TITLE="$EVENT_ISSUE_TITLE"
|
||||
ISSUE_NUMBER="$EVENT_ISSUE_NUMBER"
|
||||
|
||||
if check_trigger "$COMMENT_BODY"; then
|
||||
TRIGGER_FOUND="true"
|
||||
USER_REQUEST="$COMMENT_BODY"
|
||||
CONTEXT_INFO="Issue Comment on #$ISSUE_NUMBER: $ISSUE_TITLE"
|
||||
fi
|
||||
;;
|
||||
|
||||
"pull_request_review_comment")
|
||||
COMMENT_BODY="$EVENT_COMMENT_BODY"
|
||||
PR_TITLE="$EVENT_PR_TITLE"
|
||||
PR_NUMBER="$EVENT_PR_NUMBER"
|
||||
|
||||
if check_trigger "$COMMENT_BODY"; then
|
||||
TRIGGER_FOUND="true"
|
||||
USER_REQUEST="$COMMENT_BODY"
|
||||
CONTEXT_INFO="PR Comment on #$PR_NUMBER: $PR_TITLE"
|
||||
fi
|
||||
;;
|
||||
|
||||
"pull_request_review")
|
||||
REVIEW_BODY="$EVENT_REVIEW_BODY"
|
||||
PR_TITLE="$EVENT_PR_TITLE"
|
||||
PR_NUMBER="$EVENT_PR_NUMBER"
|
||||
|
||||
if check_trigger "$REVIEW_BODY"; then
|
||||
TRIGGER_FOUND="true"
|
||||
USER_REQUEST="$REVIEW_BODY"
|
||||
CONTEXT_INFO="PR Review on #$PR_NUMBER: $PR_TITLE"
|
||||
fi
|
||||
;;
|
||||
|
||||
"issues")
|
||||
ISSUE_BODY="$EVENT_ISSUE_BODY"
|
||||
ISSUE_TITLE="$EVENT_ISSUE_TITLE"
|
||||
ISSUE_NUMBER="$EVENT_ISSUE_NUMBER"
|
||||
|
||||
if check_trigger "$ISSUE_TITLE" || check_trigger "$ISSUE_BODY"; then
|
||||
TRIGGER_FOUND="true"
|
||||
USER_REQUEST="$ISSUE_BODY"
|
||||
CONTEXT_INFO="Issue #$ISSUE_NUMBER: $ISSUE_TITLE"
|
||||
elif [[ "$EVENT_ACTION" == "assigned" && -n "$INPUT_ASSIGNEE_TRIGGER" ]]; then
|
||||
ASSIGNEE="$EVENT_ASSIGNEE_LOGIN"
|
||||
if [[ "$ASSIGNEE" == "$INPUT_ASSIGNEE_TRIGGER" ]]; then
|
||||
TRIGGER_FOUND="true"
|
||||
USER_REQUEST="$ISSUE_BODY"
|
||||
CONTEXT_INFO="Issue #$ISSUE_NUMBER assigned to $ASSIGNEE: $ISSUE_TITLE"
|
||||
fi
|
||||
fi
|
||||
;;
|
||||
esac
|
||||
|
||||
# Check for direct prompt override
|
||||
if [[ -n "$INPUT_DIRECT_PROMPT" ]]; then
|
||||
TRIGGER_FOUND="true"
|
||||
USER_REQUEST="$INPUT_DIRECT_PROMPT"
|
||||
CONTEXT_INFO="Automated GitHub workflow"
|
||||
fi
|
||||
|
||||
if [[ "$TRIGGER_FOUND" != "true" ]]; then
|
||||
echo "❌ No trigger phrase found or direct prompt provided. Exiting gracefully."
|
||||
echo "SKIP_EXECUTION=true" >> $GITHUB_ENV
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "✅ Trigger found! Context: $CONTEXT_INFO"
|
||||
|
||||
# Create comprehensive prompt
|
||||
mkdir -p /tmp/claude-action
|
||||
cat > /tmp/claude-action/github-context-prompt.txt << EOF
|
||||
You are Claude Code, an AI assistant helping with GitHub workflows and code.
|
||||
|
||||
Repository: $REPO_NAME
|
||||
Context: $CONTEXT_INFO
|
||||
Event: $EVENT_NAME
|
||||
|
||||
User Request:
|
||||
$USER_REQUEST
|
||||
|
||||
Please analyze the request and provide helpful assistance.
|
||||
|
||||
CRITICAL INSTRUCTION: If your task involves modifying codebase files to add a feature or fix a bug:
|
||||
|
||||
STEP 0 — SETUP GIT IDENTITY:
|
||||
git config user.name "MervinPraison"
|
||||
git config user.email "[email protected]"
|
||||
|
||||
STEP 1 — READ GUIDELINES:
|
||||
MANDATORY: Before writing any code, you MUST carefully read "src/praisonai-agents/AGENTS.md" to understand this repository's extremely specific Architecture, Protocol-First design rules, and Agent-Centric Philosophy.
|
||||
|
||||
STEP 2 — ARCHITECTURE VALIDATION & ROUTING (MANDATORY before writing code):
|
||||
Before implementing anything, answer these questions:
|
||||
- CORE vs WRAPPER vs TOOLS ROUTING:
|
||||
1. Core SDK (praisonaiagents/): Only core protocols, base classes, decorators. No heavy implementations.
|
||||
2. Wrapper (praisonai/): CLI, heavy implementations, optional dependencies.
|
||||
3. Tools (PraisonAI-Tools): Specific integrations, external tools (e.g. SurrealDB, Slack), and community extensions MUST go to the `MervinPraison/PraisonAI-Tools` repository. If the feature is a tool, clone `https://github.com/MervinPraison/PraisonAI-Tools`, implement it there, and create the PR using `gh pr create -R MervinPraison/PraisonAI-Tools`.
|
||||
- Does it duplicate existing functionality? Check if Agent already supports this via existing params (reflection, planning, tools, hooks, memory).
|
||||
- Does it inherit from Agent properly? New agent types MUST inherit Agent, not wrap it with composition.
|
||||
- Does it add new dependencies? Only optional deps allowed, must be lazy-imported.
|
||||
- Will agent.py grow larger? If the change adds >50 lines to agent.py, find a way to extract instead.
|
||||
- Is there a name collision with existing exports in __init__.py?
|
||||
If ANY of these conceptual checks fail (excluding routing), add a comment to the issue explaining why and close it. Do NOT create a PR.
|
||||
|
||||
STEP 3 — IMPLEMENT:
|
||||
- Create a new git branch appropriately named (e.g. \`feature/issue-<number>\`)
|
||||
- Follow protocol-driven design: protocols in core SDK, heavy implementations in wrapper
|
||||
- Keep changes small and backward-compatible
|
||||
|
||||
STEP 4 — TEST:
|
||||
- Run: cd src/praisonai-agents && PYTHONPATH=. python -m pytest tests/ -x -q --timeout=30
|
||||
- Ensure no regressions
|
||||
|
||||
STEP 5 — CREATE PR:
|
||||
- Commit with descriptive message, push the branch
|
||||
- Use the GitHub CLI (\`gh pr create --title "..." --body "Fixes #<number>"\`) to open a Pull Request
|
||||
CRITICAL: You MUST create the PR automatically using \`gh pr create\`. Do NOT just provide a link.
|
||||
|
||||
Respond naturally and helpfully to the user's request using the available tools.
|
||||
EOF
|
||||
|
||||
echo "PROMPT_FILE=/tmp/claude-action/github-context-prompt.txt" >> $GITHUB_ENV
|
||||
echo "SKIP_EXECUTION=false" >> $GITHUB_ENV
|
||||
|
||||
- name: Run Claude Code
|
||||
if: env.SKIP_EXECUTION != 'true'
|
||||
shell: bash
|
||||
run: |
|
||||
echo "🚀 Running Claude Code with GitHub context..."
|
||||
|
||||
# Build command arguments
|
||||
CMD_ARGS=("-p" "--verbose" "--output-format" "stream-json")
|
||||
|
||||
# Add max turns if specified
|
||||
if [[ -n "${{ inputs.max_turns }}" ]]; then
|
||||
CMD_ARGS+=("--max-turns" "${{ inputs.max_turns }}")
|
||||
fi
|
||||
|
||||
# Add allowed tools (include GitHub tools by default)
|
||||
TOOLS="mcp__github__get_issue,mcp__github__get_issue_comments,mcp__github__update_issue,mcp__github__search_issues,mcp__github__list_issues,mcp__github__create_comment,Read,Write,Edit,Bash"
|
||||
if [[ -n "${{ inputs.allowed_tools }}" ]]; then
|
||||
TOOLS="$TOOLS,${{ inputs.allowed_tools }}"
|
||||
fi
|
||||
CMD_ARGS+=("--allowedTools" "$TOOLS")
|
||||
|
||||
# Add disallowed tools
|
||||
if [[ -n "${{ inputs.disallowed_tools }}" ]]; then
|
||||
CMD_ARGS+=("--disallowedTools" "${{ inputs.disallowed_tools }}")
|
||||
fi
|
||||
|
||||
echo "📝 Executing Claude Code with prompt from file..."
|
||||
|
||||
# Execute Claude Code with timeout, using stdin for the prompt
|
||||
TIMEOUT_SECONDS=$((${{ inputs.timeout_minutes }} * 60))
|
||||
timeout $TIMEOUT_SECONDS claude "${CMD_ARGS[@]}" < "${{ env.PROMPT_FILE }}"
|
||||
|
||||
echo "✅ Claude Code execution completed"
|
||||
env:
|
||||
ANTHROPIC_API_KEY: ${{ inputs.anthropic_api_key }}
|
||||
CLAUDE_CODE_OAUTH_TOKEN: ${{ inputs.claude_code_oauth_token }}
|
||||
GITHUB_TOKEN: ${{ inputs.github_token }}
|
||||
@@ -1,91 +0,0 @@
|
||||
name: "Claude Issue Triage Action"
|
||||
description: "Automatically triage GitHub issues using Claude Code"
|
||||
|
||||
inputs:
|
||||
timeout_minutes:
|
||||
description: "Timeout in minutes for execution"
|
||||
required: false
|
||||
default: "5"
|
||||
claude_code_oauth_token:
|
||||
description: "Claude Code OAuth token for Pro subscription access"
|
||||
required: true
|
||||
github_token:
|
||||
description: "GitHub token with repo and issues permissions"
|
||||
required: true
|
||||
|
||||
runs:
|
||||
using: "composite"
|
||||
steps:
|
||||
- name: Checkout repository code
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Create prompt
|
||||
id: generate_prompt
|
||||
shell: bash
|
||||
run: |
|
||||
mkdir -p /tmp/claude-prompts
|
||||
cat > /tmp/claude-prompts/claude-issue-triage-prompt.txt << 'EOF'
|
||||
You're an issue triage assistant for GitHub issues. Your task is to analyze the issue and select appropriate labels from the provided list.
|
||||
|
||||
IMPORTANT: Don't post any comments or messages to the issue. Your only action should be to apply labels.
|
||||
|
||||
Issue Information:
|
||||
- REPO: ${{ github.repository }}
|
||||
- ISSUE_NUMBER: ${{ github.event.issue.number }}
|
||||
|
||||
TASK OVERVIEW:
|
||||
|
||||
1. First, fetch the list of labels available in this repository by running: `gh label list`. Run exactly this command with nothing else.
|
||||
|
||||
2. Next, use the GitHub tools to get context about the issue:
|
||||
- You have access to these tools:
|
||||
- mcp__github__get_issue: Use this to retrieve the current issue's details including title, description, and existing labels
|
||||
- mcp__github__get_issue_comments: Use this to read any discussion or additional context provided in the comments
|
||||
- mcp__github__update_issue: Use this to apply labels to the issue (do not use this for commenting)
|
||||
- mcp__github__search_issues: Use this to find similar issues that might provide context for proper categorization and to identify potential duplicate issues
|
||||
- mcp__github__list_issues: Use this to understand patterns in how other issues are labeled
|
||||
- Start by using mcp__github__get_issue to get the issue details
|
||||
|
||||
3. Analyze the issue content, considering:
|
||||
- The issue title and description
|
||||
- The type of issue (bug report, feature request, question, etc.)
|
||||
- Technical areas mentioned
|
||||
- Severity or priority indicators
|
||||
- User impact
|
||||
- Components affected
|
||||
|
||||
4. Select appropriate labels from the available labels list provided above:
|
||||
- Choose labels that accurately reflect the issue's nature
|
||||
- Be specific but comprehensive
|
||||
- Select priority labels if you can determine urgency (high-priority, med-priority, or low-priority)
|
||||
- Consider platform labels (android, ios) if applicable
|
||||
- If you find similar issues using mcp__github__search_issues, consider using a "duplicate" label if appropriate. Only do so if the issue is a duplicate of another OPEN issue.
|
||||
|
||||
5. Apply the selected labels:
|
||||
- Use mcp__github__update_issue to apply your selected labels
|
||||
- DO NOT post any comments explaining your decision
|
||||
- DO NOT communicate directly with users
|
||||
- If no labels are clearly applicable, do not apply any labels
|
||||
|
||||
IMPORTANT GUIDELINES:
|
||||
- Be thorough in your analysis
|
||||
- Only select labels from the provided list above
|
||||
- DO NOT post any comments to the issue
|
||||
- Your ONLY action should be to apply labels using mcp__github__update_issue
|
||||
- It's okay to not add any labels if none are clearly applicable
|
||||
EOF
|
||||
|
||||
echo "PROMPT<<DELIMITER" >> $GITHUB_OUTPUT
|
||||
cat /tmp/claude-prompts/claude-issue-triage-prompt.txt >> $GITHUB_OUTPUT
|
||||
echo "DELIMITER" >> $GITHUB_OUTPUT
|
||||
|
||||
- name: Run Claude Code
|
||||
uses: ./.github/actions/claude-code-action
|
||||
with:
|
||||
direct_prompt: ${{ steps.generate_prompt.outputs.PROMPT }}
|
||||
allowed_tools: "Bash(gh label list),mcp__github__get_issue,mcp__github__get_issue_comments,mcp__github__update_issue,mcp__github__search_issues,mcp__github__list_issues"
|
||||
timeout_minutes: ${{ inputs.timeout_minutes }}
|
||||
claude_code_oauth_token: ${{ inputs.claude_code_oauth_token }}
|
||||
github_token: ${{ inputs.github_token }}
|
||||
@@ -1,9 +0,0 @@
|
||||
{
|
||||
"templateRepo": "MervinPraison/github-automation-template",
|
||||
"stack": "claude",
|
||||
"profile": "sdk",
|
||||
"mode": "hub",
|
||||
"hubRef": "v1.1.11",
|
||||
"templateVersion": "1.1.7",
|
||||
"installedAt": "2026-09-07T10:02:11Z"
|
||||
}
|
||||
@@ -1,153 +0,0 @@
|
||||
/**
|
||||
* Idempotent CodeRabbit/Qodo kick for bot-opened PRs.
|
||||
* @see .github/workflows/auto-pr-comment.yml, claude.yml, bot-pr-recovery.yml
|
||||
*/
|
||||
|
||||
const KICK_AUTHORS = new Set(['MervinPraison', 'github-actions[bot]']);
|
||||
const BOT_PR_AUTHORS = new Set(['praisonai-triage-agent[bot]', 'github-actions[bot]']);
|
||||
|
||||
async function listAllComments(github, owner, repo, issueNumber) {
|
||||
if (typeof github.paginate === 'function') {
|
||||
return github.paginate(github.rest.issues.listComments, {
|
||||
owner,
|
||||
repo,
|
||||
issue_number: issueNumber,
|
||||
per_page: 100,
|
||||
});
|
||||
}
|
||||
const { data } = await github.rest.issues.listComments({
|
||||
owner,
|
||||
repo,
|
||||
issue_number: issueNumber,
|
||||
per_page: 100,
|
||||
});
|
||||
return data;
|
||||
}
|
||||
|
||||
function kickAuthored(comment, marker) {
|
||||
return (
|
||||
KICK_AUTHORS.has(comment.user?.login) &&
|
||||
(comment.body || '').includes(marker)
|
||||
);
|
||||
}
|
||||
|
||||
function coderabbitKickPosted(comments) {
|
||||
return comments.some((c) => kickAuthored(c, '@coderabbitai review'));
|
||||
}
|
||||
|
||||
function qodoKickPosted(comments) {
|
||||
return comments.some((c) => kickAuthored(c, '/review'));
|
||||
}
|
||||
|
||||
function chainKickPosted(comments) {
|
||||
return coderabbitKickPosted(comments) && qodoKickPosted(comments);
|
||||
}
|
||||
|
||||
function isBotOpenedPr(pr) {
|
||||
if (BOT_PR_AUTHORS.has(pr.user?.login)) return true;
|
||||
return pr.user?.type === 'Bot';
|
||||
}
|
||||
|
||||
async function kickReviewChain(github, owner, repo, prNumber, core, preFetchedComments = null) {
|
||||
const comments = preFetchedComments || await listAllComments(github, owner, repo, prNumber);
|
||||
const needCoderabbit = !coderabbitKickPosted(comments);
|
||||
const needQodo = !qodoKickPosted(comments);
|
||||
|
||||
if (!needCoderabbit && !needQodo) {
|
||||
core?.info?.(`Review chain already kicked on PR #${prNumber}`);
|
||||
return { kicked: false, reason: 'already_kicked' };
|
||||
}
|
||||
|
||||
if (needCoderabbit) {
|
||||
await github.rest.issues.createComment({
|
||||
owner,
|
||||
repo,
|
||||
issue_number: prNumber,
|
||||
body: '@coderabbitai review',
|
||||
});
|
||||
}
|
||||
if (needQodo) {
|
||||
await github.rest.issues.createComment({
|
||||
owner,
|
||||
repo,
|
||||
issue_number: prNumber,
|
||||
body: '/review',
|
||||
});
|
||||
}
|
||||
core?.info?.(`Kicked review chain for PR #${prNumber} (coderabbit=${needCoderabbit}, qodo=${needQodo})`);
|
||||
return { kicked: true, coderabbit: needCoderabbit, qodo: needQodo };
|
||||
}
|
||||
|
||||
async function findOpenPrForIssue(github, owner, repo, issueNumber) {
|
||||
const prefix = `claude/issue-${issueNumber}-`;
|
||||
const { data: prs } = await github.rest.pulls.list({
|
||||
owner,
|
||||
repo,
|
||||
state: 'open',
|
||||
sort: 'created',
|
||||
direction: 'desc',
|
||||
per_page: 30,
|
||||
});
|
||||
return (
|
||||
prs.find(
|
||||
(p) => (p.head?.ref || '').startsWith(prefix) && isBotOpenedPr(p)
|
||||
) || null
|
||||
);
|
||||
}
|
||||
|
||||
async function kickReviewChainForIssue(github, owner, repo, issueNumber, core) {
|
||||
const pr = await findOpenPrForIssue(github, owner, repo, issueNumber);
|
||||
if (!pr) {
|
||||
core?.info?.(`No open PR for issue #${issueNumber}, skipping review kick`);
|
||||
return { kicked: false, reason: 'no_pr' };
|
||||
}
|
||||
const result = await kickReviewChain(github, owner, repo, pr.number, core);
|
||||
return { ...result, prNumber: pr.number };
|
||||
}
|
||||
|
||||
async function recoverStalledBotPrs(github, owner, repo, options, core) {
|
||||
const { prNumber = null, minAgeMs = 10 * 60 * 1000, maxRecover = 10 } = options || {};
|
||||
let prs;
|
||||
if (prNumber) {
|
||||
const { data } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
|
||||
prs = [data];
|
||||
} else if (typeof github.paginate === 'function') {
|
||||
prs = await github.paginate(github.rest.pulls.list, {
|
||||
owner,
|
||||
repo,
|
||||
state: 'open',
|
||||
per_page: 100,
|
||||
});
|
||||
} else {
|
||||
const { data } = await github.rest.pulls.list({ owner, repo, state: 'open', per_page: 100 });
|
||||
prs = data;
|
||||
}
|
||||
|
||||
const cutoff = Date.now() - minAgeMs;
|
||||
let recovered = 0;
|
||||
for (const pr of prs) {
|
||||
if (recovered >= maxRecover) break;
|
||||
if (!isBotOpenedPr(pr)) continue;
|
||||
if (!prNumber && new Date(pr.created_at).getTime() > cutoff) continue;
|
||||
const comments = await listAllComments(github, owner, repo, pr.number);
|
||||
if (chainKickPosted(comments)) continue;
|
||||
await kickReviewChain(github, owner, repo, pr.number, core, comments);
|
||||
recovered += 1;
|
||||
}
|
||||
core?.info?.(`Recovery complete (${recovered} PR(s) kicked)`);
|
||||
return recovered;
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
KICK_AUTHORS,
|
||||
BOT_PR_AUTHORS,
|
||||
listAllComments,
|
||||
chainKickPosted,
|
||||
coderabbitKickPosted,
|
||||
qodoKickPosted,
|
||||
isBotOpenedPr,
|
||||
kickReviewChain,
|
||||
findOpenPrForIssue,
|
||||
kickReviewChainForIssue,
|
||||
recoverStalledBotPrs,
|
||||
};
|
||||
@@ -1,44 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Run: node .github/scripts/ci-failure-claude-selftest.js
|
||||
*/
|
||||
const ciFix = require('./ci-failure-claude.js');
|
||||
const mergeGate = require('./merge-gate.js');
|
||||
const config = require('./gate-config.js');
|
||||
|
||||
let failed = 0;
|
||||
function assert(name, cond) {
|
||||
if (!cond) {
|
||||
console.error('FAIL:', name);
|
||||
failed += 1;
|
||||
} else {
|
||||
console.log('ok:', name);
|
||||
}
|
||||
}
|
||||
|
||||
const LOG = `
|
||||
python UNKNOWN STEP FAILED (0.0100s) tests/unit/test_example.py::test_foo - AssertionError: bar
|
||||
python UNKNOWN STEP ##[error]Process completed with exit code 1.
|
||||
`;
|
||||
|
||||
const parsed = ciFix.parsePytestFailures(LOG);
|
||||
assert('parses pytest failure', parsed.length === 1);
|
||||
assert('uses CI workflow list', config.ciFailureWorkflowRuns.includes('CI'));
|
||||
|
||||
const comment = ciFix.buildCiFixComment({
|
||||
headSha: 'abc1234567890abcdef1234567890abcdef12',
|
||||
failedChecks: [{ name: 'python', workflow: 'CI', html_url: 'https://example.com/job/1' }],
|
||||
failureSummaries: [{ jobName: 'python', failures: parsed }],
|
||||
});
|
||||
assert('comment mentions product guardrails', comment.includes('Product guardrails'));
|
||||
|
||||
const skip = ciFix.shouldSkipCiFix({
|
||||
comments: [],
|
||||
headSha: 'abc1234567890abcdef1234567890abcdef12',
|
||||
labels: [],
|
||||
claudeInProgress: false,
|
||||
failedChecks: [{ name: 'python', workflow: 'CI' }],
|
||||
});
|
||||
assert('ci fix without FINAL review allowed', !skip.skip);
|
||||
|
||||
process.exit(failed ? 1 : 0);
|
||||
@@ -1,293 +0,0 @@
|
||||
/**
|
||||
* Post @claude comments with CI failure details for internal PRs.
|
||||
* @see .github/workflows/ci-failure-claude.yml
|
||||
*/
|
||||
|
||||
const mergeGate = require('./merge-gate.js');
|
||||
const config = require('./gate-config.js');
|
||||
|
||||
const CI_FIX_LABEL = 'claude-ci-fix-pending';
|
||||
const COOLDOWN_MS = 12 * 60 * 60 * 1000;
|
||||
const AUTO_ACTORS = mergeGate.AUTO_ACTORS;
|
||||
const MAX_FAILURES = 15;
|
||||
const MAX_JOBS_TO_FETCH = 5;
|
||||
|
||||
function shortSha(headSha) {
|
||||
return (headSha || '').slice(0, 8);
|
||||
}
|
||||
|
||||
function ciFixShaMarker(headSha) {
|
||||
return `ci failed on head \`${shortSha(headSha)}`.toLowerCase();
|
||||
}
|
||||
|
||||
function isCiFixComment(comment) {
|
||||
const body = (comment.body || '').toLowerCase();
|
||||
return body.includes('@claude') && body.includes('ci failed on head');
|
||||
}
|
||||
|
||||
function hasCiFixCommentForSha(comments, headSha) {
|
||||
const marker = shortSha(headSha).toLowerCase();
|
||||
return comments.some((c) => {
|
||||
if (!AUTO_ACTORS.includes(c.user.login)) return false;
|
||||
if (!isCiFixComment(c)) return false;
|
||||
return (c.body || '').toLowerCase().includes(marker);
|
||||
});
|
||||
}
|
||||
|
||||
function hasRecentCiFixComment(comments, headSha) {
|
||||
const cutoff = Date.now() - COOLDOWN_MS;
|
||||
const marker = shortSha(headSha).toLowerCase();
|
||||
return comments.some((c) => {
|
||||
if (!AUTO_ACTORS.includes(c.user.login)) return false;
|
||||
if (!isCiFixComment(c)) return false;
|
||||
const body = (c.body || '').toLowerCase();
|
||||
if (body.includes(marker)) return true;
|
||||
return new Date(c.created_at).getTime() > cutoff;
|
||||
});
|
||||
}
|
||||
|
||||
function shouldSkipCiFix({ comments, headSha, labels, claudeInProgress, failedChecks }) {
|
||||
if (!failedChecks.length) return { skip: true, reason: 'no failed checks' };
|
||||
if (labels.includes(CI_FIX_LABEL)) return { skip: true, reason: 'ci fix pending' };
|
||||
if (claudeInProgress) return { skip: true, reason: 'claude in progress' };
|
||||
if (hasCiFixCommentForSha(comments, headSha)) {
|
||||
return { skip: true, reason: 'already commented for this sha' };
|
||||
}
|
||||
if (hasRecentCiFixComment(comments, headSha)) {
|
||||
return { skip: true, reason: 'recent ci fix comment cooldown' };
|
||||
}
|
||||
return { skip: false };
|
||||
}
|
||||
|
||||
function parsePytestFailures(logText) {
|
||||
if (!logText) return [];
|
||||
const lines = logText.split('\n');
|
||||
const failures = [];
|
||||
const seen = new Set();
|
||||
|
||||
for (let i = lines.length - 1; i >= 0 && failures.length < MAX_FAILURES; i -= 1) {
|
||||
const line = lines[i].trim();
|
||||
if (!line) continue;
|
||||
|
||||
const pytestMatch = line.match(
|
||||
/FAILED\s*(?:\([^)]+\))?\s+(tests\/[^\s]+(?:::[^\s-]+)*)\s*-\s*(.+)/i
|
||||
);
|
||||
if (pytestMatch) {
|
||||
const testId = pytestMatch[1];
|
||||
if (!seen.has(testId)) {
|
||||
seen.add(testId);
|
||||
failures.push({ testId, error: pytestMatch[2].trim() });
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
const errorMatch = line.match(/##\[error\](.+)/);
|
||||
if (errorMatch && /tests\//.test(errorMatch[1])) {
|
||||
const msg = errorMatch[1].trim();
|
||||
if (!seen.has(msg)) {
|
||||
seen.add(msg);
|
||||
failures.push({ testId: msg, error: msg });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return failures;
|
||||
}
|
||||
|
||||
async function fetchJobFailureSummary(github, owner, repo, jobId, jobName) {
|
||||
try {
|
||||
const response = await github.rest.actions.downloadJobLogsForWorkflowRun({
|
||||
owner,
|
||||
repo,
|
||||
job_id: jobId,
|
||||
});
|
||||
let logText = typeof response.data === 'string' ? response.data : String(response.data || '');
|
||||
if (logText.length > 100000) {
|
||||
logText = logText.slice(-100000);
|
||||
}
|
||||
return { jobName, jobId, failures: parsePytestFailures(logText) };
|
||||
} catch (err) {
|
||||
return { jobName, jobId, failures: [], error: err.message };
|
||||
}
|
||||
}
|
||||
|
||||
function mapFailedChecks(runs) {
|
||||
return runs.map((run) => ({
|
||||
name: run.name,
|
||||
id: run.id,
|
||||
html_url: run.html_url || run.details_url,
|
||||
workflow: run.app?.slug || run.check_suite?.app?.slug || run.name,
|
||||
}));
|
||||
}
|
||||
|
||||
function buildCiFixComment({ headSha, failedChecks, failureSummaries }) {
|
||||
const parts = [
|
||||
`@claude CI failed on HEAD \`${shortSha(headSha)}\`. Please fix the failures below and push to this branch.`,
|
||||
'',
|
||||
'## Failed checks',
|
||||
];
|
||||
|
||||
for (const check of failedChecks) {
|
||||
parts.push(`- **${check.workflow || check.name}** / \`${check.name}\` — ${check.html_url}`);
|
||||
}
|
||||
|
||||
parts.push('', '## Failures (extracted)');
|
||||
let idx = 0;
|
||||
for (const summary of failureSummaries) {
|
||||
for (const failure of summary.failures) {
|
||||
idx += 1;
|
||||
if (idx > MAX_FAILURES) break;
|
||||
parts.push(`${idx}. \`${failure.testId}\` — \`${failure.error}\``);
|
||||
parts.push(` - Job: \`${summary.jobName}\``);
|
||||
}
|
||||
if (idx >= MAX_FAILURES) break;
|
||||
}
|
||||
|
||||
if (idx === 0) {
|
||||
parts.push('_(Could not extract pytest details — see job logs above.)_');
|
||||
}
|
||||
|
||||
const exampleTest = failureSummaries.find((s) => s.failures.length)?.failures[0]?.testId;
|
||||
parts.push(
|
||||
'',
|
||||
'## Critical review first',
|
||||
'Before changing code or tests, decide **which side is wrong**:',
|
||||
'1. **Legitimate feature change** — the PR intent is correct but implementation or tests need updating. Preserve product guarantees; update tests only when behaviour intentionally changed and document why.',
|
||||
'2. **Regression / bug in this PR** — the failure exposes a real breakage introduced here. Fix the implementation; **do not weaken, skip, or delete tests** just to go green.',
|
||||
'3. **Pre-existing flake or unrelated failure** — say so explicitly; prefer fixing the root cause over masking it.',
|
||||
'',
|
||||
'**Product guardrails (AGENTS.md):**',
|
||||
'- Do not disturb PraisonAIUI contracts or frontend/backend layering to accommodate scope creep.',
|
||||
'- Core agent runtime belongs in praisonaiagents; agent-callable tools belong in PraisonAI-Tools — not here.',
|
||||
'- Prefer existing YAML config, plugins, and feature modules over new server.py/create_app() params or knobs with no live consumer.',
|
||||
'- Tests must continue to guard backward compatibility and UX behaviour — passing CI by lowering test standards is not acceptable.',
|
||||
'- If the feature does not genuinely add product value, recommend reverting or narrowing scope instead of patching around failures.',
|
||||
'',
|
||||
'## What to do',
|
||||
'1. State your verdict: **legitimate fix**, **regression fix**, or **needs human review** — and why (1–3 sentences).',
|
||||
'2. Fix root cause with **minimal changes**; never bloat server.py or create_app() with extra params.',
|
||||
exampleTest
|
||||
? `3. Run failing tests locally, e.g. \`pytest ${exampleTest} -q\`, plus any related tests touched by the PR.`
|
||||
: '3. Run failing tests locally with targeted pytest, plus any related tests touched by the PR.',
|
||||
'4. Push to this branch and comment: files changed, review verdict, and why tests still protect product behaviour.',
|
||||
);
|
||||
|
||||
return parts.join('\n');
|
||||
}
|
||||
|
||||
async function maybeClearCiFixLabel(github, owner, repo, prNumber, labels, headSha, core) {
|
||||
if (!labels.includes(CI_FIX_LABEL)) return false;
|
||||
const ciGreen = await mergeGate.allChecksGreenOnSha(github, owner, repo, headSha, core);
|
||||
if (!ciGreen) return false;
|
||||
try {
|
||||
await github.rest.issues.removeLabel({
|
||||
owner,
|
||||
repo,
|
||||
issue_number: prNumber,
|
||||
name: CI_FIX_LABEL,
|
||||
});
|
||||
core?.info?.(`Removed ${CI_FIX_LABEL} from PR #${prNumber}`);
|
||||
} catch (err) {
|
||||
if (err.status !== 404) throw err;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
async function maybeTriggerCiFixClaude(github, owner, repo, prNumber, core, opts = {}) {
|
||||
const baseRepo = `${owner}/${repo}`;
|
||||
const ctx = await mergeGate.loadPrContext(github, owner, repo, prNumber);
|
||||
const pr = ctx.pr;
|
||||
|
||||
if (pr.state !== 'open') return { skipped: true, reason: 'not open' };
|
||||
if (pr.draft) return { skipped: true, reason: 'draft' };
|
||||
|
||||
const headRepo = pr.head.repo?.full_name;
|
||||
if (headRepo && headRepo !== baseRepo && !pr.maintainer_can_modify) {
|
||||
return { skipped: true, reason: 'fork without maintainer edits' };
|
||||
}
|
||||
|
||||
const headSha = pr.head.sha;
|
||||
const labels = ctx.labels;
|
||||
|
||||
if (await maybeClearCiFixLabel(github, owner, repo, prNumber, labels, headSha, core)) {
|
||||
return { skipped: true, reason: 'ci green, label cleared' };
|
||||
}
|
||||
|
||||
const ciGreen = await mergeGate.allChecksGreenOnSha(github, owner, repo, headSha, core);
|
||||
if (ciGreen) return { skipped: true, reason: 'ci green' };
|
||||
|
||||
const runs = await mergeGate.listChecksOnSha(github, owner, repo, headSha);
|
||||
const failedRuns = mergeGate.listFailedChecksOnSha(runs);
|
||||
if (failedRuns.length === 0) {
|
||||
return { skipped: true, reason: 'no failed checks yet (may be pending)' };
|
||||
}
|
||||
|
||||
const claudeInProgress = await mergeGate.hasInProgressClaudeAssistant(
|
||||
github, owner, repo, prNumber
|
||||
);
|
||||
const skip = shouldSkipCiFix({
|
||||
comments: ctx.comments,
|
||||
headSha,
|
||||
labels,
|
||||
claudeInProgress,
|
||||
failedChecks: failedRuns,
|
||||
});
|
||||
if (skip.skip) return { skipped: true, reason: skip.reason };
|
||||
|
||||
const failedChecks = mapFailedChecks(failedRuns);
|
||||
const failureSummaries = [];
|
||||
for (const check of failedChecks.slice(0, MAX_JOBS_TO_FETCH)) {
|
||||
failureSummaries.push(
|
||||
await fetchJobFailureSummary(github, owner, repo, check.id, check.name)
|
||||
);
|
||||
}
|
||||
|
||||
const body = buildCiFixComment({ headSha, failedChecks, failureSummaries });
|
||||
|
||||
await github.rest.issues.addLabels({
|
||||
owner,
|
||||
repo,
|
||||
issue_number: prNumber,
|
||||
labels: [CI_FIX_LABEL],
|
||||
});
|
||||
await github.rest.issues.createComment({
|
||||
owner,
|
||||
repo,
|
||||
issue_number: prNumber,
|
||||
body,
|
||||
});
|
||||
|
||||
core?.info?.(`Posted CI fix @claude on PR #${prNumber} (${shortSha(headSha)})`);
|
||||
return { triggered: true, headSha: shortSha(headSha) };
|
||||
}
|
||||
|
||||
async function processWorkflowRunFailure(github, owner, repo, workflowRun, core) {
|
||||
if (workflowRun.conclusion !== 'failure') {
|
||||
return { skipped: true, reason: `conclusion=${workflowRun.conclusion}` };
|
||||
}
|
||||
const allowed = config.ciFailureWorkflowRuns;
|
||||
if (!allowed.includes(workflowRun.name)) {
|
||||
return { skipped: true, reason: `workflow ${workflowRun.name}` };
|
||||
}
|
||||
const prNumber = await mergeGate.resolvePrNumberFromWorkflowRun(
|
||||
github, owner, repo, workflowRun
|
||||
);
|
||||
if (!prNumber) return { skipped: true, reason: 'no linked PR' };
|
||||
return maybeTriggerCiFixClaude(github, owner, repo, prNumber, core);
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
CI_FIX_LABEL,
|
||||
COOLDOWN_MS,
|
||||
ciFixShaMarker,
|
||||
isCiFixComment,
|
||||
hasCiFixCommentForSha,
|
||||
hasRecentCiFixComment,
|
||||
shouldSkipCiFix,
|
||||
parsePytestFailures,
|
||||
fetchJobFailureSummary,
|
||||
buildCiFixComment,
|
||||
maybeClearCiFixLabel,
|
||||
maybeTriggerCiFixClaude,
|
||||
processWorkflowRunFailure,
|
||||
};
|
||||
@@ -1,55 +0,0 @@
|
||||
/**
|
||||
* PraisonAIUI gate configuration — imported by merge-gate, release-gate, ci-failure-claude.
|
||||
*/
|
||||
|
||||
module.exports = {
|
||||
repoFullName: 'MervinPraison/PraisonAIUI',
|
||||
gitUser: 'MervinPraison',
|
||||
gitEmail: '[email protected]',
|
||||
triggerLogins: ['MervinPraison', 'github-actions[bot]'],
|
||||
allowedTriageBots: ['praisonai-triage-agent[bot]'],
|
||||
productPathPrefixes: ['src/praisonaiui/', 'src/frontend/', 'tests/'],
|
||||
sensitivePathPatterns: [
|
||||
/^\.github\/workflows\//,
|
||||
/^pyproject\.toml$/,
|
||||
/credentials\.json$/i,
|
||||
],
|
||||
requiredCheckPatterns: [/^ci$/i, /python/i, /test/i, /lint/i, /ruff/i],
|
||||
ciWorkflowFile: 'ci.yml',
|
||||
ciWorkflowName: 'CI',
|
||||
mergeGateWorkflowRuns: ['CI', 'Claude Assistant'],
|
||||
ciFailureWorkflowRuns: ['CI'],
|
||||
pypiPackageName: 'aiui',
|
||||
packagePaths: ['src/praisonaiui', 'src/frontend', 'pyproject.toml'],
|
||||
finalClaudeScope:
|
||||
'SCOPE: Focus ONLY on PraisonAIUI (src/praisonaiui, src/frontend, tests, docs). '
|
||||
+ 'Do NOT expand into praisonaiagents or the monorepo unless the PR explicitly requires it.',
|
||||
finalClaudeProductValue:
|
||||
'4. Product value: review in depth whether the change genuinely adds PraisonAIUI UX value — '
|
||||
+ 'never add features for the sake of adding them. It must strengthen the UI (simpler, '
|
||||
+ 'more user-friendly, robust). If it does not clearly add value, request changes or recommend '
|
||||
+ 'rejecting/closing rather than merging scope creep.\n'
|
||||
+ '5. Layering: UI/frontend/server features here; core agent runtime belongs in praisonaiagents '
|
||||
+ '(PraisonAI monorepo). Agent-callable tools → PraisonAI-Tools. Do not pull monorepo or SDK '
|
||||
+ 'scope into this repo unless the PR explicitly requires it.\n'
|
||||
+ '6. Do not bloat server.py or create_app() with new params — prefer existing YAML config, '
|
||||
+ 'plugins, and feature modules; only add params if absolutely required. Reject knobs/exports '
|
||||
+ 'with no live consumer.',
|
||||
mergeGateProductValue:
|
||||
'Confirm product value gate: change strengthens PraisonAIUI UX (no scope creep). The aim is a '
|
||||
+ 'LIGHTWEIGHT AND POWERFUL package — BLOCK changes that add params/modules/exports duplicating '
|
||||
+ 'existing UI capabilities (YAML config, plugins, feature modules, existing server hooks), or '
|
||||
+ 'add knobs/fields with no live consumer, i.e. scope creep for the sake of it.',
|
||||
mergeGateLayering:
|
||||
'Layering routing: BLOCK if core agent logic was added here instead of praisonaiagents; BLOCK if '
|
||||
+ 'agent-callable tools were added here instead of PraisonAI-Tools.',
|
||||
mergeGateServerBloat:
|
||||
'Do not bloat server.py or create_app() with additional params — only if absolutely required; '
|
||||
+ 'prefer existing config/plugin patterns.',
|
||||
agentPyChecks: false,
|
||||
reviewBotLogins: [
|
||||
'coderabbitai[bot]',
|
||||
'qodo-code-review[bot]',
|
||||
'greptile-apps[bot]',
|
||||
],
|
||||
};
|
||||
@@ -1,234 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Local self-test for merge-gate.js heuristics (no GitHub API).
|
||||
* Run: node .github/scripts/merge-gate-selftest.js
|
||||
*/
|
||||
const mg = require('./merge-gate.js');
|
||||
|
||||
let failed = 0;
|
||||
function assert(name, cond) {
|
||||
if (!cond) {
|
||||
console.error('FAIL:', name);
|
||||
failed++;
|
||||
} else {
|
||||
console.log('ok:', name);
|
||||
}
|
||||
}
|
||||
|
||||
// Stale FINAL: push after FINAL, no @claude since head
|
||||
const finals = [
|
||||
{ user: { login: 'github-actions[bot]' }, body: '@claude FINAL architecture reviewer', created_at: '2026-06-12T08:00:00Z' },
|
||||
];
|
||||
assert('stale when head after final', mg.isStaleFinalAfterPush(finals, '2026-06-12T09:00:00Z'));
|
||||
|
||||
const withRecovery = [
|
||||
...finals,
|
||||
{ user: { login: 'github-actions[bot]' }, body: '@claude FINAL architecture reviewer', created_at: '2026-06-12T09:30:00Z' },
|
||||
];
|
||||
assert('not stale when @claude after head', !mg.isStaleFinalAfterPush(withRecovery, '2026-06-12T09:00:00Z'));
|
||||
|
||||
const withClaudeReply = [
|
||||
...finals,
|
||||
{
|
||||
user: { login: 'praisonai-triage-agent[bot]' },
|
||||
body: "**Claude finished @MervinPraison's task** —— [View job](https://github.com/)",
|
||||
created_at: '2026-06-12T08:30:00Z',
|
||||
},
|
||||
];
|
||||
assert('not stale when Claude replied after FINAL', !mg.isStaleFinalAfterPush(withClaudeReply, '2026-06-12T09:00:00Z'));
|
||||
assert('claude final reply detected', mg.isClaudeFinalReplyComment(withClaudeReply[1]));
|
||||
|
||||
assert('cancelled detect-and-trigger does not block', mg.OPTIONAL_CANCELLED_CHECKS.has('detect-and-trigger'));
|
||||
|
||||
// Stale-FINAL recovery guards (PR #2560 push loop)
|
||||
const nowMs = Date.now();
|
||||
const iso = (ms) => new Date(ms).toISOString();
|
||||
const firstFinal = {
|
||||
user: { login: 'MervinPraison' },
|
||||
body: '@claude You are the FINAL architecture reviewer.',
|
||||
created_at: iso(nowMs - 20 * 60 * 1000),
|
||||
};
|
||||
const pushSoonAfter = mg.shouldSkipStaleFinalRecovery(
|
||||
[firstFinal],
|
||||
iso(nowMs - 16 * 60 * 1000)
|
||||
);
|
||||
assert('debounce push soon after FINAL', pushSoonAfter.skip && pushSoonAfter.reason.includes('soon after'));
|
||||
|
||||
const secondFinal = {
|
||||
user: { login: 'MervinPraison' },
|
||||
body: '@claude You are the FINAL architecture reviewer.',
|
||||
created_at: iso(nowMs - 20 * 60 * 1000),
|
||||
};
|
||||
const capped = mg.shouldSkipStaleFinalRecovery(
|
||||
[firstFinal, secondFinal],
|
||||
iso(nowMs - 2 * 60 * 1000)
|
||||
);
|
||||
assert('hourly cap blocks third FINAL in window', capped.skip && capped.reason.includes('capped'));
|
||||
|
||||
const botPush = mg.shouldSkipStaleFinalRecovery(
|
||||
[firstFinal],
|
||||
iso(nowMs - 16 * 60 * 1000),
|
||||
'praisonai-triage-agent[bot]'
|
||||
);
|
||||
assert('skip when automation pushed head', botPush.skip && botPush.reason.includes('automation'));
|
||||
|
||||
assert('claude automation login', mg.isClaudeAutomationLogin('praisonai-triage-agent[bot]'));
|
||||
|
||||
// Bot CHANGES_REQUESTED then APPROVE
|
||||
const reviews = [
|
||||
{ user: { login: 'coderabbit[bot]', type: 'Bot' }, state: 'CHANGES_REQUESTED', submitted_at: '2026-06-12T08:00:00Z' },
|
||||
{ user: { login: 'coderabbit[bot]', type: 'Bot' }, state: 'APPROVED', submitted_at: '2026-06-12T09:00:00Z' },
|
||||
];
|
||||
assert('bot approve clears CR', !mg.hasAnyChangesRequested(reviews));
|
||||
assert('human CR blocks', mg.hasAnyChangesRequested([
|
||||
{ user: { login: 'MervinPraison', type: 'User' }, state: 'CHANGES_REQUESTED', submitted_at: '2026-06-12T09:00:00Z' },
|
||||
]));
|
||||
|
||||
// Verdict after HEAD
|
||||
const verdictComments = [
|
||||
{ body: 'MERGE_GATE_VERDICT: APPROVE', created_at: '2026-06-12T08:00:00Z' },
|
||||
];
|
||||
assert('verdict before head rejected', mg.findMergeGateVerdict(verdictComments, null, '2026-06-12T09:00:00Z') === null);
|
||||
assert('verdict after head accepted', mg.findMergeGateVerdict(
|
||||
[{ body: 'MERGE_GATE_VERDICT: APPROVE', created_at: '2026-06-12T10:00:00Z' }],
|
||||
null,
|
||||
'2026-06-12T09:00:00Z'
|
||||
) === 'APPROVE');
|
||||
|
||||
const fallbackApprove = [
|
||||
{
|
||||
body: 'MERGE_GATE_VERDICT: APPROVE\n\nAutomated fallback — Claude assess did not post a verdict comment.',
|
||||
created_at: '2026-06-12T10:00:00Z',
|
||||
},
|
||||
];
|
||||
assert(
|
||||
'automated fallback APPROVE ignored when Opus required',
|
||||
mg.findMergeGateVerdict(fallbackApprove, null, '2026-06-12T09:00:00Z', { excludeAutomatedFallback: true }) === null
|
||||
);
|
||||
assert(
|
||||
'automated fallback APPROVE still visible without Opus-only filter',
|
||||
mg.findMergeGateVerdict(fallbackApprove, null, '2026-06-12T09:00:00Z') === 'APPROVE'
|
||||
);
|
||||
|
||||
const fallbackBlockNewFormat = [
|
||||
{
|
||||
body: 'MERGE_GATE_VERDICT: BLOCK\n\nAutomated fallback — Opus merge gate assessment did not complete.',
|
||||
created_at: '2026-06-12T10:00:00Z',
|
||||
},
|
||||
];
|
||||
assert(
|
||||
'new-format fallback BLOCK ignored when Opus required',
|
||||
mg.findMergeGateVerdict(fallbackBlockNewFormat, null, '2026-06-12T09:00:00Z', { excludeAutomatedFallback: true }) === null
|
||||
);
|
||||
assert(
|
||||
'new-format fallback BLOCK detected by marker helper',
|
||||
mg.isAutomatedFallbackVerdict(fallbackBlockNewFormat[0].body)
|
||||
);
|
||||
assert(
|
||||
'findMergeGateVerdict null-safe with explicit null options',
|
||||
mg.findMergeGateVerdict(fallbackApprove, null, '2026-06-12T09:00:00Z', null) === 'APPROVE'
|
||||
);
|
||||
|
||||
const noise = [{ user: { login: 'MervinPraison' }, body: '**Merge gate scan** — wait for `@claude`', created_at: new Date().toISOString() }];
|
||||
assert('diagnostic comment not a trigger', !mg.hasRecentClaudeTrigger(noise, 35));
|
||||
|
||||
// Cooldown skip requires an actual verdict on HEAD, not just a FINAL trigger comment
|
||||
const recentFinalOnHead = [
|
||||
{
|
||||
user: { login: 'MervinPraison' },
|
||||
body: '@claude You are the FINAL architecture reviewer.',
|
||||
created_at: '2026-06-27T10:00:00Z',
|
||||
},
|
||||
];
|
||||
assert(
|
||||
'final trigger alone does not count as verdict on head',
|
||||
mg.findMergeGateVerdict(recentFinalOnHead, null, '2026-06-27T09:55:00Z') === null
|
||||
);
|
||||
const recentVerdictOnHead = [
|
||||
...recentFinalOnHead,
|
||||
{
|
||||
user: { login: 'github-actions[bot]' },
|
||||
body: 'MERGE_GATE_VERDICT: APPROVE',
|
||||
created_at: '2026-06-27T10:05:00Z',
|
||||
},
|
||||
];
|
||||
assert(
|
||||
'verdict on head skips cooldown gate',
|
||||
mg.findMergeGateVerdict(recentVerdictOnHead, null, '2026-06-27T09:55:00Z') === 'APPROVE'
|
||||
);
|
||||
|
||||
// Sensitive + secrets
|
||||
assert('workflow path sensitive', mg.sensitivePathReasons([{ filename: '.github/workflows/foo.yml' }]).length === 1);
|
||||
assert('ci-only label exempts workflows', mg.sensitivePathReasons(
|
||||
[{ filename: '.github/workflows/foo.yml' }],
|
||||
[mg.WORKFLOW_ONLY_LABEL]
|
||||
).length === 0);
|
||||
assert('ci-only label not exempt mixed changes', mg.sensitivePathReasons(
|
||||
[{ filename: '.github/workflows/foo.yml' }, { filename: 'src/praisonaiui/foo.py' }],
|
||||
[mg.WORKFLOW_ONLY_LABEL]
|
||||
).length === 1);
|
||||
assert('secret in patch', mg.secretScanReasons([{ filename: 'x.py', patch: '+key = "ghp_abcdefghijklmnopqrstuvwxyz1234567890"' }]).length === 1);
|
||||
|
||||
// Claude run scoping — other PR branches must not block
|
||||
assert('other branch claude does not block', !mg.hasBlockingClaudeRunForPr(
|
||||
[{ event: 'issue_comment', head_branch: 'other-branch' }],
|
||||
'my-branch'
|
||||
));
|
||||
assert('same branch claude blocks', mg.hasBlockingClaudeRunForPr(
|
||||
[{ event: 'issue_comment', head_branch: 'my-branch' }],
|
||||
'my-branch'
|
||||
));
|
||||
assert('issues event never blocks', !mg.hasBlockingClaudeRunForPr(
|
||||
[{ event: 'issues', head_branch: 'my-branch' }],
|
||||
'my-branch'
|
||||
));
|
||||
|
||||
// Conflict rebase clears after bot completion + FINAL on HEAD (within 12h cooldown)
|
||||
const conflictNowMs = Date.now();
|
||||
const conflictIso = (offsetMs) => new Date(conflictNowMs + offsetMs).toISOString();
|
||||
const conflictTrigger = {
|
||||
user: { login: 'MervinPraison' },
|
||||
body: '@claude this PR has merge conflicts with main. Please rebase',
|
||||
created_at: conflictIso(-30 * 60 * 1000),
|
||||
};
|
||||
const rebaseDone = {
|
||||
user: { login: 'praisonai-triage-agent[bot]' },
|
||||
body: 'Rebase complete — PR #2308 onto latest main',
|
||||
created_at: conflictIso(-29 * 60 * 1000),
|
||||
};
|
||||
const finalAfterRebase = {
|
||||
user: { login: 'MervinPraison' },
|
||||
body: '@claude You are the FINAL architecture reviewer.',
|
||||
created_at: conflictIso(-20 * 60 * 1000),
|
||||
};
|
||||
const headAfterRebase = conflictIso(-21 * 60 * 1000);
|
||||
const rebaseComments = [conflictTrigger, rebaseDone, finalAfterRebase];
|
||||
assert('conflict blocks before rebase done', mg.hasRecentConflictComment([conflictTrigger], headAfterRebase));
|
||||
assert('conflict clears after rebase + FINAL on HEAD', !mg.hasRecentConflictComment(rebaseComments, headAfterRebase));
|
||||
assert('conflict clears after rebase without FINAL on HEAD', !mg.hasRecentConflictComment(
|
||||
[conflictTrigger, rebaseDone],
|
||||
headAfterRebase
|
||||
));
|
||||
|
||||
// Tests heuristic
|
||||
assert('product code without tests', mg.missingTestsReason([{ filename: 'src/praisonaiui/a/b.py', additions: 3 }]) !== null);
|
||||
assert('product code with tests ok', mg.missingTestsReason([
|
||||
{ filename: 'src/praisonaiui/a/b.py', additions: 3 },
|
||||
{ filename: 'tests/test_x.py', additions: 10 },
|
||||
]) === null);
|
||||
|
||||
// PR size
|
||||
assert('large PR blocked', mg.prSizeReasons([{ additions: 900 }]).length > 0);
|
||||
|
||||
assert('internal PR link accepted', mg.isInternalPullRequestLink(
|
||||
{ base: { repo: { full_name: 'MervinPraison/PraisonAIUI' } } },
|
||||
'MervinPraison',
|
||||
'PraisonAIUI'
|
||||
));
|
||||
assert('fork sync PR link rejected', !mg.isInternalPullRequestLink(
|
||||
{ number: 21, base: { repo: { full_name: 'Milkmange/PraisonAIUI' } } },
|
||||
'MervinPraison',
|
||||
'PraisonAIUI'
|
||||
));
|
||||
|
||||
process.exit(failed ? 1 : 0);
|
||||
@@ -1,940 +0,0 @@
|
||||
/**
|
||||
* Shared merge-gate helpers for claude-merge-gate.yml
|
||||
* @see .github/workflows/claude-merge-gate.yml
|
||||
*/
|
||||
|
||||
const config = require('./gate-config.js');
|
||||
|
||||
const CLAUDE_TRIGGER_LOGINS = ['MervinPraison', 'github-actions[bot]'];
|
||||
const AUTO_ACTORS = CLAUDE_TRIGGER_LOGINS;
|
||||
const CONFLICT_COOLDOWN_MS = 12 * 60 * 60 * 1000;
|
||||
const CLAUDE_ACTIVE_MS = 35 * 60 * 1000;
|
||||
const STALE_FINAL_RECOVERY_WINDOW_MS = 60 * 60 * 1000;
|
||||
const STALE_FINAL_MAX_PER_WINDOW = 2;
|
||||
const PUSH_AFTER_FINAL_DEBOUNCE_MS = 15 * 60 * 1000;
|
||||
const ALLOWED_MERGE_STATES = new Set(['CLEAN', 'UNSTABLE']);
|
||||
const AGENT_PY_MAX_AUTO_LINES = 100;
|
||||
const PR_MAX_AUTO_ADDITIONS = 800;
|
||||
const PR_MAX_AUTO_FILES = 30;
|
||||
const MANUAL_ONLY_LABELS = new Set(['security', 'breaking-change', 'needs-manual-review', 'release']);
|
||||
const WORKFLOW_ONLY_LABEL = 'merge-gate-ci-only';
|
||||
const CI_ONLY_PATH_PREFIXES = ['.github/workflows/', '.github/actions/', '.github/scripts/merge-gate'];
|
||||
const SDK_PATH_PREFIXES = config.productPathPrefixes;
|
||||
const SENSITIVE_PATH_PATTERNS = config.sensitivePathPatterns;
|
||||
const REQUIRED_SDK_CHECK_PATTERNS = config.requiredCheckPatterns;
|
||||
const SECRET_PATTERNS = [
|
||||
/sk-[a-zA-Z0-9]{20,}/,
|
||||
/AKIA[0-9A-Z]{16}/,
|
||||
/ghp_[a-zA-Z0-9]{36,}/,
|
||||
/github_pat_/,
|
||||
/Bearer eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+/,
|
||||
/-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----/,
|
||||
];
|
||||
const BLOCK_LABELS = new Set([
|
||||
'claude-conflict-pending',
|
||||
'claude-merge-gate-active',
|
||||
'no-auto-merge',
|
||||
'auto-merged-by-gate',
|
||||
]);
|
||||
const MERGE_READY_LABEL = 'pipeline/merge-ready';
|
||||
/** Superseded concurrency runs; must not block merge when real tests passed. */
|
||||
const OPTIONAL_CANCELLED_CHECKS = new Set(['detect-and-trigger']);
|
||||
const BOT_REVIEWER_PATTERNS = [
|
||||
'coderabbit',
|
||||
'qodo',
|
||||
'gemini',
|
||||
'copilot',
|
||||
'greptile',
|
||||
];
|
||||
|
||||
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
|
||||
|
||||
function isFinalClaudeTriggerComment(c) {
|
||||
const body = (c.body || '').toLowerCase();
|
||||
if (!AUTO_ACTORS.includes(c.user.login)) return false;
|
||||
if (!body.includes('@claude')) return false;
|
||||
if (body.includes('merge conflict')) return false;
|
||||
return body.includes('final architecture reviewer') || body.includes('lead engineer');
|
||||
}
|
||||
|
||||
function isClaudeTriggerNoise(c) {
|
||||
const body = c.body || '';
|
||||
if (body.includes('Merge gate scan')) return true;
|
||||
if (body.includes('MERGE_GATE_VERDICT')) return true;
|
||||
if (body.includes('Merged by **Claude PR merge gate**')) return true;
|
||||
return false;
|
||||
}
|
||||
|
||||
function isClaudeFinalReplyComment(c) {
|
||||
const login = (c.user?.login || '').toLowerCase();
|
||||
const fromAutomation =
|
||||
login.includes('praisonai-triage') ||
|
||||
login.includes('github-actions') ||
|
||||
AUTO_ACTORS.some((a) => a.toLowerCase() === login);
|
||||
if (!fromAutomation) return false;
|
||||
return (c.body || '').includes('Claude finished');
|
||||
}
|
||||
|
||||
function hasRecentClaudeTrigger(comments, minutes = 35) {
|
||||
const cutoff = Date.now() - minutes * 60 * 1000;
|
||||
return comments.some((c) => {
|
||||
if (!CLAUDE_TRIGGER_LOGINS.includes(c.user.login)) return false;
|
||||
if (isClaudeTriggerNoise(c)) return false;
|
||||
if (!(c.body || '').includes('@claude')) return false;
|
||||
return new Date(c.created_at).getTime() > cutoff;
|
||||
});
|
||||
}
|
||||
|
||||
function isConflictRebaseTriggerComment(c) {
|
||||
if (!AUTO_ACTORS.includes(c.user.login)) return false;
|
||||
const body = (c.body || '').toLowerCase();
|
||||
return body.includes('@claude') && body.includes('merge conflict');
|
||||
}
|
||||
|
||||
function isConflictRebaseCompletionComment(c) {
|
||||
const login = (c.user?.login || '').toLowerCase();
|
||||
const fromAutomation =
|
||||
login.includes('praisonai-triage') ||
|
||||
login.includes('github-actions') ||
|
||||
AUTO_ACTORS.some((a) => a.toLowerCase() === login);
|
||||
if (!fromAutomation) return false;
|
||||
const body = (c.body || '').toLowerCase();
|
||||
return (
|
||||
body.includes('rebase complete') ||
|
||||
body.includes('rebase onto') ||
|
||||
body.includes('force-pushed') ||
|
||||
(body.includes('conflict') && body.includes('resolved'))
|
||||
);
|
||||
}
|
||||
|
||||
/** HEAD landed after conflict rebase but no FINAL @claude since that push. */
|
||||
function needsFinalReReviewAfterConflictRebase(comments, headPushedAt) {
|
||||
if (!headPushedAt) return false;
|
||||
const headTime = new Date(headPushedAt).getTime();
|
||||
const conflictTriggers = comments.filter(isConflictRebaseTriggerComment);
|
||||
if (conflictTriggers.length === 0) return false;
|
||||
|
||||
const latestConflict = conflictTriggers.reduce((a, b) =>
|
||||
new Date(a.created_at) > new Date(b.created_at) ? a : b
|
||||
);
|
||||
const conflictTime = new Date(latestConflict.created_at).getTime();
|
||||
if (headTime <= conflictTime) return false;
|
||||
|
||||
const rebaseDone = comments.some(
|
||||
(c) =>
|
||||
new Date(c.created_at).getTime() > conflictTime && isConflictRebaseCompletionComment(c)
|
||||
);
|
||||
if (!rebaseDone) return false;
|
||||
|
||||
const finalsAfterHead = comments.filter(
|
||||
(c) =>
|
||||
isFinalClaudeTriggerComment(c) &&
|
||||
new Date(c.created_at).getTime() >= headTime - 60000
|
||||
);
|
||||
return finalsAfterHead.length === 0;
|
||||
}
|
||||
|
||||
function conflictRebaseQuiescent(comments, headPushedAt) {
|
||||
const conflictTriggers = comments.filter(isConflictRebaseTriggerComment);
|
||||
if (conflictTriggers.length === 0) return true;
|
||||
|
||||
const latestConflict = conflictTriggers.reduce((a, b) =>
|
||||
new Date(a.created_at) > new Date(b.created_at) ? a : b
|
||||
);
|
||||
const conflictTime = new Date(latestConflict.created_at).getTime();
|
||||
|
||||
const rebaseDone = comments.some(
|
||||
(c) =>
|
||||
new Date(c.created_at).getTime() > conflictTime && isConflictRebaseCompletionComment(c)
|
||||
);
|
||||
if (!rebaseDone) return false;
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
function hasRecentConflictComment(comments, headPushedAt = null) {
|
||||
const cutoff = Date.now() - CONFLICT_COOLDOWN_MS;
|
||||
const hasRecentTrigger = comments.some((c) => {
|
||||
if (!isConflictRebaseTriggerComment(c)) return false;
|
||||
return new Date(c.created_at).getTime() > cutoff;
|
||||
});
|
||||
if (!hasRecentTrigger) return false;
|
||||
|
||||
if (headPushedAt && conflictRebaseQuiescent(comments, headPushedAt)) {
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
function isBotReviewer(login, userType) {
|
||||
const lower = (login || '').toLowerCase();
|
||||
if (userType === 'Bot') return true;
|
||||
if (lower.endsWith('[bot]')) return true;
|
||||
return ['coderabbit', 'qodo', 'gemini', 'copilot', 'greptile'].some((p) => lower.includes(p));
|
||||
}
|
||||
|
||||
function latestReviewsByUser(reviews) {
|
||||
const latestByUser = new Map();
|
||||
for (const r of reviews) {
|
||||
const login = r.user?.login;
|
||||
if (!login) continue;
|
||||
const prev = latestByUser.get(login);
|
||||
if (!prev || new Date(r.submitted_at) > new Date(prev.submitted_at)) {
|
||||
latestByUser.set(login, r);
|
||||
}
|
||||
}
|
||||
return latestByUser;
|
||||
}
|
||||
|
||||
function hasHumanChangesRequested(reviews) {
|
||||
for (const [login, review] of latestReviewsByUser(reviews)) {
|
||||
if (review.state !== 'CHANGES_REQUESTED') continue;
|
||||
if (!isBotReviewer(login, review.user?.type)) return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
function hasAnyChangesRequested(reviews) {
|
||||
for (const [, review] of latestReviewsByUser(reviews)) {
|
||||
if (review.state === 'CHANGES_REQUESTED') return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
function hasFinalClaudeReviewTrigger(comments) {
|
||||
return comments.some(isFinalClaudeTriggerComment);
|
||||
}
|
||||
|
||||
function isStaleFinalAfterPush(comments, headPushedAt) {
|
||||
if (!headPushedAt) return false;
|
||||
const headTime = new Date(headPushedAt).getTime();
|
||||
const finals = comments.filter(isFinalClaudeTriggerComment);
|
||||
if (finals.length === 0) return true;
|
||||
const latestFinal = finals.reduce((a, b) =>
|
||||
new Date(a.created_at) > new Date(b.created_at) ? a : b
|
||||
);
|
||||
const finalTime = new Date(latestFinal.created_at).getTime();
|
||||
if (headTime <= finalTime + 60000) return false;
|
||||
const claudeRepliedAfterFinal = comments.some((c) => {
|
||||
if (!isClaudeFinalReplyComment(c)) return false;
|
||||
return new Date(c.created_at).getTime() >= finalTime - 60000;
|
||||
});
|
||||
if (claudeRepliedAfterFinal) return false;
|
||||
const claudeSinceHead = comments.some((c) => {
|
||||
if (!CLAUDE_TRIGGER_LOGINS.includes(c.user.login)) return false;
|
||||
if (isClaudeTriggerNoise(c)) return false;
|
||||
if (!(c.body || '').includes('@claude')) return false;
|
||||
return new Date(c.created_at).getTime() >= headTime - 60000;
|
||||
});
|
||||
return !claudeSinceHead;
|
||||
}
|
||||
|
||||
function needsStaleFinalRecovery(comments, headPushedAt) {
|
||||
return (
|
||||
hasFinalClaudeReviewTrigger(comments) &&
|
||||
isStaleFinalAfterPush(comments, headPushedAt)
|
||||
);
|
||||
}
|
||||
|
||||
function shouldSkipFinalRecovery(comments, headPushedAt) {
|
||||
const isStale = isStaleFinalAfterPush(comments, headPushedAt);
|
||||
if (isStale) return false;
|
||||
return hasRecentClaudeTrigger(comments, 35);
|
||||
}
|
||||
|
||||
function countFinalTriggersSince(comments, sinceMs) {
|
||||
return comments.filter(
|
||||
(c) => isFinalClaudeTriggerComment(c) && new Date(c.created_at).getTime() > sinceMs
|
||||
).length;
|
||||
}
|
||||
|
||||
function isClaudeAutomationLogin(login) {
|
||||
const lower = (login || '').toLowerCase();
|
||||
return lower.includes('praisonai-triage') || lower === 'github-actions[bot]';
|
||||
}
|
||||
|
||||
function isPushSoonAfterLatestFinal(comments, headPushedAt) {
|
||||
if (!headPushedAt) return false;
|
||||
const finals = comments.filter(isFinalClaudeTriggerComment);
|
||||
if (finals.length === 0) return false;
|
||||
const latestFinal = finals.reduce((a, b) =>
|
||||
new Date(a.created_at) > new Date(b.created_at) ? a : b
|
||||
);
|
||||
const finalTime = new Date(latestFinal.created_at).getTime();
|
||||
const headTime = new Date(headPushedAt).getTime();
|
||||
if (headTime <= finalTime) return false;
|
||||
return headTime - finalTime < PUSH_AFTER_FINAL_DEBOUNCE_MS;
|
||||
}
|
||||
|
||||
/** Returns { skip: true, reason } when stale-FINAL recovery should not post. */
|
||||
function shouldSkipStaleFinalRecovery(comments, headPushedAt, headPusherLogin = null) {
|
||||
if (!isStaleFinalAfterPush(comments, headPushedAt)) {
|
||||
return { skip: true, reason: 'not stale' };
|
||||
}
|
||||
if (headPusherLogin && isClaudeAutomationLogin(headPusherLogin)) {
|
||||
return { skip: true, reason: 'head pushed by Claude automation' };
|
||||
}
|
||||
if (needsFinalReReviewAfterConflictRebase(comments, headPushedAt)) {
|
||||
return { skip: false, reason: '' };
|
||||
}
|
||||
if (isPushSoonAfterLatestFinal(comments, headPushedAt)) {
|
||||
return {
|
||||
skip: true,
|
||||
reason: 'head pushed soon after FINAL (wait for CI / batched fixes)',
|
||||
};
|
||||
}
|
||||
const windowStart = Date.now() - STALE_FINAL_RECOVERY_WINDOW_MS;
|
||||
const finalsInWindow = countFinalTriggersSince(comments, windowStart);
|
||||
if (finalsInWindow >= STALE_FINAL_MAX_PER_WINDOW) {
|
||||
return {
|
||||
skip: true,
|
||||
reason: `stale-FINAL capped (${finalsInWindow} FINAL triggers in last hour)`,
|
||||
};
|
||||
}
|
||||
return { skip: false, reason: '' };
|
||||
}
|
||||
|
||||
function finalClaudeCompletedOnSha(comments, headPushedAt) {
|
||||
if (!hasFinalClaudeReviewTrigger(comments)) return false;
|
||||
if (isStaleFinalAfterPush(comments, headPushedAt)) return false;
|
||||
return true;
|
||||
}
|
||||
|
||||
const FINAL_CLAUDE_REVIEW_BODY =
|
||||
`@claude You are the FINAL architecture reviewer. If the branch is under ${config.repoFullName} (not a fork), you are able to make modifications to this branch and push directly. ${config.finalClaudeScope} Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.\n\n**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: check heavy implementations vs core SDK\n2. Backward compatible: ensure zero feature regressions\n3. Performance: no hot-path regressions (lazy imports, import-time <200ms)\n${config.finalClaudeProductValue}\n\n**Phase 2: FIX Valid Issues**\n5. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n6. Push all code fixes directly to THIS branch (do NOT create a new PR)\n7. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n8. If all issues are resolved, approve the PR / close the Issue\n9. If blocking issues remain, request changes / leave clear action items`;
|
||||
|
||||
async function getMergeState(github, owner, repo, prNumber) {
|
||||
const query = `
|
||||
query($owner: String!, $repo: String!, $number: Int!) {
|
||||
repository(owner: $owner, name: $repo) {
|
||||
pullRequest(number: $number) {
|
||||
mergeStateStatus
|
||||
maintainerCanModify
|
||||
isDraft
|
||||
headRefOid
|
||||
headRef { repository { nameWithOwner } }
|
||||
}
|
||||
}
|
||||
}
|
||||
`;
|
||||
for (let attempt = 0; attempt < 3; attempt++) {
|
||||
const result = await github.graphql(query, { owner, repo, number: prNumber });
|
||||
const prGql = result.repository.pullRequest;
|
||||
const status = (prGql?.mergeStateStatus || '').toUpperCase();
|
||||
if (status && status !== 'UNKNOWN') {
|
||||
return {
|
||||
status,
|
||||
isDraft: prGql.isDraft,
|
||||
headRepo: prGql.headRef?.repository?.nameWithOwner,
|
||||
headSha: prGql.headRefOid,
|
||||
maintainerCanModify: prGql.maintainerCanModify === true,
|
||||
};
|
||||
}
|
||||
if (attempt < 2) await sleep(10000);
|
||||
}
|
||||
const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
|
||||
return {
|
||||
status: (pr.mergeable_state || '').toUpperCase(),
|
||||
isDraft: pr.draft,
|
||||
headRepo: pr.head.repo?.full_name,
|
||||
headSha: pr.head.sha,
|
||||
maintainerCanModify: pr.maintainer_can_modify === true,
|
||||
};
|
||||
}
|
||||
|
||||
async function listChecksOnSha(github, owner, repo, sha) {
|
||||
const { data } = await github.rest.checks.listForRef({
|
||||
owner,
|
||||
repo,
|
||||
ref: sha,
|
||||
per_page: 100,
|
||||
});
|
||||
return (data.check_runs || []).filter((r) => r.head_sha === sha);
|
||||
}
|
||||
|
||||
function listFailedChecksOnSha(runs) {
|
||||
return (runs || []).filter((run) => {
|
||||
if (run.status !== 'completed') return false;
|
||||
return run.conclusion === 'failure';
|
||||
});
|
||||
}
|
||||
|
||||
async function allChecksGreenOnSha(github, owner, repo, sha, core) {
|
||||
const runs = await listChecksOnSha(github, owner, repo, sha);
|
||||
if (runs.length === 0) {
|
||||
core?.info?.(`No check runs on ${sha.slice(0, 7)} — allowing (e.g. docs-only PR)`);
|
||||
return true;
|
||||
}
|
||||
for (const run of runs) {
|
||||
if (run.status !== 'completed') {
|
||||
core?.info?.(`Check pending: ${run.name} (${run.status})`);
|
||||
return false;
|
||||
}
|
||||
const ok =
|
||||
['success', 'neutral', 'skipped'].includes(run.conclusion) ||
|
||||
(run.conclusion === 'cancelled' && OPTIONAL_CANCELLED_CHECKS.has(run.name));
|
||||
if (!ok) {
|
||||
core?.info?.(`Check failed: ${run.name} (${run.conclusion})`);
|
||||
return false;
|
||||
}
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
function claudeRunBlocksPr(run, headRef) {
|
||||
if (!run || run.event === 'issues') return false;
|
||||
if (!headRef) return true;
|
||||
return run.head_branch === headRef;
|
||||
}
|
||||
|
||||
function hasBlockingClaudeRunForPr(runs, headRef) {
|
||||
return (runs || []).some((r) => claudeRunBlocksPr(r, headRef));
|
||||
}
|
||||
|
||||
async function hasInProgressClaudeAssistant(github, owner, repo, prNumber = null) {
|
||||
try {
|
||||
const { data } = await github.rest.actions.listWorkflowRuns({
|
||||
owner,
|
||||
repo,
|
||||
workflow_id: 'claude.yml',
|
||||
status: 'in_progress',
|
||||
per_page: 20,
|
||||
});
|
||||
const runs = (data.workflow_runs || []).filter((r) => r.event !== 'issues');
|
||||
if (runs.length === 0) return false;
|
||||
if (prNumber == null) return runs.length > 0;
|
||||
|
||||
const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
|
||||
const headRef = pr.head.ref;
|
||||
return hasBlockingClaudeRunForPr(runs, headRef);
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function isCiOnlyChange(files) {
|
||||
if (!files.length) return false;
|
||||
return files.every((f) => CI_ONLY_PATH_PREFIXES.some((p) => f.filename.startsWith(p)));
|
||||
}
|
||||
|
||||
function isInternalPullRequestLink(link, owner, repo) {
|
||||
if (link?.base?.repo?.full_name === `${owner}/${repo}`) return true;
|
||||
const baseUrl = link?.base?.repo?.url || '';
|
||||
return baseUrl.endsWith(`/repos/${owner}/${repo}`);
|
||||
}
|
||||
|
||||
async function resolvePrNumberFromLinkedPullRequests(github, owner, repo, linked) {
|
||||
const repoFull = `${owner}/${repo}`;
|
||||
const internal = (linked || []).filter((l) => isInternalPullRequestLink(l, owner, repo));
|
||||
for (const link of internal) {
|
||||
if (!link.number) continue;
|
||||
try {
|
||||
const { data } = await github.rest.pulls.get({
|
||||
owner,
|
||||
repo,
|
||||
pull_number: link.number,
|
||||
});
|
||||
if (data.state === 'open' && data.base?.repo?.full_name === repoFull) {
|
||||
return data.number;
|
||||
}
|
||||
} catch (err) {
|
||||
if (err.status !== 404) throw err;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
async function resolvePrNumberFromHeadBranch(github, owner, repo, branch) {
|
||||
if (!branch || branch === 'main' || branch === 'master') return null;
|
||||
const { data } = await github.rest.pulls.list({
|
||||
owner,
|
||||
repo,
|
||||
state: 'open',
|
||||
head: `${owner}:${branch}`,
|
||||
per_page: 1,
|
||||
});
|
||||
return data[0]?.number || null;
|
||||
}
|
||||
|
||||
async function resolvePrNumberFromWorkflowRun(github, owner, repo, workflowRun) {
|
||||
const fromLinked = await resolvePrNumberFromLinkedPullRequests(
|
||||
github, owner, repo, workflowRun.pull_requests
|
||||
);
|
||||
if (fromLinked) return fromLinked;
|
||||
|
||||
const fromBranch = await resolvePrNumberFromHeadBranch(
|
||||
github, owner, repo, workflowRun.head_branch
|
||||
);
|
||||
if (fromBranch) return fromBranch;
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
async function listPullFiles(github, owner, repo, prNumber) {
|
||||
if (typeof github.paginate === 'function') {
|
||||
return github.paginate(github.rest.pulls.listFiles, {
|
||||
owner,
|
||||
repo,
|
||||
pull_number: prNumber,
|
||||
per_page: 100,
|
||||
});
|
||||
}
|
||||
const { data } = await github.rest.pulls.listFiles({
|
||||
owner,
|
||||
repo,
|
||||
pull_number: prNumber,
|
||||
per_page: 100,
|
||||
});
|
||||
return data;
|
||||
}
|
||||
|
||||
function countNewAgentParams(patch) {
|
||||
if (!patch) return 0;
|
||||
return patch
|
||||
.split('\n')
|
||||
.filter((l) => l.startsWith('+') && !l.startsWith('+++'))
|
||||
.filter((l) => {
|
||||
const t = l.slice(1).trim();
|
||||
if (!t || t.startsWith('#') || t.startsWith('"""') || t.startsWith("'''")) return false;
|
||||
if (/^(def|class|@|return\b|if\b|elif\b|else\b|for\b|while\b)/.test(t)) return false;
|
||||
if (/^\w+\s*[:=]/.test(t) && !t.startsWith('self.')) return true;
|
||||
return false;
|
||||
}).length;
|
||||
}
|
||||
|
||||
function getAgentPyChangeFromFiles(files) {
|
||||
const agentFile = files.find((f) => f.filename.endsWith('praisonaiagents/agent/agent.py'));
|
||||
if (!agentFile) {
|
||||
return { touched: false, additions: 0, newParams: 0 };
|
||||
}
|
||||
return {
|
||||
touched: true,
|
||||
additions: agentFile.additions || 0,
|
||||
newParams: countNewAgentParams(agentFile.patch || ''),
|
||||
};
|
||||
}
|
||||
|
||||
async function getAgentPyChange(github, owner, repo, prNumber) {
|
||||
const files = await listPullFiles(github, owner, repo, prNumber);
|
||||
return getAgentPyChangeFromFiles(files);
|
||||
}
|
||||
|
||||
function touchesSdk(files) {
|
||||
return files.some((f) => SDK_PATH_PREFIXES.some((p) => f.filename.startsWith(p)));
|
||||
}
|
||||
|
||||
function hasManualOnlyLabel(labels) {
|
||||
return labels.some((l) => MANUAL_ONLY_LABELS.has(l));
|
||||
}
|
||||
|
||||
function sensitivePathReasons(files, labels = []) {
|
||||
if (labels.includes(WORKFLOW_ONLY_LABEL) && isCiOnlyChange(files)) {
|
||||
return [];
|
||||
}
|
||||
const reasons = [];
|
||||
for (const f of files) {
|
||||
if (SENSITIVE_PATH_PATTERNS.some((p) => p.test(f.filename))) {
|
||||
reasons.push(`sensitive path: ${f.filename}`);
|
||||
break;
|
||||
}
|
||||
}
|
||||
return reasons;
|
||||
}
|
||||
|
||||
function prSizeReasons(files) {
|
||||
const reasons = [];
|
||||
const totalAdditions = files.reduce((sum, f) => sum + (f.additions || 0), 0);
|
||||
if (totalAdditions > PR_MAX_AUTO_ADDITIONS) {
|
||||
reasons.push(`PR +${totalAdditions} lines (>${PR_MAX_AUTO_ADDITIONS}) requires manual review`);
|
||||
}
|
||||
if (files.length > PR_MAX_AUTO_FILES) {
|
||||
reasons.push(`${files.length} files changed (>${PR_MAX_AUTO_FILES}) requires manual review`);
|
||||
}
|
||||
return reasons;
|
||||
}
|
||||
|
||||
function missingTestsReason(files) {
|
||||
const productAdds = files.filter(
|
||||
(f) =>
|
||||
SDK_PATH_PREFIXES.some((p) => f.filename.startsWith(p)) &&
|
||||
f.filename.startsWith('src/praisonaiui/') &&
|
||||
f.filename.endsWith('.py') &&
|
||||
!f.filename.endsWith('__init__.py') &&
|
||||
(f.additions || 0) > 0
|
||||
);
|
||||
if (productAdds.length === 0) return null;
|
||||
const hasTestChange = files.some(
|
||||
(f) => /\/tests?\//.test(f.filename) || /test_.*\.py$/.test(f.filename) || /_test\.py$/.test(f.filename)
|
||||
);
|
||||
if (!hasTestChange) return 'Product code added without test file changes — requires manual review';
|
||||
return null;
|
||||
}
|
||||
|
||||
function secretScanReasons(files) {
|
||||
for (const f of files) {
|
||||
if (/\/tests?\//.test(f.filename) || /test_.*\.py$/.test(f.filename)) continue;
|
||||
const patch = f.patch || '';
|
||||
if (!patch) continue;
|
||||
for (const pattern of SECRET_PATTERNS) {
|
||||
if (pattern.test(patch)) {
|
||||
return [`possible secret in diff (${f.filename}) — requires manual review`];
|
||||
}
|
||||
}
|
||||
}
|
||||
return [];
|
||||
}
|
||||
|
||||
async function sdkTestChecksReason(github, owner, repo, sha, files, core) {
|
||||
if (!touchesSdk(files)) return null;
|
||||
const { data } = await github.rest.checks.listForRef({
|
||||
owner,
|
||||
repo,
|
||||
ref: sha,
|
||||
per_page: 100,
|
||||
});
|
||||
const runs = (data.check_runs || []).filter((r) => r.head_sha === sha);
|
||||
if (runs.length === 0) {
|
||||
return 'SDK code changed but no CI checks on HEAD';
|
||||
}
|
||||
const testRuns = runs.filter((r) => REQUIRED_SDK_CHECK_PATTERNS.some((p) => p.test(r.name || '')));
|
||||
if (testRuns.length === 0) {
|
||||
return 'SDK code changed but no test check runs on HEAD';
|
||||
}
|
||||
core?.info?.(`SDK test checks on HEAD: ${testRuns.map((r) => r.name).join(', ')}`);
|
||||
return null;
|
||||
}
|
||||
|
||||
function manualReviewReasonForAgentPy(agentChange) {
|
||||
if (!agentChange.touched) return null;
|
||||
if (agentChange.additions > AGENT_PY_MAX_AUTO_LINES) {
|
||||
return `agent.py +${agentChange.additions} lines (>${AGENT_PY_MAX_AUTO_LINES}) requires manual review`;
|
||||
}
|
||||
if (agentChange.newParams > 0) {
|
||||
return `agent.py adds ${agentChange.newParams} new Agent param(s) — requires manual review`;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
async function listAllComments(github, owner, repo, issueNumber) {
|
||||
if (typeof github.paginate === 'function') {
|
||||
return github.paginate(github.rest.issues.listComments, {
|
||||
owner,
|
||||
repo,
|
||||
issue_number: issueNumber,
|
||||
per_page: 100,
|
||||
});
|
||||
}
|
||||
const { data } = await github.rest.issues.listComments({
|
||||
owner,
|
||||
repo,
|
||||
issue_number: issueNumber,
|
||||
per_page: 100,
|
||||
});
|
||||
return data;
|
||||
}
|
||||
|
||||
async function getHeadCommitDate(github, owner, repo, prNumber) {
|
||||
try {
|
||||
let commits;
|
||||
if (typeof github.paginate === 'function') {
|
||||
commits = await github.paginate(github.rest.pulls.listCommits, {
|
||||
owner,
|
||||
repo,
|
||||
pull_number: prNumber,
|
||||
per_page: 100,
|
||||
});
|
||||
} else {
|
||||
const { data } = await github.rest.pulls.listCommits({
|
||||
owner,
|
||||
repo,
|
||||
pull_number: prNumber,
|
||||
per_page: 100,
|
||||
});
|
||||
commits = data;
|
||||
}
|
||||
const last = commits[commits.length - 1];
|
||||
return last?.commit?.committer?.date || last?.commit?.author?.date || null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
async function loadPrContext(github, owner, repo, prNumber) {
|
||||
const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
|
||||
const { data: issue } = await github.rest.issues.get({ owner, repo, issue_number: prNumber });
|
||||
const comments = await listAllComments(github, owner, repo, prNumber);
|
||||
const { data: reviews } = await github.rest.pulls.listReviews({
|
||||
owner,
|
||||
repo,
|
||||
pull_number: prNumber,
|
||||
per_page: 100,
|
||||
});
|
||||
const mergeState = await getMergeState(github, owner, repo, prNumber);
|
||||
const headSha = mergeState.headSha || pr.head.sha;
|
||||
const headCommitDate = await getHeadCommitDate(github, owner, repo, prNumber);
|
||||
const headPushedAt = headCommitDate || pr.updated_at;
|
||||
|
||||
return {
|
||||
pr,
|
||||
issue,
|
||||
comments,
|
||||
reviews,
|
||||
mergeState,
|
||||
headSha,
|
||||
headPushedAt,
|
||||
labels: issue.labels.map((l) => l.name),
|
||||
baseRepo: `${owner}/${repo}`,
|
||||
};
|
||||
}
|
||||
|
||||
async function evaluatePipelineQuiescent(github, owner, repo, prNumber, core, options = {}) {
|
||||
const {
|
||||
forMergeStep = false,
|
||||
skipGlobalClaudeRunCheck = false,
|
||||
skipRecentClaudeCooldown = false,
|
||||
} = options;
|
||||
const ctx = await loadPrContext(github, owner, repo, prNumber);
|
||||
const reasons = [];
|
||||
|
||||
if (ctx.pr.draft) reasons.push('draft');
|
||||
if (ctx.pr.state !== 'open') reasons.push('not open');
|
||||
if (ctx.labels.includes('auto-merged-by-gate')) reasons.push('already merged by gate');
|
||||
if (ctx.labels.includes('no-auto-merge')) reasons.push('no-auto-merge label');
|
||||
if (ctx.labels.includes('claude-conflict-pending')) reasons.push('claude-conflict-pending');
|
||||
if (!forMergeStep && ctx.labels.includes('claude-merge-gate-active')) {
|
||||
reasons.push('claude-merge-gate-active');
|
||||
}
|
||||
|
||||
const { status, headRepo, maintainerCanModify } = ctx.mergeState;
|
||||
if (!ALLOWED_MERGE_STATES.has(status)) reasons.push(`mergeState=${status}`);
|
||||
|
||||
if (headRepo && headRepo !== ctx.baseRepo) {
|
||||
reasons.push('fork PR');
|
||||
}
|
||||
|
||||
if (hasRecentConflictComment(ctx.comments, ctx.headPushedAt)) {
|
||||
reasons.push('recent merge-conflict @claude');
|
||||
}
|
||||
if (!skipRecentClaudeCooldown && hasRecentClaudeTrigger(ctx.comments, 35)) {
|
||||
const verdictOnHead = findMergeGateVerdict(ctx.comments, null, ctx.headPushedAt) !== null;
|
||||
if (!verdictOnHead) reasons.push('recent @claude within 35min');
|
||||
}
|
||||
|
||||
if (!skipGlobalClaudeRunCheck && (await hasInProgressClaudeAssistant(github, owner, repo, prNumber))) {
|
||||
reasons.push('claude.yml in progress');
|
||||
}
|
||||
|
||||
const checksOk = await allChecksGreenOnSha(github, owner, repo, ctx.headSha, core);
|
||||
if (!checksOk) reasons.push('CI not green on HEAD');
|
||||
|
||||
if (!finalClaudeCompletedOnSha(ctx.comments, ctx.headPushedAt)) {
|
||||
if (!hasFinalClaudeReviewTrigger(ctx.comments)) {
|
||||
reasons.push('no FINAL Claude review trigger');
|
||||
} else if (isStaleFinalAfterPush(ctx.comments, ctx.headPushedAt)) {
|
||||
reasons.push('stale FINAL after new commits (needs @claude re-review)');
|
||||
} else {
|
||||
reasons.push('FINAL Claude not complete on HEAD');
|
||||
}
|
||||
}
|
||||
|
||||
if (hasAnyChangesRequested(ctx.reviews)) reasons.push('CHANGES_REQUESTED review');
|
||||
|
||||
if (hasManualOnlyLabel(ctx.labels)) {
|
||||
const manualLabel = ctx.labels.find((l) => MANUAL_ONLY_LABELS.has(l));
|
||||
reasons.push(`manual-only label: ${manualLabel}`);
|
||||
}
|
||||
|
||||
const pullFiles = await listPullFiles(github, owner, repo, prNumber);
|
||||
|
||||
if (config.agentPyChecks) {
|
||||
const agentChange = getAgentPyChangeFromFiles(pullFiles);
|
||||
const agentManual = manualReviewReasonForAgentPy(agentChange);
|
||||
if (agentManual) reasons.push(agentManual);
|
||||
}
|
||||
|
||||
reasons.push(...sensitivePathReasons(pullFiles, ctx.labels));
|
||||
reasons.push(...prSizeReasons(pullFiles));
|
||||
reasons.push(...secretScanReasons(pullFiles));
|
||||
|
||||
const testsReason = missingTestsReason(pullFiles);
|
||||
if (testsReason) reasons.push(testsReason);
|
||||
|
||||
const sdkCheckReason = await sdkTestChecksReason(github, owner, repo, ctx.headSha, pullFiles, core);
|
||||
if (sdkCheckReason) reasons.push(sdkCheckReason);
|
||||
|
||||
if (ctx.pr.mergeable === false) reasons.push('not mergeable');
|
||||
|
||||
const ready = reasons.length === 0;
|
||||
return {
|
||||
ready,
|
||||
reasons,
|
||||
headSha: ctx.headSha,
|
||||
prNumber,
|
||||
};
|
||||
}
|
||||
|
||||
async function listPrNumbersForMergeGateScan(github, owner, repo, core) {
|
||||
let mergeReadyIssues;
|
||||
if (typeof github.paginate === 'function') {
|
||||
mergeReadyIssues = await github.paginate(github.rest.issues.listForRepo, {
|
||||
owner,
|
||||
repo,
|
||||
state: 'open',
|
||||
labels: MERGE_READY_LABEL,
|
||||
per_page: 100,
|
||||
});
|
||||
} else {
|
||||
({ data: mergeReadyIssues } = await github.rest.issues.listForRepo({
|
||||
owner,
|
||||
repo,
|
||||
state: 'open',
|
||||
labels: MERGE_READY_LABEL,
|
||||
per_page: 100,
|
||||
}));
|
||||
}
|
||||
const mergeReady = mergeReadyIssues
|
||||
.filter((issue) => issue.pull_request)
|
||||
.map((issue) => issue.number)
|
||||
.sort((a, b) => a - b);
|
||||
|
||||
if (mergeReady.length > 0) {
|
||||
core?.info?.(
|
||||
`Merge gate scan: ${mergeReady.length} ${MERGE_READY_LABEL} PR(s) (skipping unlabelled open PRs)`
|
||||
);
|
||||
return mergeReady;
|
||||
}
|
||||
|
||||
core?.info?.(`No ${MERGE_READY_LABEL} PRs — scanning oldest open PRs`);
|
||||
const prs =
|
||||
typeof github.paginate === 'function'
|
||||
? await github.paginate(github.rest.pulls.list, {
|
||||
owner,
|
||||
repo,
|
||||
state: 'open',
|
||||
per_page: 100,
|
||||
sort: 'created',
|
||||
direction: 'asc',
|
||||
})
|
||||
: (await github.rest.pulls.list({
|
||||
owner,
|
||||
repo,
|
||||
state: 'open',
|
||||
per_page: 100,
|
||||
sort: 'created',
|
||||
direction: 'asc',
|
||||
})).data;
|
||||
return prs.map((pr) => pr.number);
|
||||
}
|
||||
|
||||
async function selectMergeGateCandidates(github, owner, repo, prNumbers, maxCandidates, core) {
|
||||
const readyList = [];
|
||||
const skipped = [];
|
||||
for (const num of prNumbers) {
|
||||
if (readyList.length >= maxCandidates) {
|
||||
core?.info?.(`Found ${maxCandidates} candidate(s) — skipping remaining PR scans`);
|
||||
break;
|
||||
}
|
||||
const result = await evaluatePipelineQuiescent(github, owner, repo, num, core);
|
||||
if (result.ready) {
|
||||
readyList.push({ pr_number: num, head_sha: result.headSha });
|
||||
} else {
|
||||
skipped.push({ pr: num, reasons: result.reasons });
|
||||
}
|
||||
}
|
||||
readyList.sort((a, b) => a.pr_number - b.pr_number);
|
||||
return {
|
||||
candidates: readyList.slice(0, maxCandidates),
|
||||
skipped,
|
||||
};
|
||||
}
|
||||
|
||||
const AUTOMATED_FALLBACK_MARKER = 'Automated fallback —';
|
||||
|
||||
function isAutomatedFallbackVerdict(body) {
|
||||
return (body || '').includes(AUTOMATED_FALLBACK_MARKER);
|
||||
}
|
||||
|
||||
function findMergeGateVerdict(comments, minCreatedAt = null, headPushedAt = null, options = {}) {
|
||||
const { excludeAutomatedFallback = false } = options || {};
|
||||
const minTime = minCreatedAt ? new Date(minCreatedAt).getTime() : 0;
|
||||
const headTime = headPushedAt ? new Date(headPushedAt).getTime() - 60000 : 0;
|
||||
const gateComments = comments
|
||||
.filter((c) => {
|
||||
if (!(c.body || '').includes('MERGE_GATE_VERDICT:')) return false;
|
||||
if (excludeAutomatedFallback && isAutomatedFallbackVerdict(c.body)) return false;
|
||||
const created = new Date(c.created_at).getTime();
|
||||
if (minTime && created < minTime) return false;
|
||||
if (headTime && created < headTime) return false;
|
||||
return true;
|
||||
})
|
||||
.sort((a, b) => new Date(b.created_at) - new Date(a.created_at));
|
||||
if (gateComments.length === 0) return null;
|
||||
const body = gateComments[0].body || '';
|
||||
if (body.includes('MERGE_GATE_VERDICT: APPROVE')) return 'APPROVE';
|
||||
if (body.includes('MERGE_GATE_VERDICT: BLOCK')) return 'BLOCK';
|
||||
return null;
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
CLAUDE_TRIGGER_LOGINS,
|
||||
AUTO_ACTORS,
|
||||
isFinalClaudeTriggerComment,
|
||||
isClaudeTriggerNoise,
|
||||
isClaudeFinalReplyComment,
|
||||
hasRecentClaudeTrigger,
|
||||
hasRecentConflictComment,
|
||||
isConflictRebaseTriggerComment,
|
||||
isConflictRebaseCompletionComment,
|
||||
needsFinalReReviewAfterConflictRebase,
|
||||
conflictRebaseQuiescent,
|
||||
hasHumanChangesRequested,
|
||||
hasAnyChangesRequested,
|
||||
hasFinalClaudeReviewTrigger,
|
||||
finalClaudeCompletedOnSha,
|
||||
getMergeState,
|
||||
OPTIONAL_CANCELLED_CHECKS,
|
||||
listChecksOnSha,
|
||||
listFailedChecksOnSha,
|
||||
allChecksGreenOnSha,
|
||||
hasInProgressClaudeAssistant,
|
||||
claudeRunBlocksPr,
|
||||
hasBlockingClaudeRunForPr,
|
||||
isCiOnlyChange,
|
||||
isInternalPullRequestLink,
|
||||
resolvePrNumberFromLinkedPullRequests,
|
||||
resolvePrNumberFromHeadBranch,
|
||||
resolvePrNumberFromWorkflowRun,
|
||||
WORKFLOW_ONLY_LABEL,
|
||||
getAgentPyChange,
|
||||
getAgentPyChangeFromFiles,
|
||||
manualReviewReasonForAgentPy,
|
||||
countNewAgentParams,
|
||||
listPullFiles,
|
||||
touchesSdk,
|
||||
hasManualOnlyLabel,
|
||||
sensitivePathReasons,
|
||||
prSizeReasons,
|
||||
missingTestsReason,
|
||||
secretScanReasons,
|
||||
sdkTestChecksReason,
|
||||
listAllComments,
|
||||
getHeadCommitDate,
|
||||
isStaleFinalAfterPush,
|
||||
needsStaleFinalRecovery,
|
||||
shouldSkipFinalRecovery,
|
||||
shouldSkipStaleFinalRecovery,
|
||||
isClaudeAutomationLogin,
|
||||
isPushSoonAfterLatestFinal,
|
||||
countFinalTriggersSince,
|
||||
STALE_FINAL_RECOVERY_WINDOW_MS,
|
||||
STALE_FINAL_MAX_PER_WINDOW,
|
||||
FINAL_CLAUDE_REVIEW_BODY,
|
||||
loadPrContext,
|
||||
evaluatePipelineQuiescent,
|
||||
MERGE_READY_LABEL,
|
||||
listPrNumbersForMergeGateScan,
|
||||
selectMergeGateCandidates,
|
||||
isAutomatedFallbackVerdict,
|
||||
AUTOMATED_FALLBACK_MARKER,
|
||||
findMergeGateVerdict,
|
||||
};
|
||||
@@ -1,82 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Run: node .github/scripts/pipeline-status-selftest.js
|
||||
*/
|
||||
const ps = require('./pipeline-status.js');
|
||||
const mg = require('./merge-gate.js');
|
||||
const config = require('./gate-config.js');
|
||||
|
||||
let failed = 0;
|
||||
function assert(name, cond) {
|
||||
if (!cond) {
|
||||
console.error('FAIL:', name);
|
||||
failed++;
|
||||
} else {
|
||||
console.log('ok:', name);
|
||||
}
|
||||
}
|
||||
|
||||
const kickComments = [
|
||||
{ user: { login: 'MervinPraison' }, body: '@coderabbitai review' },
|
||||
{ user: { login: 'MervinPraison' }, body: '/review' },
|
||||
];
|
||||
|
||||
const finalComment = {
|
||||
user: { login: 'MervinPraison' },
|
||||
body: '@claude You are the FINAL architecture reviewer.',
|
||||
created_at: '2026-06-26T10:00:00Z',
|
||||
};
|
||||
|
||||
assert(
|
||||
'reviews pending when not kicked',
|
||||
ps.deriveStage([], { ready: false, reasons: ['no FINAL Claude review trigger'] })
|
||||
=== 'pipeline/reviews-pending'
|
||||
);
|
||||
assert(
|
||||
'final pending after kick',
|
||||
ps.deriveStage(kickComments, { ready: false, reasons: ['no FINAL Claude review trigger'] })
|
||||
=== 'pipeline/final-claude-pending'
|
||||
);
|
||||
assert(
|
||||
'awaiting merge gate after bot review comment',
|
||||
ps.deriveStage(
|
||||
[
|
||||
{ user: { login: 'coderabbitai[bot]' }, body: 'review summary' },
|
||||
finalComment,
|
||||
],
|
||||
{ ready: false, reasons: ['recent @claude within 35min'] }
|
||||
) === 'pipeline/awaiting-merge-gate'
|
||||
);
|
||||
|
||||
assert('review bot logins configured', config.reviewBotLogins.includes('coderabbitai[bot]'));
|
||||
assert(
|
||||
'merge ready',
|
||||
ps.deriveStage([...kickComments, finalComment], { ready: true, reasons: [] })
|
||||
=== 'pipeline/merge-ready'
|
||||
);
|
||||
|
||||
const blockers = ps.deriveBlockerLabels({
|
||||
ready: false,
|
||||
reasons: ['CI not green on HEAD', 'SDK code added without test file changes — requires manual review'],
|
||||
});
|
||||
assert('maps ci blocker', blockers.includes('pipeline/blocked:ci'));
|
||||
assert('maps manual blocker', blockers.includes('pipeline/blocked:manual-review'));
|
||||
|
||||
assert(
|
||||
'internal link matches upstream base',
|
||||
mg.isInternalPullRequestLink(
|
||||
{ base: { repo: { full_name: 'MervinPraison/PraisonAI' } } },
|
||||
'MervinPraison',
|
||||
'PraisonAI'
|
||||
)
|
||||
);
|
||||
assert(
|
||||
'fork sync link rejected',
|
||||
!mg.isInternalPullRequestLink(
|
||||
{ number: 21, base: { repo: { full_name: 'Milkmange/PraisonAI' } } },
|
||||
'MervinPraison',
|
||||
'PraisonAI'
|
||||
)
|
||||
);
|
||||
|
||||
process.exit(failed ? 1 : 0);
|
||||
@@ -1,264 +0,0 @@
|
||||
/**
|
||||
* Sync pipeline stage/blocker labels on open PRs.
|
||||
* @see .github/workflows/pipeline-status-sync.yml
|
||||
*/
|
||||
|
||||
const mergeGate = require('./merge-gate.js');
|
||||
const chain = require('./bot-pr-review-chain.js');
|
||||
const ciFix = require('./ci-failure-claude.js');
|
||||
const config = require('./gate-config.js');
|
||||
|
||||
const PIPELINE_PREFIX = 'pipeline/';
|
||||
const STAGE_LABELS = [
|
||||
'pipeline/reviews-pending',
|
||||
'pipeline/final-claude-pending',
|
||||
'pipeline/awaiting-merge-gate',
|
||||
'pipeline/merge-ready',
|
||||
'pipeline/merged',
|
||||
];
|
||||
const BLOCKER_LABELS = [
|
||||
'pipeline/blocked:ci',
|
||||
'pipeline/blocked:conflict',
|
||||
'pipeline/blocked:manual-review',
|
||||
'pipeline/blocked:cooldown',
|
||||
'pipeline/blocked:stale-final',
|
||||
'pipeline/blocked:no-final',
|
||||
];
|
||||
const ALL_PIPELINE_LABELS = [...STAGE_LABELS, ...BLOCKER_LABELS];
|
||||
|
||||
const LABEL_SPECS = [
|
||||
{ name: 'pipeline/reviews-pending', color: 'fbca04', description: 'Waiting for CodeRabbit/Qodo/Copilot reviews' },
|
||||
{ name: 'pipeline/final-claude-pending', color: 'd4c5f9', description: 'Reviews done; waiting for FINAL @claude' },
|
||||
{ name: 'pipeline/awaiting-merge-gate', color: 'c5def5', description: 'FINAL done; waiting for merge gate / CI' },
|
||||
{ name: 'pipeline/merge-ready', color: '0e8a16', description: 'Eligible for merge gate auto-merge' },
|
||||
{ name: 'pipeline/merged', color: '6f42c1', description: 'Merged via pipeline' },
|
||||
{ name: 'pipeline/blocked:ci', color: 'd93f0b', description: 'Blocked: CI not green on HEAD' },
|
||||
{ name: 'pipeline/blocked:conflict', color: 'b60205', description: 'Blocked: merge conflict or rebase pending' },
|
||||
{ name: 'pipeline/blocked:manual-review', color: 'e99695', description: 'Blocked: requires manual review' },
|
||||
{ name: 'pipeline/blocked:cooldown', color: 'fef2c0', description: 'Blocked: post-push or @claude cooldown' },
|
||||
{ name: 'pipeline/blocked:stale-final', color: 'f9d0c4', description: 'Blocked: FINAL stale after new commits' },
|
||||
{ name: 'pipeline/blocked:no-final', color: 'ededed', description: 'Blocked: no FINAL @claude trigger yet' },
|
||||
];
|
||||
|
||||
function reviewChainStarted(comments) {
|
||||
if (chain.chainKickPosted(comments)) return true;
|
||||
return comments.some((c) => config.reviewBotLogins.includes(c.user?.login));
|
||||
}
|
||||
|
||||
function deriveStage(comments, evalResult) {
|
||||
if (evalResult.ready) return 'pipeline/merge-ready';
|
||||
if (!reviewChainStarted(comments)) return 'pipeline/reviews-pending';
|
||||
if (!mergeGate.hasFinalClaudeReviewTrigger(comments)) return 'pipeline/final-claude-pending';
|
||||
return 'pipeline/awaiting-merge-gate';
|
||||
}
|
||||
|
||||
function reasonToBlockerLabel(reason) {
|
||||
const r = (reason || '').toLowerCase();
|
||||
if (r.includes('ci not green') || r.includes('sdk code changed but no ci')) return 'pipeline/blocked:ci';
|
||||
if (
|
||||
r.includes('conflict') ||
|
||||
r.includes('mergestate=dirty') ||
|
||||
r.includes('not mergeable')
|
||||
) return 'pipeline/blocked:conflict';
|
||||
if (
|
||||
r.includes('manual') ||
|
||||
r.includes('requires manual') ||
|
||||
r.includes('sensitive path') ||
|
||||
r.includes('no-auto-merge') ||
|
||||
r.includes('manual-only label') ||
|
||||
r.includes('without test') ||
|
||||
r.includes('product code') ||
|
||||
r.includes('files changed') ||
|
||||
r.includes('possible secret')
|
||||
) return 'pipeline/blocked:manual-review';
|
||||
if (r.includes('recent @claude') || r.includes('post-push buffer')) return 'pipeline/blocked:cooldown';
|
||||
if (r.includes('stale final')) return 'pipeline/blocked:stale-final';
|
||||
if (r.includes('no final claude')) return 'pipeline/blocked:no-final';
|
||||
if (r.includes('final claude not complete')) return 'pipeline/blocked:stale-final';
|
||||
if (r.includes('claude.yml in progress') || r.includes('claude-merge-gate-active')) {
|
||||
return null;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function deriveBlockerLabels(evalResult) {
|
||||
if (evalResult.ready) return [];
|
||||
const labels = new Set();
|
||||
for (const reason of evalResult.reasons || []) {
|
||||
const mapped = reasonToBlockerLabel(reason);
|
||||
if (mapped && mapped.startsWith('pipeline/blocked:')) labels.add(mapped);
|
||||
}
|
||||
return [...labels];
|
||||
}
|
||||
|
||||
function computePipelineLabels(comments, evalResult) {
|
||||
const stage = deriveStage(comments, evalResult);
|
||||
const blockers = stage === 'pipeline/merge-ready' ? [] : deriveBlockerLabels(evalResult);
|
||||
return { stage, blockers, all: [stage, ...blockers] };
|
||||
}
|
||||
|
||||
async function ensurePipelineLabels(github, owner, repo, core) {
|
||||
let existing;
|
||||
if (typeof github.paginate === 'function') {
|
||||
existing = await github.paginate(github.rest.issues.listLabelsForRepo, {
|
||||
owner,
|
||||
repo,
|
||||
per_page: 100,
|
||||
});
|
||||
} else {
|
||||
({ data: existing } = await github.rest.issues.listLabelsForRepo({
|
||||
owner,
|
||||
repo,
|
||||
per_page: 100,
|
||||
}));
|
||||
}
|
||||
const names = new Set(existing.map((l) => l.name));
|
||||
for (const spec of LABEL_SPECS) {
|
||||
if (names.has(spec.name)) continue;
|
||||
try {
|
||||
await github.rest.issues.createLabel({
|
||||
owner,
|
||||
repo,
|
||||
name: spec.name,
|
||||
color: spec.color,
|
||||
description: spec.description,
|
||||
});
|
||||
core?.info?.(`Created label ${spec.name}`);
|
||||
} catch (err) {
|
||||
if (err.status !== 422) throw err;
|
||||
core?.info?.(`Label ${spec.name} already exists`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async function syncPipelineLabels(github, owner, repo, prNumber, core) {
|
||||
const ctx = await mergeGate.loadPrContext(github, owner, repo, prNumber);
|
||||
if (ctx.pr.state !== 'open') return { synced: false, reason: 'not_open' };
|
||||
|
||||
const evalResult = await mergeGate.evaluatePipelineQuiescent(
|
||||
github, owner, repo, prNumber, core
|
||||
);
|
||||
const { stage, blockers, all } = computePipelineLabels(ctx.comments, evalResult);
|
||||
|
||||
const current = ctx.labels.filter((l) => l.startsWith(PIPELINE_PREFIX));
|
||||
const desired = new Set(all);
|
||||
const toRemove = current.filter((l) => !desired.has(l) && l !== 'pipeline/merged');
|
||||
const toAdd = all.filter((l) => !current.includes(l));
|
||||
|
||||
for (const name of toRemove) {
|
||||
try {
|
||||
await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name });
|
||||
} catch (err) {
|
||||
if (err.status !== 404) throw err;
|
||||
}
|
||||
}
|
||||
if (toAdd.length) {
|
||||
await github.rest.issues.addLabels({
|
||||
owner,
|
||||
repo,
|
||||
issue_number: prNumber,
|
||||
labels: toAdd,
|
||||
});
|
||||
}
|
||||
|
||||
core?.info?.(`PR #${prNumber}: stage=${stage} blockers=[${blockers.join(', ')}]`);
|
||||
|
||||
const ciNotGreen = (evalResult.reasons || []).some((r) =>
|
||||
r.toLowerCase().includes('ci not green')
|
||||
);
|
||||
if (ciNotGreen || blockers.includes('pipeline/blocked:ci')) {
|
||||
await ciFix.maybeTriggerCiFixClaude(github, owner, repo, prNumber, core);
|
||||
} else {
|
||||
await ciFix.maybeClearCiFixLabel(
|
||||
github, owner, repo, prNumber, ctx.labels, ctx.headSha, core
|
||||
);
|
||||
}
|
||||
|
||||
return {
|
||||
synced: true,
|
||||
stage,
|
||||
blockers,
|
||||
ready: evalResult.ready,
|
||||
reasons: evalResult.reasons,
|
||||
labels: ctx.labels,
|
||||
createdAt: new Date(ctx.pr.created_at).getTime(),
|
||||
};
|
||||
}
|
||||
|
||||
async function dispatchMergeGateForOldestReady(github, owner, repo, readyCandidates, core) {
|
||||
if (!readyCandidates.length) return 0;
|
||||
readyCandidates.sort((a, b) => a.createdAt - b.createdAt);
|
||||
for (const cand of readyCandidates) {
|
||||
if ((cand.labels || []).includes('claude-merge-gate-active')) {
|
||||
core?.info?.(`Skip dispatch PR #${cand.prNumber}: merge gate already active`);
|
||||
continue;
|
||||
}
|
||||
await github.rest.repos.createDispatchEvent({
|
||||
owner,
|
||||
repo,
|
||||
event_type: 'claude-merge-gate',
|
||||
client_payload: { pr_number: cand.prNumber },
|
||||
});
|
||||
core?.info?.(`Dispatched merge gate for ready PR #${cand.prNumber}`);
|
||||
return cand.prNumber;
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
|
||||
async function syncOpenPullRequests(github, owner, repo, options, core) {
|
||||
const { maxPrs = 20, dispatchMergeGate = true } = options || {};
|
||||
await ensurePipelineLabels(github, owner, repo, core);
|
||||
let prs;
|
||||
if (maxPrs <= 100) {
|
||||
({ data: prs } = await github.rest.pulls.list({
|
||||
owner,
|
||||
repo,
|
||||
state: 'open',
|
||||
per_page: 100,
|
||||
}));
|
||||
} else {
|
||||
prs = await github.paginate(github.rest.pulls.list, {
|
||||
owner,
|
||||
repo,
|
||||
state: 'open',
|
||||
per_page: 100,
|
||||
});
|
||||
}
|
||||
let synced = 0;
|
||||
const readyCandidates = [];
|
||||
for (const pr of prs) {
|
||||
if (synced >= maxPrs) break;
|
||||
if (pr.draft) continue;
|
||||
if (pr.head?.repo?.full_name && pr.head.repo.full_name !== `${owner}/${repo}`) continue;
|
||||
const result = await syncPipelineLabels(github, owner, repo, pr.number, core);
|
||||
if (result.ready) {
|
||||
readyCandidates.push({
|
||||
prNumber: pr.number,
|
||||
createdAt: result.createdAt || new Date(pr.created_at).getTime(),
|
||||
labels: result.labels || [],
|
||||
});
|
||||
}
|
||||
synced += 1;
|
||||
}
|
||||
let dispatched = 0;
|
||||
if (dispatchMergeGate && readyCandidates.length) {
|
||||
dispatched = await dispatchMergeGateForOldestReady(
|
||||
github, owner, repo, readyCandidates, core
|
||||
);
|
||||
}
|
||||
core?.info?.(`Pipeline label sync complete (${synced} PR(s), dispatched=${dispatched || 'none'})`);
|
||||
return synced;
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
STAGE_LABELS,
|
||||
BLOCKER_LABELS,
|
||||
ALL_PIPELINE_LABELS,
|
||||
deriveStage,
|
||||
deriveBlockerLabels,
|
||||
computePipelineLabels,
|
||||
ensurePipelineLabels,
|
||||
syncPipelineLabels,
|
||||
syncOpenPullRequests,
|
||||
dispatchMergeGateForOldestReady,
|
||||
};
|
||||
@@ -1,90 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
const chain = require('./pr-review-chain.js');
|
||||
|
||||
let failed = 0;
|
||||
function assert(name, cond) {
|
||||
if (!cond) {
|
||||
console.error('FAIL:', name);
|
||||
failed++;
|
||||
} else {
|
||||
console.log('ok:', name);
|
||||
}
|
||||
}
|
||||
|
||||
const coderabbit = {
|
||||
user: { login: 'coderabbitai[bot]' },
|
||||
body: '<!-- summarize by coderabbit.ai --> summary',
|
||||
created_at: '2026-07-02T07:16:00Z',
|
||||
};
|
||||
const greptile = {
|
||||
user: { login: 'greptile-apps[bot]' },
|
||||
body: '<h3>Greptile Summary</h3><p>Looks good</p>',
|
||||
created_at: '2026-07-02T07:19:00Z',
|
||||
};
|
||||
const copilotKick = {
|
||||
user: { login: 'MervinPraison' },
|
||||
body: '@copilot Do a thorough review',
|
||||
created_at: '2026-07-02T07:20:00Z',
|
||||
};
|
||||
const copilotReply = {
|
||||
user: { login: 'copilot-swe-agent' },
|
||||
body: 'Copilot review here',
|
||||
created_at: '2026-07-02T07:22:00Z',
|
||||
};
|
||||
|
||||
assert('prior not ready without greptile', !chain.priorReviewersReady([coderabbit]).ready);
|
||||
assert('prior ready with coderabbit + greptile', chain.priorReviewersReady([coderabbit, greptile]).ready);
|
||||
assert('copilot not ready before trigger', !chain.copilotReviewReady([coderabbit, greptile]).ready);
|
||||
assert(
|
||||
'copilot ready after reply',
|
||||
chain.copilotReviewReady([coderabbit, greptile, copilotKick, copilotReply]).ready
|
||||
);
|
||||
assert(
|
||||
'claude not ready before copilot',
|
||||
!chain.claudeFinalReady([coderabbit, greptile]).ready
|
||||
);
|
||||
assert(
|
||||
'claude ready after full chain',
|
||||
chain.claudeFinalReady([coderabbit, greptile, copilotKick, copilotReply]).ready
|
||||
);
|
||||
assert(
|
||||
'claude timeout fallback when copilot triggered but silent',
|
||||
chain.claudeFinalReady([coderabbit, greptile, copilotKick], [], { allowCopilotTimeout: true }).ready
|
||||
);
|
||||
assert(
|
||||
'no timeout fallback without copilot trigger',
|
||||
!chain.claudeFinalReady([coderabbit, greptile], [], { allowCopilotTimeout: true }).ready
|
||||
);
|
||||
assert(
|
||||
'skipCopilot proceeds after prior reviewers',
|
||||
chain.claudeFinalReady([coderabbit, greptile], [], { skipCopilot: true }).ready
|
||||
);
|
||||
|
||||
const oldPr = new Date(Date.now() - 31 * 60 * 1000).toISOString();
|
||||
assert(
|
||||
'prior not ready without coderabbit before timeout',
|
||||
!chain.priorReviewersReady([greptile], [], { prCreatedAt: new Date().toISOString(), requiredWaitMs: 30 * 60 * 1000 }).ready
|
||||
);
|
||||
assert(
|
||||
'prior timeout when coderabbit silent after 30m',
|
||||
chain.priorReviewersReady([greptile], [], { prCreatedAt: oldPr, requiredWaitMs: 30 * 60 * 1000 }).ready
|
||||
);
|
||||
assert(
|
||||
'claude FINAL timeout when required reviewer silent and no prior FINAL',
|
||||
chain.claudeFinalReady([greptile], [], { prCreatedAt: oldPr, requiredWaitMs: 30 * 60 * 1000 }).ready
|
||||
);
|
||||
assert(
|
||||
'claude FINAL timeout auto-skips copilot without explicit skipCopilot',
|
||||
chain.claudeFinalReady([greptile], [], { prCreatedAt: oldPr, requiredWaitMs: 30 * 60 * 1000 }).copilotSkipped
|
||||
);
|
||||
const finalClaude = {
|
||||
user: { login: 'github-actions[bot]' },
|
||||
body: '@claude You are the FINAL architecture reviewer for this PR.',
|
||||
created_at: '2026-07-02T07:25:00Z',
|
||||
};
|
||||
assert(
|
||||
'claude FINAL not re-posted when already triggered',
|
||||
!chain.claudeFinalReady([greptile, finalClaude], [], { prCreatedAt: oldPr, requiredWaitMs: 0 }).ready
|
||||
);
|
||||
|
||||
process.exit(failed ? 1 : 0);
|
||||
@@ -1,319 +0,0 @@
|
||||
/**
|
||||
* PR review pipeline: CodeRabbit / Greptile (+ optional Qodo/Gemini) → Claude (FINAL).
|
||||
* Copilot step optional — set REVIEW_CHAIN_SKIP_COPILOT=1 or skipCopilot: true to bypass.
|
||||
* @see .github/workflows/auto-pr-comment.yml
|
||||
*/
|
||||
|
||||
function isSkipCopilot(options = {}) {
|
||||
if (options.skipCopilot === true) return true;
|
||||
if (options.skipCopilot === false) return false;
|
||||
return process.env.REVIEW_CHAIN_SKIP_COPILOT === '1';
|
||||
}
|
||||
|
||||
const COPILOT_TRIGGER_LOGINS = new Set(['MervinPraison', 'github-actions[bot]']);
|
||||
const CLAUDE_TRIGGER_LOGINS = new Set(['MervinPraison', 'github-actions[bot]']);
|
||||
|
||||
const REQUIRED_PRIOR = ['coderabbit', 'greptile'];
|
||||
const OPTIONAL_PRIOR = ['qodo', 'gemini'];
|
||||
const OPTIONAL_PRIOR_WAIT_MS = 20 * 60 * 1000;
|
||||
const REQUIRED_PRIOR_WAIT_MS = 30 * 60 * 1000;
|
||||
|
||||
function loginOf(item) {
|
||||
return (item?.user?.login || '').toLowerCase();
|
||||
}
|
||||
|
||||
function bodyOf(item) {
|
||||
return item?.body || '';
|
||||
}
|
||||
|
||||
function hasCoderabbitSummary(comments) {
|
||||
return comments.some(
|
||||
(c) =>
|
||||
loginOf(c).includes('coderabbit') &&
|
||||
bodyOf(c).toLowerCase().includes('summarize by coderabbit')
|
||||
);
|
||||
}
|
||||
|
||||
function hasGreptileReview(comments) {
|
||||
return comments.some((c) => {
|
||||
if (!loginOf(c).includes('greptile')) return false;
|
||||
const body = bodyOf(c);
|
||||
return body.includes('Greptile Summary') || body.includes('<h3>Greptile Summary</h3>') || body.length > 150;
|
||||
});
|
||||
}
|
||||
|
||||
function hasQodoReview(comments, reviews = []) {
|
||||
if (comments.some((c) => loginOf(c).includes('qodo'))) return true;
|
||||
return reviews.some((r) => loginOf(r).includes('qodo'));
|
||||
}
|
||||
|
||||
function hasGeminiReview(comments, reviews = []) {
|
||||
if (reviews.some((r) => loginOf(r).includes('gemini'))) return true;
|
||||
return comments.some((c) => {
|
||||
if (loginOf(c).includes('gemini')) return true;
|
||||
const body = bodyOf(c);
|
||||
return (
|
||||
body.includes('Review completed by Gemini CLI') ||
|
||||
body.includes('The fix is ready for review. Please test')
|
||||
);
|
||||
});
|
||||
}
|
||||
|
||||
const PRIOR_CHECKS = {
|
||||
coderabbit: (comments) => hasCoderabbitSummary(comments),
|
||||
greptile: (comments) => hasGreptileReview(comments),
|
||||
qodo: (comments, reviews) => hasQodoReview(comments, reviews),
|
||||
gemini: (comments, reviews) => hasGeminiReview(comments, reviews),
|
||||
};
|
||||
|
||||
function priorReviewerStatus(comments, reviews = []) {
|
||||
const status = {};
|
||||
for (const [id, check] of Object.entries(PRIOR_CHECKS)) {
|
||||
status[id] = check(comments, reviews);
|
||||
}
|
||||
return status;
|
||||
}
|
||||
|
||||
function priorReviewersReady(comments, reviews = [], options = {}) {
|
||||
const waitMs = options.optionalWaitMs ?? OPTIONAL_PRIOR_WAIT_MS;
|
||||
const requiredWaitMs = options.requiredWaitMs ?? REQUIRED_PRIOR_WAIT_MS;
|
||||
const prCreatedAt = options.prCreatedAt || null;
|
||||
const status = priorReviewerStatus(comments, reviews);
|
||||
|
||||
const missingRequired = REQUIRED_PRIOR.filter((id) => !status[id]);
|
||||
if (missingRequired.length) {
|
||||
if (prCreatedAt) {
|
||||
const age = Date.now() - new Date(prCreatedAt).getTime();
|
||||
if (age >= requiredWaitMs) {
|
||||
return {
|
||||
ready: true,
|
||||
reason: `required reviewer timeout (${missingRequired.join(', ')} silent after ${Math.round(requiredWaitMs / 60000)}m)`,
|
||||
status,
|
||||
requiredTimeout: true,
|
||||
};
|
||||
}
|
||||
}
|
||||
return { ready: false, reason: `waiting for ${missingRequired.join(', ')}`, status };
|
||||
}
|
||||
|
||||
const missingOptional = OPTIONAL_PRIOR.filter((id) => !status[id]);
|
||||
if (missingOptional.length && prCreatedAt) {
|
||||
const age = Date.now() - new Date(prCreatedAt).getTime();
|
||||
if (age < waitMs) {
|
||||
return {
|
||||
ready: false,
|
||||
reason: `waiting for optional ${missingOptional.join(', ')} (${Math.round((waitMs - age) / 60000)}m left)`,
|
||||
status,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
return { ready: true, reason: '', status };
|
||||
}
|
||||
|
||||
function copilotTriggerComment(comments) {
|
||||
return comments.find(
|
||||
(c) =>
|
||||
bodyOf(c).includes('@copilot') &&
|
||||
COPILOT_TRIGGER_LOGINS.has(c.user?.login) &&
|
||||
!bodyOf(c).toLowerCase().includes('@claude')
|
||||
);
|
||||
}
|
||||
|
||||
function copilotTriggered(comments) {
|
||||
return Boolean(copilotTriggerComment(comments));
|
||||
}
|
||||
|
||||
function copilotReviewReady(comments, reviews = []) {
|
||||
const trigger = copilotTriggerComment(comments);
|
||||
if (!trigger) {
|
||||
return { ready: false, reason: 'copilot not triggered yet' };
|
||||
}
|
||||
const triggerTime = new Date(trigger.created_at).getTime();
|
||||
const copilotComment = comments.some((c) => {
|
||||
if (c === trigger) return false;
|
||||
if (new Date(c.created_at).getTime() < triggerTime) return false;
|
||||
const login = loginOf(c);
|
||||
return (
|
||||
login.includes('copilot') ||
|
||||
c.user?.login === 'Copilot' ||
|
||||
c.user?.login === 'copilot-swe-agent'
|
||||
);
|
||||
});
|
||||
const copilotReview = reviews.some((r) => {
|
||||
if (new Date(r.submitted_at).getTime() < triggerTime) return false;
|
||||
return loginOf(r).includes('copilot');
|
||||
});
|
||||
if (copilotComment || copilotReview) {
|
||||
return { ready: true, reason: '' };
|
||||
}
|
||||
return { ready: false, reason: 'awaiting copilot review' };
|
||||
}
|
||||
|
||||
function isFinalClaudeTriggerComment(c) {
|
||||
const body = bodyOf(c).toLowerCase();
|
||||
if (!CLAUDE_TRIGGER_LOGINS.has(c.user?.login)) return false;
|
||||
if (!body.includes('@claude')) return false;
|
||||
if (body.includes('merge conflict')) return false;
|
||||
return body.includes('final architecture reviewer') || body.includes('lead engineer');
|
||||
}
|
||||
|
||||
function claudeFinalAlreadyTriggered(comments) {
|
||||
return comments.some(isFinalClaudeTriggerComment);
|
||||
}
|
||||
|
||||
function claudeFinalReady(comments, reviews = [], options = {}) {
|
||||
if (!options.allowStaleRepost && claudeFinalAlreadyTriggered(comments)) {
|
||||
return { ready: false, reason: 'claude FINAL already triggered', already: true };
|
||||
}
|
||||
const prior = priorReviewersReady(comments, reviews, options);
|
||||
if (!prior.ready) {
|
||||
return { ready: false, reason: prior.reason };
|
||||
}
|
||||
if (isSkipCopilot(options) || prior.requiredTimeout) {
|
||||
return {
|
||||
ready: true,
|
||||
reason: prior.requiredTimeout ? prior.reason : 'copilot skipped',
|
||||
copilotSkipped: true,
|
||||
requiredTimeout: prior.requiredTimeout,
|
||||
};
|
||||
}
|
||||
const copilot = copilotReviewReady(comments, reviews);
|
||||
if (copilot.ready) {
|
||||
return { ready: true, reason: '' };
|
||||
}
|
||||
if (options.allowCopilotTimeout && copilotTriggered(comments)) {
|
||||
return { ready: true, reason: 'copilot timeout fallback', copilotSkipped: true };
|
||||
}
|
||||
return { ready: false, reason: copilot.reason };
|
||||
}
|
||||
|
||||
/** Post @copilot when prior reviewers are ready, then @claude FINAL when Copilot done (or timeout). */
|
||||
async function advanceReviewChain(github, owner, repo, prNumber, finalBody, core, options = {}) {
|
||||
const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
|
||||
const chainOpts = {
|
||||
prCreatedAt: pr.created_at,
|
||||
optionalWaitMs: options.optionalWaitMs ?? 0,
|
||||
};
|
||||
const copilot = options.skipCopilot
|
||||
? { triggered: false, reason: 'skipped' }
|
||||
: await maybeTriggerCopilot(github, owner, repo, prNumber, core, chainOpts);
|
||||
const claude = await maybeTriggerClaudeFinal(
|
||||
github, owner, repo, prNumber, finalBody, core,
|
||||
{ ...options, ...chainOpts }
|
||||
);
|
||||
return { copilot, claude };
|
||||
}
|
||||
|
||||
async function maybeTriggerClaudeFinal(github, owner, repo, prNumber, finalBody, core, options = {}) {
|
||||
const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
|
||||
const { comments, reviews } = await listCommentsAndReviews(github, owner, repo, prNumber);
|
||||
const gate = claudeFinalReady(comments, reviews, {
|
||||
prCreatedAt: pr.created_at,
|
||||
optionalWaitMs: options.optionalWaitMs,
|
||||
allowCopilotTimeout: options.allowCopilotTimeout !== false,
|
||||
allowStaleRepost: options.allowStaleRepost === true,
|
||||
skipCopilot: options.skipCopilot,
|
||||
});
|
||||
if (!gate.ready) {
|
||||
core?.info?.(`PR #${prNumber}: skip Claude FINAL — ${gate.reason}`);
|
||||
return { posted: false, reason: gate.reason };
|
||||
}
|
||||
await github.rest.issues.createComment({
|
||||
owner,
|
||||
repo,
|
||||
issue_number: prNumber,
|
||||
body: finalBody,
|
||||
});
|
||||
const note = gate.copilotSkipped ? ' (Copilot timeout fallback)' : '';
|
||||
core?.info?.(`Posted Claude FINAL on PR #${prNumber}${note}`);
|
||||
return { posted: true, reason: '' };
|
||||
}
|
||||
|
||||
const COPILOT_REVIEW_BODY =
|
||||
'@copilot Do a thorough review of this PR. Read ALL existing reviewer comments above from Qodo, CodeRabbit, Gemini, and Greptile first — incorporate their findings.\n\nReview areas:\n1. **Bloat check**: Are changes minimal and focused? Any unnecessary code or scope creep?\n2. **Security**: Any hardcoded secrets, unsafe eval/exec, missing input validation?\n3. **Performance**: Any module-level heavy imports? Hot-path regressions?\n4. **Tests**: Are tests included? Do they cover the changes adequately?\n5. **Backward compat**: Any public API changes without deprecation?\n6. **Code quality**: DRY violations, naming conventions, error handling?\n7. **Address reviewer feedback**: If Qodo, CodeRabbit, Gemini, or Greptile flagged valid issues, include them in your review\n8. Suggest specific improvements with code examples where possible';
|
||||
|
||||
async function listCommentsAndReviews(github, owner, repo, prNumber) {
|
||||
let comments;
|
||||
if (typeof github.paginate === 'function') {
|
||||
comments = await github.paginate(github.rest.issues.listComments, {
|
||||
owner,
|
||||
repo,
|
||||
issue_number: prNumber,
|
||||
per_page: 100,
|
||||
});
|
||||
} else {
|
||||
const { data } = await github.rest.issues.listComments({
|
||||
owner,
|
||||
repo,
|
||||
issue_number: prNumber,
|
||||
per_page: 100,
|
||||
});
|
||||
comments = data;
|
||||
}
|
||||
const { data: reviews } = await github.rest.pulls.listReviews({
|
||||
owner,
|
||||
repo,
|
||||
pull_number: prNumber,
|
||||
per_page: 100,
|
||||
});
|
||||
return { comments, reviews };
|
||||
}
|
||||
|
||||
async function maybeTriggerCopilot(github, owner, repo, prNumber, core, options = {}) {
|
||||
const { comments, reviews } = await listCommentsAndReviews(github, owner, repo, prNumber);
|
||||
if (copilotTriggered(comments)) {
|
||||
core?.info?.(`Copilot already triggered on PR #${prNumber}`);
|
||||
return { triggered: false, reason: 'already_triggered' };
|
||||
}
|
||||
const prior = priorReviewersReady(comments, reviews, options);
|
||||
if (!prior.ready) {
|
||||
core?.info?.(`PR #${prNumber}: not ready for Copilot — ${prior.reason}`);
|
||||
return { triggered: false, reason: prior.reason };
|
||||
}
|
||||
await github.rest.issues.createComment({
|
||||
owner,
|
||||
repo,
|
||||
issue_number: prNumber,
|
||||
body: COPILOT_REVIEW_BODY,
|
||||
});
|
||||
core?.info?.(`Posted @copilot on PR #${prNumber} after prior reviewers`);
|
||||
return { triggered: true };
|
||||
}
|
||||
|
||||
async function pollCopilotResponse(github, owner, repo, prNumber, options = {}) {
|
||||
const maxAttempts = options.maxAttempts ?? 20;
|
||||
const delayMs = options.delayMs ?? 30000;
|
||||
for (let i = 0; i < maxAttempts; i += 1) {
|
||||
const { comments, reviews } = await listCommentsAndReviews(github, owner, repo, prNumber);
|
||||
const copilot = copilotReviewReady(comments, reviews);
|
||||
if (copilot.ready) {
|
||||
return { ready: true, reason: '' };
|
||||
}
|
||||
if (i < maxAttempts - 1) {
|
||||
await new Promise((resolve) => setTimeout(resolve, delayMs));
|
||||
}
|
||||
}
|
||||
return { ready: false, reason: 'copilot timeout' };
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
isSkipCopilot,
|
||||
REQUIRED_PRIOR,
|
||||
OPTIONAL_PRIOR,
|
||||
REQUIRED_PRIOR_WAIT_MS,
|
||||
COPILOT_REVIEW_BODY,
|
||||
priorReviewerStatus,
|
||||
priorReviewersReady,
|
||||
copilotTriggered,
|
||||
copilotReviewReady,
|
||||
claudeFinalReady,
|
||||
claudeFinalAlreadyTriggered,
|
||||
isFinalClaudeTriggerComment,
|
||||
maybeTriggerCopilot,
|
||||
maybeTriggerClaudeFinal,
|
||||
advanceReviewChain,
|
||||
pollCopilotResponse,
|
||||
hasGeminiReview,
|
||||
listCommentsAndReviews,
|
||||
};
|
||||
@@ -1,32 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Run: node .github/scripts/release-gate-selftest.js
|
||||
*/
|
||||
const rg = require('./release-gate.js');
|
||||
const config = require('./gate-config.js');
|
||||
|
||||
let failed = 0;
|
||||
function assert(name, cond) {
|
||||
if (!cond) {
|
||||
console.error('FAIL:', name);
|
||||
failed += 1;
|
||||
} else {
|
||||
console.log('ok:', name);
|
||||
}
|
||||
}
|
||||
|
||||
assert('package name is aiui', config.pypiPackageName === 'aiui');
|
||||
assert('bumpPatch works', rg.bumpPatch('0.3.127') === '0.3.128');
|
||||
|
||||
try {
|
||||
const versions = rg.readVersionsFromTree(process.cwd());
|
||||
assert('reads current version', /^\d+\.\d+\.\d+$/.test(versions.current));
|
||||
assert('computes target patch', versions.target === rg.bumpPatch(versions.current));
|
||||
} catch (err) {
|
||||
console.error('FAIL: readVersionsFromTree', err.message);
|
||||
failed += 1;
|
||||
}
|
||||
|
||||
assert('PACKAGE_PATHS includes pyproject', rg.PACKAGE_PATHS.includes('pyproject.toml'));
|
||||
|
||||
process.exit(failed ? 1 : 0);
|
||||
@@ -1,205 +0,0 @@
|
||||
/**
|
||||
* Release gate preflight — path changes, CI SHA, dedupe, PyPI version checks (PraisonAIUI).
|
||||
*/
|
||||
|
||||
const https = require('https');
|
||||
const config = require('./gate-config.js');
|
||||
|
||||
const PACKAGE_PATHS = config.packagePaths;
|
||||
const ACTIVE_RELEASE_STATUSES = new Set([
|
||||
'queued', 'in_progress', 'waiting', 'pending', 'requested',
|
||||
]);
|
||||
|
||||
function bumpPatch(version) {
|
||||
const parts = version.split('.');
|
||||
if (parts.length !== 3) throw new Error(`Invalid version: ${version}`);
|
||||
return `${parts[0]}.${parts[1]}.${Number(parts[2]) + 1}`;
|
||||
}
|
||||
|
||||
function readVersionsFromTree(root = '.') {
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
const toml = fs.readFileSync(path.join(root, 'pyproject.toml'), 'utf8');
|
||||
const match = toml.match(/^version\s*=\s*"([^"]+)"/m);
|
||||
if (!match) throw new Error('Could not read aiui version from pyproject.toml');
|
||||
const current = match[1];
|
||||
const target = bumpPatch(current);
|
||||
return { current, target, packageName: config.pypiPackageName };
|
||||
}
|
||||
|
||||
function pypiVersionExists(packageName, version) {
|
||||
return new Promise((resolve) => {
|
||||
const req = https.get(
|
||||
`https://pypi.org/pypi/${packageName}/${version}/json`,
|
||||
{ timeout: 15000 },
|
||||
(res) => {
|
||||
res.resume();
|
||||
resolve(res.statusCode === 200);
|
||||
}
|
||||
);
|
||||
req.on('error', () => resolve(false));
|
||||
req.on('timeout', () => {
|
||||
req.destroy();
|
||||
resolve(false);
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
async function hasActiveReleaseRun(github, owner, repo) {
|
||||
const runs = await github.rest.actions.listWorkflowRuns({
|
||||
owner,
|
||||
repo,
|
||||
workflow_id: 'pypi-release.yml',
|
||||
per_page: 20,
|
||||
});
|
||||
return runs.data.workflow_runs.some(
|
||||
(r) => ACTIVE_RELEASE_STATUSES.has(r.status) && !r.conclusion
|
||||
);
|
||||
}
|
||||
|
||||
function utcDayStart(now = new Date()) {
|
||||
return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
|
||||
}
|
||||
|
||||
async function hasSuccessfulReleaseToday(github, owner, repo, now = new Date()) {
|
||||
const dayStart = utcDayStart(now);
|
||||
const runs = await github.rest.actions.listWorkflowRuns({
|
||||
owner,
|
||||
repo,
|
||||
workflow_id: 'pypi-release.yml',
|
||||
status: 'completed',
|
||||
per_page: 30,
|
||||
});
|
||||
return runs.data.workflow_runs.some(
|
||||
(r) => r.conclusion === 'success' && new Date(r.created_at) >= dayStart
|
||||
);
|
||||
}
|
||||
|
||||
async function lastGreenCiSha(github, owner, repo) {
|
||||
const runs = await github.rest.actions.listWorkflowRuns({
|
||||
owner,
|
||||
repo,
|
||||
workflow_id: config.ciWorkflowFile,
|
||||
branch: 'main',
|
||||
status: 'completed',
|
||||
per_page: 30,
|
||||
});
|
||||
const hit = runs.data.workflow_runs.find((r) => r.conclusion === 'success');
|
||||
return hit ? hit.head_sha : '';
|
||||
}
|
||||
|
||||
async function evaluateReleasePreflight(github, owner, repo, options, core) {
|
||||
const {
|
||||
headSha,
|
||||
isCiTrigger = false,
|
||||
bump = 'patch',
|
||||
} = options;
|
||||
|
||||
const reasons = [];
|
||||
const out = {
|
||||
ready: false,
|
||||
reasons,
|
||||
headSha: headSha || '',
|
||||
lastTag: '',
|
||||
targetVersion: '',
|
||||
packageName: config.pypiPackageName,
|
||||
};
|
||||
|
||||
if (bump !== 'patch') {
|
||||
reasons.push('only patch auto-release supported');
|
||||
return out;
|
||||
}
|
||||
|
||||
if (await hasActiveReleaseRun(github, owner, repo)) {
|
||||
reasons.push('PyPI Release already in progress or awaiting approval');
|
||||
return out;
|
||||
}
|
||||
|
||||
const referenceTime = options.now instanceof Date ? options.now : new Date();
|
||||
if (await hasSuccessfulReleaseToday(github, owner, repo, referenceTime)) {
|
||||
const day = referenceTime.toISOString().slice(0, 10);
|
||||
reasons.push(`already released today (UTC ${day}); max one patch release per day`);
|
||||
return out;
|
||||
}
|
||||
|
||||
let versions;
|
||||
try {
|
||||
versions = readVersionsFromTree();
|
||||
} catch (err) {
|
||||
reasons.push(err.message);
|
||||
return out;
|
||||
}
|
||||
out.targetVersion = versions.target;
|
||||
|
||||
const onPypi = await pypiVersionExists(config.pypiPackageName, versions.target);
|
||||
if (onPypi) {
|
||||
reasons.push(`already published: ${config.pypiPackageName}==${versions.target}`);
|
||||
return out;
|
||||
}
|
||||
|
||||
const { execSync } = require('child_process');
|
||||
let lastTag = '';
|
||||
try {
|
||||
lastTag = execSync('git describe --tags --match "v*" --abbrev=0', { encoding: 'utf8' }).trim();
|
||||
} catch {
|
||||
reasons.push('no v* tag found');
|
||||
return out;
|
||||
}
|
||||
out.lastTag = lastTag;
|
||||
|
||||
let changed = '';
|
||||
try {
|
||||
changed = execSync(
|
||||
`git diff --name-only ${lastTag} HEAD -- ${PACKAGE_PATHS.join(' ')}`,
|
||||
{ encoding: 'utf8' }
|
||||
).trim();
|
||||
} catch {
|
||||
reasons.push('git diff failed');
|
||||
return out;
|
||||
}
|
||||
|
||||
if (!changed) {
|
||||
reasons.push(`no changes in ${PACKAGE_PATHS.join(' or ')} since ${lastTag}`);
|
||||
return out;
|
||||
}
|
||||
|
||||
if (isCiTrigger) {
|
||||
let mainSha = '';
|
||||
try {
|
||||
mainSha = execSync('git rev-parse origin/main', { encoding: 'utf8' }).trim();
|
||||
} catch {
|
||||
reasons.push('could not resolve origin/main');
|
||||
return out;
|
||||
}
|
||||
if (headSha !== mainSha) {
|
||||
reasons.push(`superseded: green SHA ${headSha.slice(0, 7)} != main ${mainSha.slice(0, 7)}`);
|
||||
return out;
|
||||
}
|
||||
out.headSha = headSha;
|
||||
} else {
|
||||
const evalSha = execSync('git rev-parse HEAD', { encoding: 'utf8' }).trim();
|
||||
out.headSha = evalSha;
|
||||
const greenSha = await lastGreenCiSha(github, owner, repo);
|
||||
if (greenSha !== evalSha) {
|
||||
reasons.push(`CI not green on HEAD (last green: ${greenSha ? greenSha.slice(0, 7) : 'none'})`);
|
||||
return out;
|
||||
}
|
||||
}
|
||||
|
||||
out.ready = true;
|
||||
out.reasons = ['ready'];
|
||||
if (core) core.info(`Release preflight passed for ${out.headSha || headSha}`);
|
||||
return out;
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
bumpPatch,
|
||||
readVersionsFromTree,
|
||||
pypiVersionExists,
|
||||
hasSuccessfulReleaseToday,
|
||||
utcDayStart,
|
||||
evaluateReleasePreflight,
|
||||
lastGreenCiSha,
|
||||
ACTIVE_RELEASE_STATUSES,
|
||||
PACKAGE_PATHS,
|
||||
};
|
||||
@@ -1,95 +0,0 @@
|
||||
name: Auto Issue Comment
|
||||
|
||||
# Automatically escalate every new issue to Claude for a full investigation
|
||||
# + draft fix. Manual re-trigger: workflow_dispatch with issue_number.
|
||||
#
|
||||
# Note: `@claude` mentions only trigger claude.yml when the commenter is a
|
||||
# HUMAN user (or github-actions[bot] via PAT). This workflow posts the
|
||||
# comment as github-actions[bot], so claude.yml must allow that bot.
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
issue_number:
|
||||
description: "Issue number to triage with Claude"
|
||||
required: true
|
||||
type: string
|
||||
issues:
|
||||
types: [opened]
|
||||
|
||||
jobs:
|
||||
# Escalate an issue to full Claude implementation by adding the `claude`
|
||||
# label. claude.yml listens on `issues:labeled` + label=='claude' and
|
||||
# triggers Job 2 (claude-response) which does the actual work.
|
||||
trigger-claude:
|
||||
if: |
|
||||
github.event_name == 'workflow_dispatch' ||
|
||||
github.event_name == 'issues'
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
issues: write
|
||||
actions: write
|
||||
steps:
|
||||
- name: Resolve issue number
|
||||
id: resolve
|
||||
run: |
|
||||
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
|
||||
echo "number=${{ inputs.issue_number }}" >> "$GITHUB_OUTPUT"
|
||||
else
|
||||
echo "number=${{ github.event.issue.number }}" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
|
||||
- name: Add claude label + post instructions
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
github-token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
|
||||
script: |
|
||||
const issueNumber = Number('${{ steps.resolve.outputs.number }}');
|
||||
const { data: issue } = await github.rest.issues.get({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: issueNumber,
|
||||
});
|
||||
|
||||
const labels = (issue.labels || []).map(l => typeof l === 'string' ? l : l.name);
|
||||
const hadClaude = labels.includes('claude');
|
||||
if (!hadClaude) {
|
||||
await github.rest.issues.addLabels({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: issueNumber,
|
||||
labels: ['claude'],
|
||||
});
|
||||
} else {
|
||||
console.log(`Issue #${issueNumber} already has 'claude' label — dispatching Claude only.`);
|
||||
}
|
||||
|
||||
const body = [
|
||||
'🤖 Auto-triaging with Claude.',
|
||||
'',
|
||||
'Claude will:',
|
||||
'',
|
||||
'1. Read this issue and all comments.',
|
||||
'2. Classify and route to the right area (`src/praisonaiui/`, `src/frontend/`, `docs/`, or external repo).',
|
||||
'3. Implement a minimal fix per `AGENTS.md`.',
|
||||
'4. Run `pytest` + the import-time invariant locally.',
|
||||
'5. Open a draft PR linked to this issue.',
|
||||
'',
|
||||
'Follow-ups in this thread with `@claude` will re-trigger the loop.'
|
||||
].join('\n');
|
||||
|
||||
await github.rest.issues.createComment({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: issueNumber,
|
||||
body,
|
||||
});
|
||||
|
||||
await github.rest.actions.createWorkflowDispatch({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
workflow_id: 'claude.yml',
|
||||
ref: 'main',
|
||||
inputs: { issue_number: String(issueNumber) },
|
||||
});
|
||||
console.log(`Dispatched Claude Assistant for issue #${issueNumber}`);
|
||||
@@ -1,33 +0,0 @@
|
||||
name: Auto PR Comment
|
||||
|
||||
on:
|
||||
issue_comment:
|
||||
types: [created]
|
||||
pull_request_review:
|
||||
types: [submitted]
|
||||
pull_request:
|
||||
types: [opened, synchronize]
|
||||
pull_request_target:
|
||||
types: [opened, synchronize]
|
||||
schedule:
|
||||
- cron: '30 * * * *'
|
||||
workflow_dispatch:
|
||||
|
||||
env:
|
||||
REVIEW_CHAIN_SKIP_COPILOT: '1'
|
||||
|
||||
permissions:
|
||||
issues: write
|
||||
pull-requests: write
|
||||
|
||||
jobs:
|
||||
review-chain:
|
||||
# Grant union of callee job permissions (repos with default_workflow_permissions: read
|
||||
# reject reusable calls when the caller ceiling is lower than any callee job).
|
||||
permissions:
|
||||
issues: write
|
||||
pull-requests: write
|
||||
uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
|
||||
secrets: inherit
|
||||
with:
|
||||
hub_ref: v1.1.20
|
||||
@@ -1,23 +0,0 @@
|
||||
name: Bot PR Recovery
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: '*/15 * * * *'
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
pr_number:
|
||||
description: 'Specific PR number to kick (optional)'
|
||||
required: false
|
||||
type: string
|
||||
|
||||
permissions:
|
||||
pull-requests: write
|
||||
issues: write
|
||||
|
||||
jobs:
|
||||
recover:
|
||||
uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
|
||||
secrets: inherit
|
||||
with:
|
||||
hub_ref: v1.1.20
|
||||
pr_number: ${{ github.event.inputs.pr_number || '' }}
|
||||
@@ -1,32 +0,0 @@
|
||||
name: Auto CI Failure → Claude
|
||||
|
||||
on:
|
||||
workflow_run:
|
||||
workflows: [Core Tests, Optimized Test Suite]
|
||||
types: [completed]
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened]
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
pr_number:
|
||||
required: false
|
||||
type: string
|
||||
schedule:
|
||||
- cron: '15 */6 * * *'
|
||||
|
||||
concurrency:
|
||||
group: ci-failure-scan-${{ github.repository }}-${{ github.event.pull_request.number || github.event.workflow_run.id || github.run_id }}
|
||||
cancel-in-progress: true
|
||||
|
||||
permissions:
|
||||
pull-requests: read
|
||||
issues: write
|
||||
actions: read
|
||||
|
||||
jobs:
|
||||
detect-and-trigger:
|
||||
uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
|
||||
secrets: inherit
|
||||
with:
|
||||
hub_ref: v1.1.20
|
||||
pr_number: ${{ github.event.inputs.pr_number || '' }}
|
||||
@@ -1,93 +0,0 @@
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
python:
|
||||
name: python
|
||||
runs-on: ubuntu-latest
|
||||
strategy:
|
||||
matrix:
|
||||
python-version: ["3.10", "3.11", "3.12"]
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Python ${{ matrix.python-version }}
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: ${{ matrix.python-version }}
|
||||
|
||||
- name: Install dependencies
|
||||
run: pip install -e .[dev]
|
||||
|
||||
- name: Lint with ruff
|
||||
run: ruff check src/praisonaiui
|
||||
|
||||
- name: Test with pytest
|
||||
# Unit tests are the primary CI contract; integration smoke validates backends.
|
||||
run: pytest tests/unit -v --no-cov --timeout=60
|
||||
|
||||
- name: Integration smoke tests
|
||||
run: pytest tests/integration/test_agentic_roundtrip.py tests/test_feature_sdk_backends.py -q --no-cov --timeout=120
|
||||
|
||||
frontend:
|
||||
name: frontend
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: "22"
|
||||
cache: npm
|
||||
cache-dependency-path: src/frontend/package-lock.json
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
working-directory: src/frontend
|
||||
|
||||
# `npm run build` is the dashboard ship path: dist/ is synced to
|
||||
# src/praisonaiui/templates/frontend/ (see src/frontend/README.md).
|
||||
- name: Build frontend
|
||||
run: npm run build
|
||||
working-directory: src/frontend
|
||||
|
||||
docs:
|
||||
runs-on: ubuntu-latest
|
||||
if: github.ref == 'refs/heads/main'
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.11"
|
||||
|
||||
- name: Install AIUI
|
||||
run: pip install -e .
|
||||
|
||||
- name: Build docs with AIUI
|
||||
run: |
|
||||
aiui build --output site --minify
|
||||
cp CNAME site/CNAME
|
||||
|
||||
- name: Deploy to GitHub Pages
|
||||
uses: peaceiris/actions-gh-pages@v4
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./site
|
||||
force_orphan: true
|
||||
@@ -1,96 +0,0 @@
|
||||
name: Claude PR Merge Gate
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: '*/10 * * * *'
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
pr_number:
|
||||
required: false
|
||||
type: string
|
||||
merge_method:
|
||||
required: false
|
||||
type: choice
|
||||
default: merge
|
||||
options: [merge, squash, rebase]
|
||||
workflow_run:
|
||||
workflows:
|
||||
- Claude Assistant
|
||||
- Core Tests
|
||||
types: [completed]
|
||||
repository_dispatch:
|
||||
types: [claude-merge-gate]
|
||||
|
||||
concurrency:
|
||||
group: claude-merge-gate-${{ github.repository }}-${{ github.event.inputs.pr_number || github.event.client_payload.pr_number || github.event.workflow_run.id || 'scan' }}
|
||||
cancel-in-progress: false
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: read
|
||||
issues: read
|
||||
actions: read
|
||||
|
||||
jobs:
|
||||
auto-dispatch:
|
||||
if: github.event_name == 'workflow_run'
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: read
|
||||
issues: read
|
||||
actions: write
|
||||
id-token: write
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: MervinPraison/github-automation-template/.github/actions/[email protected]
|
||||
with:
|
||||
hub_ref: v1.1.20
|
||||
- name: Generate GitHub App token
|
||||
id: app-token
|
||||
uses: actions/create-github-app-token@v1
|
||||
with:
|
||||
app-id: ${{ secrets.CLAUDE_APP_ID }}
|
||||
private-key: ${{ secrets.CLAUDE_APP_PRIVATE_KEY }}
|
||||
owner: ${{ github.repository_owner }}
|
||||
- name: Dispatch merge gate when PR pipeline is ready
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
github-token: ${{ steps.app-token.outputs.token }}
|
||||
script: |
|
||||
const path = require('path');
|
||||
const mergeGate = require(path.join(process.env.HUB_SCRIPTS, 'merge-gate.js'));
|
||||
const wr = context.payload.workflow_run;
|
||||
const owner = context.repo.owner;
|
||||
const repo = context.repo.repo;
|
||||
if (wr.conclusion !== 'success') return;
|
||||
const allowed = ['Claude Assistant', 'Core Tests'];
|
||||
if (!allowed.includes(wr.name)) return;
|
||||
const prNumber = await mergeGate.resolvePrNumberFromWorkflowRun(github, owner, repo, wr);
|
||||
if (!prNumber) return;
|
||||
const fromClaude = wr.name === 'Claude Assistant';
|
||||
const check = await mergeGate.evaluatePipelineQuiescent(github, owner, repo, prNumber, core, {
|
||||
skipGlobalClaudeRunCheck: fromClaude,
|
||||
skipRecentClaudeCooldown: fromClaude,
|
||||
});
|
||||
if (!check.ready) return;
|
||||
await github.rest.repos.createDispatchEvent({
|
||||
owner, repo, event_type: 'claude-merge-gate',
|
||||
client_payload: { pr_number: prNumber },
|
||||
});
|
||||
|
||||
merge-gate:
|
||||
if: github.event_name != 'workflow_run'
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: write
|
||||
issues: write
|
||||
actions: read
|
||||
id-token: write
|
||||
statuses: write # the assess job records security/outsider-review
|
||||
uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
|
||||
secrets: inherit
|
||||
with:
|
||||
hub_ref: v1.1.20
|
||||
pr_number: ${{ github.event.inputs.pr_number || github.event.client_payload.pr_number || '' }}
|
||||
merge_method: ${{ github.event.inputs.merge_method || 'merge' }}
|
||||
@@ -1,24 +0,0 @@
|
||||
name: Claude Assistant
|
||||
|
||||
on:
|
||||
issue_comment:
|
||||
types: [created]
|
||||
pull_request_review_comment:
|
||||
types: [created]
|
||||
issues:
|
||||
types: [assigned, labeled, opened]
|
||||
pull_request_review:
|
||||
types: [submitted]
|
||||
|
||||
jobs:
|
||||
claude:
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: write
|
||||
issues: write
|
||||
actions: read
|
||||
id-token: write
|
||||
uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
|
||||
secrets: inherit
|
||||
with:
|
||||
hub_ref: v1.1.20
|
||||
@@ -1,41 +0,0 @@
|
||||
name: Deploy Docs
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
concurrency:
|
||||
group: deploy-docs
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.11"
|
||||
|
||||
- name: Install AIUI
|
||||
run: pip install -e .
|
||||
|
||||
- name: Build docs with AIUI
|
||||
run: |
|
||||
aiui build --output site --minify
|
||||
cp CNAME site/CNAME
|
||||
|
||||
- name: Deploy to GitHub Pages
|
||||
uses: peaceiris/actions-gh-pages@v4
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./site
|
||||
force_orphan: true
|
||||
@@ -1,52 +0,0 @@
|
||||
name: Auto Merge Conflict → Claude
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened]
|
||||
workflow_dispatch:
|
||||
schedule:
|
||||
- cron: '0 */6 * * *'
|
||||
|
||||
concurrency:
|
||||
group: merge-conflict-scan-${{ github.repository }}-${{ github.event.pull_request.number || github.run_id }}
|
||||
cancel-in-progress: true
|
||||
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GH_TOKEN || github.token }}
|
||||
|
||||
permissions:
|
||||
pull-requests: write
|
||||
issues: write
|
||||
|
||||
jobs:
|
||||
detect-and-trigger:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: MervinPraison/github-automation-template/.github/actions/[email protected]
|
||||
with:
|
||||
hub_ref: v1.1.20
|
||||
- name: Detect conflicting PRs and trigger Claude
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
github-token: ${{ env.GH_TOKEN }}
|
||||
script: |
|
||||
const path = require('path');
|
||||
const mg = require(path.join(process.env.HUB_SCRIPTS, 'merge-gate.js'));
|
||||
const owner = context.repo.owner;
|
||||
const repo = context.repo.repo;
|
||||
const baseRepo = `${owner}/${repo}`;
|
||||
const prs = await github.paginate(github.rest.pulls.list, { owner, repo, state: 'open', per_page: 50 });
|
||||
for (const pr of prs) {
|
||||
if (pr.draft) continue;
|
||||
if (pr.head?.repo?.full_name !== baseRepo) continue;
|
||||
const state = await mg.getMergeState(github, owner, repo, pr.number);
|
||||
if (state.status !== 'DIRTY') continue;
|
||||
const { data: comments } = await github.rest.issues.listComments({ owner, repo, issue_number: pr.number, per_page: 100 });
|
||||
if (mg.hasRecentConflictComment(comments)) continue;
|
||||
const body = '@claude this PR has merge conflicts with `main`. Rebase onto latest main, resolve conflicts, run tests, force-push with --force-with-lease.';
|
||||
await github.rest.issues.createComment({ owner, repo, issue_number: pr.number, body });
|
||||
await github.rest.issues.addLabels({ owner, repo, issue_number: pr.number, labels: ['claude-conflict-pending'] });
|
||||
}
|
||||
@@ -1,129 +0,0 @@
|
||||
name: Nightly Release Gate
|
||||
|
||||
# Preflight before PyPI Release (patch bump).
|
||||
# Primary: CI success on main (workflow_run).
|
||||
# Backstop: nightly cron at 00:00 UTC.
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: '0 0 * * *'
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
dry_run:
|
||||
description: 'Run preflight only; do not dispatch pypi-release.yml'
|
||||
required: false
|
||||
default: false
|
||||
type: boolean
|
||||
workflow_run:
|
||||
workflows:
|
||||
- CI
|
||||
types:
|
||||
- completed
|
||||
branches:
|
||||
- main
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
actions: write
|
||||
|
||||
concurrency:
|
||||
group: nightly-release-gate
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
preflight:
|
||||
if: |
|
||||
github.event_name == 'workflow_dispatch' ||
|
||||
github.event_name == 'schedule' ||
|
||||
(
|
||||
github.event_name == 'workflow_run' &&
|
||||
github.event.workflow_run.conclusion == 'success' &&
|
||||
github.event.workflow_run.head_branch == 'main' &&
|
||||
github.event.workflow_run.event == 'push'
|
||||
)
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GH_TOKEN }}
|
||||
steps:
|
||||
- name: Resolve trigger context
|
||||
id: ctx
|
||||
run: |
|
||||
if [ "${{ github.event_name }}" = "workflow_run" ]; then
|
||||
echo "checkout_sha=${{ github.event.workflow_run.head_sha }}" >> "$GITHUB_OUTPUT"
|
||||
echo "source=ci" >> "$GITHUB_OUTPUT"
|
||||
echo "is_ci=true" >> "$GITHUB_OUTPUT"
|
||||
else
|
||||
echo "checkout_sha=main" >> "$GITHUB_OUTPUT"
|
||||
echo "source=nightly" >> "$GITHUB_OUTPUT"
|
||||
echo "is_ci=false" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
|
||||
- name: Checkout
|
||||
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
with:
|
||||
ref: ${{ steps.ctx.outputs.checkout_sha }}
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Fetch main and tags
|
||||
run: git fetch --tags origin main
|
||||
|
||||
- name: Preflight — path changes, CI SHA, dedupe
|
||||
id: preflight
|
||||
uses: actions/github-script@v7
|
||||
env:
|
||||
HEAD_SHA: ${{ steps.ctx.outputs.checkout_sha }}
|
||||
IS_CI: ${{ steps.ctx.outputs.is_ci }}
|
||||
with:
|
||||
github-token: ${{ secrets.GH_TOKEN }}
|
||||
script: |
|
||||
const path = require('path');
|
||||
const rg = require(path.join(process.env.GITHUB_WORKSPACE, '.github/scripts/release-gate.js'));
|
||||
const owner = context.repo.owner;
|
||||
const repo = context.repo.repo;
|
||||
const headSha = process.env.HEAD_SHA;
|
||||
const isCi = process.env.IS_CI === 'true';
|
||||
|
||||
const result = await rg.evaluateReleasePreflight(
|
||||
github, owner, repo,
|
||||
{ headSha, isCiTrigger: isCi, bump: 'patch' },
|
||||
core
|
||||
);
|
||||
|
||||
core.setOutput('should_release', result.ready ? 'true' : 'false');
|
||||
core.setOutput('reason', result.reasons.join('; '));
|
||||
core.setOutput('head_sha', result.headSha || headSha);
|
||||
core.setOutput('last_tag', result.lastTag || '');
|
||||
core.setOutput('target_version', result.targetVersion || '');
|
||||
|
||||
core.summary.addRaw('## Release gate preflight\n');
|
||||
core.summary.addRaw(`Ready: ${result.ready}\n`);
|
||||
core.summary.addRaw(`Reason: ${result.reasons.join('; ')}\n`);
|
||||
if (result.targetVersion) {
|
||||
core.summary.addRaw(`Target: aiui==${result.targetVersion}\n`);
|
||||
}
|
||||
await core.summary.write();
|
||||
|
||||
if (!result.ready) {
|
||||
core.info(`Skip release: ${result.reasons.join('; ')}`);
|
||||
}
|
||||
|
||||
- name: Dry run summary
|
||||
if: inputs.dry_run == true
|
||||
run: |
|
||||
echo "Dry run — preflight only, no pypi-release dispatch."
|
||||
echo "should_release=${{ steps.preflight.outputs.should_release }}"
|
||||
echo "reason=${{ steps.preflight.outputs.reason }}"
|
||||
|
||||
- name: Dispatch PyPI Release (patch)
|
||||
if: steps.preflight.outputs.should_release == 'true' && inputs.dry_run != true
|
||||
run: |
|
||||
set -euo pipefail
|
||||
gh workflow run pypi-release.yml \
|
||||
--repo "${GITHUB_REPOSITORY}" \
|
||||
--ref main \
|
||||
-f bump=patch \
|
||||
-f source=${{ steps.ctx.outputs.source }} \
|
||||
-f trigger_sha=${{ steps.preflight.outputs.head_sha }} \
|
||||
-f dry_run=false
|
||||
echo "Dispatched pypi-release.yml (patch, source=${{ steps.ctx.outputs.source }})"
|
||||
echo "Uses pypi-auto environment for ci/nightly patch releases."
|
||||
@@ -1,19 +0,0 @@
|
||||
name: Pipeline Status Sync
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: '*/10 * * * *'
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
pull-requests: read
|
||||
issues: write
|
||||
actions: write
|
||||
id-token: write
|
||||
|
||||
jobs:
|
||||
sync:
|
||||
uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
|
||||
secrets: inherit
|
||||
with:
|
||||
hub_ref: v1.1.20
|
||||
@@ -1,232 +0,0 @@
|
||||
name: PyPI Release
|
||||
|
||||
# Requires GitHub Environment "pypi" (manual) or "pypi-auto" (ci/nightly patch).
|
||||
# Secrets: PYPI_TOKEN (or PYPI_API_TOKEN), GH_TOKEN
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
bump:
|
||||
description: 'Version bump type for aiui'
|
||||
required: true
|
||||
default: patch
|
||||
type: choice
|
||||
options:
|
||||
- patch
|
||||
- minor
|
||||
- major
|
||||
dry_run:
|
||||
description: 'Preview versions and steps without publishing or pushing'
|
||||
required: false
|
||||
default: false
|
||||
type: boolean
|
||||
version:
|
||||
description: 'Override version (empty = auto bump from pyproject.toml)'
|
||||
required: false
|
||||
default: ''
|
||||
type: string
|
||||
source:
|
||||
description: 'Trigger source (audit trail)'
|
||||
required: false
|
||||
default: manual
|
||||
type: string
|
||||
trigger_sha:
|
||||
description: 'SHA that triggered this release'
|
||||
required: false
|
||||
default: ''
|
||||
type: string
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
concurrency:
|
||||
group: pypi-release
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
release:
|
||||
if: github.ref == 'refs/heads/main'
|
||||
runs-on: ubuntu-latest
|
||||
environment: >-
|
||||
${{
|
||||
(inputs.source == 'ci' || inputs.source == 'nightly') &&
|
||||
inputs.bump == 'patch' &&
|
||||
'pypi-auto' || 'pypi'
|
||||
}}
|
||||
env:
|
||||
UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN || secrets.PYPI_API_TOKEN }}
|
||||
GH_TOKEN: ${{ secrets.GH_TOKEN }}
|
||||
PACKAGE: aiui
|
||||
steps:
|
||||
- name: Release audit
|
||||
run: |
|
||||
echo "Source: ${{ inputs.source }}"
|
||||
echo "Trigger SHA: ${{ inputs.trigger_sha }}"
|
||||
echo "Bump: ${{ inputs.bump }}"
|
||||
echo "Environment: ${{ (inputs.source == 'ci' || inputs.source == 'nightly') && inputs.bump == 'patch' && 'pypi-auto' || 'pypi' }}"
|
||||
|
||||
- name: Checkout main
|
||||
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
with:
|
||||
ref: main
|
||||
fetch-depth: 0
|
||||
token: ${{ secrets.GH_TOKEN }}
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
|
||||
with:
|
||||
python-version: '3.11'
|
||||
|
||||
- name: Set up uv
|
||||
uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
|
||||
|
||||
- name: Configure git
|
||||
run: |
|
||||
git config user.name "MervinPraison"
|
||||
git config user.email "[email protected]"
|
||||
gh auth setup-git
|
||||
|
||||
- name: Compute release version
|
||||
id: versions
|
||||
env:
|
||||
BUMP: ${{ inputs.bump }}
|
||||
VERSION_OVERRIDE: ${{ inputs.version }}
|
||||
run: |
|
||||
python <<'PY'
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
SEMVER = re.compile(r"^\d+\.\d+\.\d+$")
|
||||
bump = os.environ["BUMP"]
|
||||
override = os.environ.get("VERSION_OVERRIDE", "").strip()
|
||||
|
||||
def bump_version(version: str) -> str:
|
||||
parts = version.split(".")
|
||||
if len(parts) != 3:
|
||||
print(f"Invalid version: {version}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
maj, min_, patch = (int(parts[0]), int(parts[1]), int(parts[2]))
|
||||
if bump == "major":
|
||||
return f"{maj + 1}.0.0"
|
||||
if bump == "minor":
|
||||
return f"{maj}.{min_ + 1}.0"
|
||||
return f"{maj}.{min_}.{patch + 1}"
|
||||
|
||||
pyproject = Path("pyproject.toml")
|
||||
content = pyproject.read_text()
|
||||
match = re.search(r'^version\s*=\s*"([^"]+)"', content, re.MULTILINE)
|
||||
if not match:
|
||||
print("Could not read version from pyproject.toml", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
current = match.group(1)
|
||||
if not SEMVER.match(current):
|
||||
print(f"Invalid current version: {current}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
if override:
|
||||
if not SEMVER.match(override):
|
||||
print(f"Invalid version override: {override}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
new_version = override
|
||||
else:
|
||||
new_version = bump_version(current)
|
||||
|
||||
with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as fh:
|
||||
fh.write(f"current_version={current}\n")
|
||||
fh.write(f"new_version={new_version}\n")
|
||||
print(f"aiui: {current} -> {new_version}")
|
||||
PY
|
||||
|
||||
- name: Dry run summary
|
||||
if: inputs.dry_run
|
||||
run: |
|
||||
echo "Dry run — no publish, commit, or push."
|
||||
echo "Package: ${{ env.PACKAGE }}"
|
||||
echo "Version: ${{ steps.versions.outputs.current_version }} -> ${{ steps.versions.outputs.new_version }}"
|
||||
echo "Would: bump pyproject.toml + __version__.py, uv publish, commit, tag, GitHub release"
|
||||
|
||||
- name: Bump version files
|
||||
if: inputs.dry_run != true
|
||||
env:
|
||||
CURRENT: ${{ steps.versions.outputs.current_version }}
|
||||
NEW_VERSION: ${{ steps.versions.outputs.new_version }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
python <<'PY'
|
||||
import os
|
||||
import re
|
||||
from pathlib import Path
|
||||
|
||||
current = os.environ["CURRENT"]
|
||||
new = os.environ["NEW_VERSION"]
|
||||
|
||||
pyproject = Path("pyproject.toml")
|
||||
content = pyproject.read_text()
|
||||
pyproject.write_text(content.replace(f'version = "{current}"', f'version = "{new}"', 1))
|
||||
|
||||
version_py = Path("src/praisonaiui/__version__.py")
|
||||
vcontent = version_py.read_text()
|
||||
version_py.write_text(re.sub(
|
||||
r'__version__ = "[^"]+"',
|
||||
f'__version__ = "{new}"',
|
||||
vcontent,
|
||||
count=1,
|
||||
))
|
||||
PY
|
||||
|
||||
- name: Publish aiui to PyPI
|
||||
if: inputs.dry_run != true
|
||||
run: |
|
||||
set -euo pipefail
|
||||
rm -rf dist
|
||||
uv lock
|
||||
uv build
|
||||
uv publish
|
||||
|
||||
- name: Wait for aiui on PyPI
|
||||
if: inputs.dry_run != true
|
||||
run: |
|
||||
set -euo pipefail
|
||||
VERSION="${{ steps.versions.outputs.new_version }}"
|
||||
MAX_WAIT=600
|
||||
INTERVAL=30
|
||||
START=$(date +%s)
|
||||
|
||||
while true; do
|
||||
if curl -fsSL "https://pypi.org/pypi/${PACKAGE}/${VERSION}/json" >/dev/null; then
|
||||
echo "✅ ${PACKAGE}==${VERSION} is available on PyPI"
|
||||
exit 0
|
||||
fi
|
||||
ELAPSED=$(( $(date +%s) - START ))
|
||||
if [ "$ELAPSED" -ge "$MAX_WAIT" ]; then
|
||||
echo "❌ Timeout waiting for ${PACKAGE}==${VERSION} on PyPI"
|
||||
exit 1
|
||||
fi
|
||||
echo "⏳ Waiting for ${PACKAGE}==${VERSION} ($(( MAX_WAIT - ELAPSED ))s remaining...)"
|
||||
sleep "$INTERVAL"
|
||||
done
|
||||
|
||||
- name: Commit, tag, and release
|
||||
if: inputs.dry_run != true
|
||||
env:
|
||||
VERSION: ${{ steps.versions.outputs.new_version }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
TAG="v${VERSION}"
|
||||
git add pyproject.toml uv.lock src/praisonaiui/__version__.py
|
||||
git diff --cached --quiet && { echo "No version files to commit"; exit 0; }
|
||||
git commit -m "Release ${TAG}"
|
||||
git tag -f "${TAG}"
|
||||
git pull --rebase origin main
|
||||
git tag -f "${TAG}"
|
||||
git push origin main
|
||||
git push --tags -f
|
||||
gh release create "${TAG}" \
|
||||
--title "PraisonAIUI ${TAG}" \
|
||||
--notes "Release ${TAG}" \
|
||||
--latest
|
||||
|
||||
- name: Verify release
|
||||
if: inputs.dry_run != true
|
||||
run: echo "✅ ${{ env.PACKAGE }}==${{ steps.versions.outputs.new_version }}"
|
||||
@@ -1,33 +0,0 @@
|
||||
name: Sync Claude Secrets from PraisonAI
|
||||
|
||||
# GitHub does not allow reading secret values back via API.
|
||||
# This workflow triggers the sync job in MervinPraison/PraisonAI, which copies:
|
||||
# CLAUDE_APP_ID, CLAUDE_APP_PRIVATE_KEY, CLAUDE_CODE_OAUTH_TOKEN, GH_TOKEN
|
||||
#
|
||||
# Requires SECRETS_ADMIN_PAT in PraisonAI (repo Settings → Secrets).
|
||||
# If sync fails, copy secrets manually:
|
||||
# PraisonAI → Settings → Secrets → Actions
|
||||
# PraisonAIUI → Settings → Secrets → Actions (same names)
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
trigger-sync:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Trigger PraisonAI secret sync
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
run: |
|
||||
gh workflow run sync-secrets-to-aiui.yml \
|
||||
--repo MervinPraison/PraisonAI \
|
||||
--ref main \
|
||||
-f target_repo=MervinPraison/PraisonAIUI
|
||||
echo "Triggered: https://github.com/MervinPraison/PraisonAI/actions/workflows/sync-secrets-to-aiui.yml"
|
||||
echo ""
|
||||
echo "If sync fails (401/403), refresh SECRETS_ADMIN_PAT in PraisonAI,"
|
||||
echo "or copy CLAUDE_APP_ID + CLAUDE_APP_PRIVATE_KEY + GH_TOKEN manually."
|
||||
-60
@@ -1,60 +0,0 @@
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
.venv/
|
||||
venv/
|
||||
env/
|
||||
build/
|
||||
dist/
|
||||
*.egg-info/
|
||||
.pytest_cache/
|
||||
.coverage
|
||||
coverage.xml
|
||||
htmlcov/
|
||||
.mypy_cache/
|
||||
.ruff_cache/
|
||||
|
||||
# JavaScript / Node
|
||||
node_modules/
|
||||
.next/
|
||||
dist/
|
||||
.npm/
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
pnpm-lock.yaml
|
||||
*.tsbuildinfo
|
||||
|
||||
# Environment
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Project specific
|
||||
aiui/
|
||||
*.log
|
||||
*.err
|
||||
.praison/
|
||||
.gemini/
|
||||
.internal/
|
||||
|
||||
# Generated
|
||||
site/
|
||||
docs/_build/
|
||||
aiui-output/
|
||||
_site
|
||||
|
||||
.praisonai
|
||||
tmp/
|
||||
*.db
|
||||
File renamed without changes.
@@ -1,375 +0,0 @@
|
||||
---
|
||||
description: Comprehensive analysis workflow that produces a detailed GitHub issue — combines deep codebase analysis with issue creation for implementation-ready tickets
|
||||
---
|
||||
|
||||
# Analysis → GitHub Issue Workflow
|
||||
|
||||
Deep Analysis → Gap Analysis → Critical Review → Plan → Create GitHub Issue.
|
||||
|
||||
> **When to use this:** You need to analyze a feature, integration, or system deeply and produce a GitHub issue that another agent/developer can implement immediately without asking follow-up questions.
|
||||
> **When NOT to use this:** Use `/analysis` for analysis-only (no issue). Use `/local-fix` if you're implementing yourself.
|
||||
|
||||
---
|
||||
|
||||
## PRINCIPLES (apply throughout)
|
||||
|
||||
- **Agent-centric**: Agents, workflows, sessions, tools, memory, multi-agent safety.
|
||||
- **Protocol-driven core**: praisonaiagents = lightweight, protocol-first (protocols/hooks/adapters only).
|
||||
- **DRY**: identify reuse; avoid duplication.
|
||||
- **No perf impact**: preserve import-time and hot-path; heavy deps optional + lazy.
|
||||
- **Async-safe + multi-agent safe** by default.
|
||||
- **Easy for non-developers**: "Few lines of code to do the task!"
|
||||
- **No competitor names in public surfaces**: Never mention competitor product, company, or project names in GitHub issues, PRs, commit messages, release notes, docs, or any other public-facing content. Refer to capabilities generically (e.g., "self-improving agent pattern", "external agent framework").
|
||||
|
||||
---
|
||||
|
||||
## CANONICAL PATHS
|
||||
|
||||
```
|
||||
UI Repo: /Users/praison/praisonaiui (praisonaiui)
|
||||
SDK Core: /Users/praison/praisonai-package/src/praisonai-agents (praisonaiagents)
|
||||
Docs: /Users/praison/PraisonAIDocs
|
||||
Extension: src/praisonaiui/*, docs/*, tests/*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Acceptance Criteria
|
||||
|
||||
Translate the request into testable criteria:
|
||||
- API expectations (classes, methods, signatures)
|
||||
- CLI expectations (commands, flags, help text)
|
||||
- Documentation expectations (pages, examples)
|
||||
- Test expectations (unit, integration, smoke, real agentic)
|
||||
- Performance constraints (import time, hot-path)
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — External Research (if applicable)
|
||||
|
||||
### 2a. Read official sources
|
||||
|
||||
If analyzing an external integration, research from primary sources:
|
||||
|
||||
```bash
|
||||
# Use read_url_content tool for:
|
||||
# - Official site / announcement pages
|
||||
# - GitHub README and docs
|
||||
# - Framework documentation
|
||||
# - Third-party write-ups
|
||||
```
|
||||
|
||||
**Capture:**
|
||||
- What is it? Purpose and design goals
|
||||
- Key terminology and concepts
|
||||
- Architecture overview
|
||||
- Current ecosystem state
|
||||
- References list (all URLs)
|
||||
|
||||
### 2b. Clone & analyze external codebase (if applicable)
|
||||
|
||||
```bash
|
||||
git clone <repo-url> ~/<repo-name> --depth=1
|
||||
ls -la ~/<repo-name>/
|
||||
```
|
||||
|
||||
Key files to read:
|
||||
- `AGENTS.md` / `README.md` — architecture overview
|
||||
- Base class files (abstract methods, signatures)
|
||||
- Factory / registry files (registration pattern)
|
||||
- Model/config files (data structures)
|
||||
- Example implementations (minimal + full-featured)
|
||||
- `pyproject.toml` / `package.json` — dependencies
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — PraisonAI Codebase Inventory
|
||||
|
||||
### 3a. Inventory with evidence
|
||||
|
||||
Go through ALL relevant files, understand current logic end-to-end.
|
||||
|
||||
```bash
|
||||
# UI repo
|
||||
ls /Users/praison/praisonaiui/src/praisonaiui/
|
||||
ls /Users/praison/praisonaiui/tests/
|
||||
ls /Users/praison/praisonaiui/docs/
|
||||
|
||||
# Optional cross-check against SDK only when needed
|
||||
ls /Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/
|
||||
```
|
||||
|
||||
**Document:**
|
||||
- Public APIs: modules/classes/functions and exports
|
||||
- Protocols/adapters/hooks and extension points
|
||||
- CLI commands, options, help text
|
||||
- Integrations (db/observability/tools)
|
||||
- Tests (unit/integration), fixtures, CI config
|
||||
- Docs (Mintlify), examples, recipes
|
||||
|
||||
Provide: **file paths + key symbols + grep counts + entry points**.
|
||||
|
||||
### 3b. Identify DRY opportunities
|
||||
|
||||
- Existing abstractions that can be reused
|
||||
- Duplicated code that should be consolidated
|
||||
- Existing protocols before creating new ones
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Detailed Analysis
|
||||
|
||||
### 4a. Architecture and behavior
|
||||
|
||||
- Control flow and data flow
|
||||
- Concurrency model (sync/async)
|
||||
- Multi-agent interactions
|
||||
- Dependency boundaries (core/wrapper/tools)
|
||||
- Failure modes and error handling
|
||||
|
||||
### 4b. Invariants check
|
||||
|
||||
Verify these are preserved:
|
||||
- [ ] Protocol-driven core (no heavy impls in praisonaiagents)
|
||||
- [ ] Lazy imports (optional deps never at module level)
|
||||
- [ ] Backward compatible (public API changes need deprecation)
|
||||
- [ ] Safe defaults (new features opt-in)
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Gap Analysis
|
||||
|
||||
Compare acceptance criteria vs current state.
|
||||
|
||||
### Checklist
|
||||
|
||||
| Area | Current State | Gap | Severity | Impact | Placement |
|
||||
|------|---------------|-----|----------|--------|-----------|
|
||||
| Core SDK | | | | | |
|
||||
| Wrapper | | | | | |
|
||||
| Tools/plugins | | | | | |
|
||||
| CLI | | | | | |
|
||||
| Docs | | | | | |
|
||||
| Tests | | | | | |
|
||||
| Exports | | | | | |
|
||||
| Perf | | | | | |
|
||||
| Multi-agent + async | | | | | |
|
||||
|
||||
### Gap severity levels
|
||||
- **Critical**: Blocks functionality
|
||||
- **High**: Significant limitation
|
||||
- **Medium**: Missing feature
|
||||
- **Low**: Nice-to-have
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — Critical Review
|
||||
|
||||
### 6a. Risks and footguns
|
||||
|
||||
- API ambiguity or edge cases
|
||||
- Backward compatibility concerns
|
||||
- Coupling violations
|
||||
- Performance regressions
|
||||
- Concurrency hazards
|
||||
- Misuse risks
|
||||
- Operational concerns
|
||||
|
||||
### 6b. Mitigation strategies
|
||||
|
||||
For each risk, document:
|
||||
- "Safe by default" recommendation
|
||||
- Explicit opt-in for dangerous behavior
|
||||
- Documentation warnings
|
||||
|
||||
---
|
||||
|
||||
## Phase 7 — Implementation Plan
|
||||
|
||||
Step-by-step plan (DO NOT implement):
|
||||
|
||||
### 7a. Test-first (TDD)
|
||||
|
||||
1. Unit tests for new functionality
|
||||
2. Integration tests for cross-component behavior
|
||||
3. Smoke tests for quick validation
|
||||
4. **Real agentic tests** (REQUIRED):
|
||||
```python
|
||||
from praisonaiagents import Agent
|
||||
agent = Agent(name="test", instructions="You are helpful")
|
||||
result = agent.start("Say hello in one sentence")
|
||||
print(result) # Must call LLM and produce response
|
||||
```
|
||||
|
||||
### 7b. Implementation order
|
||||
|
||||
1. Tests (TDD)
|
||||
2. Core implementation
|
||||
3. CLI integration
|
||||
4. Documentation
|
||||
5. Verification
|
||||
|
||||
### 7c. Files to change/create
|
||||
|
||||
| File | Action | Purpose |
|
||||
|------|--------|---------|
|
||||
| | | |
|
||||
|
||||
### 7d. Verification commands
|
||||
|
||||
```bash
|
||||
# Unit tests
|
||||
pytest tests/unit/test_<feature>.py -v
|
||||
|
||||
# Integration tests
|
||||
pytest tests/integration/test_<feature>.py -v
|
||||
|
||||
# Smoke test
|
||||
python -c "from praisonaiagents import <Feature>; print('OK')"
|
||||
|
||||
# Real agentic test
|
||||
python examples/<feature>_example.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 8 — Draft GitHub Issue
|
||||
|
||||
The issue must be **self-contained**. Another agent must be able to implement by reading only the issue.
|
||||
|
||||
### Required sections
|
||||
|
||||
```markdown
|
||||
## Overview
|
||||
One paragraph: what, why, and the end goal.
|
||||
|
||||
## Background
|
||||
- Purpose and design goals
|
||||
- Why this is valuable
|
||||
- Current state / ecosystem
|
||||
|
||||
## Architecture Analysis
|
||||
### Current Implementation
|
||||
- Key files and their purposes
|
||||
- Integration points
|
||||
- Data flow
|
||||
|
||||
### Key File Locations
|
||||
| File | Purpose | Lines |
|
||||
|------|---------|-------|
|
||||
|
||||
## Gap Analysis Summary
|
||||
### Critical Gaps
|
||||
| Gap | Impact | Effort |
|
||||
|-----|--------|--------|
|
||||
|
||||
### Feature Gaps
|
||||
| Feature | Current Support | Gap |
|
||||
|---------|-----------------|-----|
|
||||
|
||||
## Proposed Implementation
|
||||
### Phase 1: Minimal
|
||||
Working code example.
|
||||
|
||||
### Phase 2: Production
|
||||
Working code example.
|
||||
|
||||
## Files to Create / Modify
|
||||
### New files
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
|
||||
### Modified files
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
|
||||
## Technical Considerations
|
||||
- Dependencies
|
||||
- Performance impact
|
||||
- Safety / approval
|
||||
- Multi-agent safety
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Verifiable checkbox list
|
||||
|
||||
## Implementation Notes
|
||||
### Key Files to Read First
|
||||
1. `path/to/file.py` (N lines) — purpose
|
||||
|
||||
### Critical Integration Points
|
||||
1. Where X connects to Y
|
||||
|
||||
### Testing Commands
|
||||
```bash
|
||||
# Copy-pastable commands
|
||||
```
|
||||
|
||||
## References
|
||||
- [Link](url)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 9 — Create GitHub Issue
|
||||
|
||||
### 9a. Create via `gh` CLI
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--repo MervinPraison/PraisonAIUI \
|
||||
--title "<Type>: <Descriptive Title>" \
|
||||
--body "<issue body>"
|
||||
```
|
||||
|
||||
**Title formats:**
|
||||
- `Feature: <What>` — new functionality
|
||||
- `Analysis: <Topic>` — analysis/research
|
||||
- `Integration: <External System>` — external integration
|
||||
- `Fix: <Problem>` — bug fix proposal
|
||||
|
||||
### 9b. Verify issue created
|
||||
|
||||
```bash
|
||||
gh issue view <number> --repo MervinPraison/PraisonAIUI | head -20
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist — Before Creating Issue
|
||||
|
||||
- [ ] Acceptance criteria defined and testable
|
||||
- [ ] All relevant PraisonAI files read (not skimmed)
|
||||
- [ ] External sources researched (if applicable)
|
||||
- [ ] Gap analysis completed with severity ratings
|
||||
- [ ] Critical review identifies risks and mitigations
|
||||
- [ ] Implementation plan is step-by-step with file list
|
||||
- [ ] Issue body has working code examples (not pseudocode)
|
||||
- [ ] All file paths are absolute and verified
|
||||
- [ ] CLI commands are copy-pastable
|
||||
- [ ] Acceptance criteria are verifiable (not vague)
|
||||
- [ ] References section includes all URLs
|
||||
- [ ] Issue is self-contained — no "see docs" without details
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference — Common Mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---------|-----|
|
||||
| Pseudocode in examples | Use real, runnable code with imports |
|
||||
| Vague file paths | Use absolute paths |
|
||||
| Skipping gap analysis | Every gap needs severity + impact |
|
||||
| Missing real agentic test | Include `agent.start()` test, not just construction |
|
||||
| No verification commands | Include copy-pastable pytest/python commands |
|
||||
| Claiming "done" without evidence | Every claim references specific files/symbols |
|
||||
| Implementing instead of analyzing | This workflow produces issues, not code |
|
||||
|
||||
---
|
||||
|
||||
## Hard Rules
|
||||
|
||||
1. **DO NOT implement** — this workflow produces analysis and issues only
|
||||
2. **DO NOT claim done** without evidence
|
||||
3. **Every claim must reference** specific files/symbols
|
||||
4. **Issue must be self-contained** — implementer needs no follow-up questions
|
||||
5. **Working code examples required** — no pseudocode
|
||||
@@ -1,104 +0,0 @@
|
||||
---
|
||||
description: analysis
|
||||
---
|
||||
|
||||
You are an expert AI engineer in the PraisonAI ecosystem.
|
||||
Your job: produce ONLY (1) analysis, (2) review, (3) gap analysis, (4) critical review, (5) plan, (6) proposal.
|
||||
Do NOT implement. Do NOT write code. Do NOT update docs. Do NOT run tests beyond discovery.
|
||||
Be precise, evidence-based, and agent-centric.
|
||||
|
||||
PRINCIPLES (apply in all analysis/proposals):
|
||||
- Agent-centric: Agents, workflows, sessions, tools, memory, multi-agent safety.
|
||||
- Protocol-driven core: praisonaiagents = lightweight, protocol-first (protocols/hooks/adapters only).
|
||||
- DRY: identify reuse; avoid duplication.
|
||||
- No perf impact: preserve import-time and hot-path; heavy deps optional + lazy.
|
||||
- Async-safe + multi-agent safe by default.
|
||||
- Clear paid upgrade path (support/cloud/services) without restricting core.
|
||||
- Easy for non-developers. "Few lines of code to do the task!"
|
||||
|
||||
CANONICAL PATHS:
|
||||
- UI Repo: /Users/praison/praisonaiui (praisonaiui)
|
||||
- SDK Core (reference): /Users/praison/praisonai-package/src/praisonai-agents (praisonaiagents)
|
||||
- Docs: /Users/praison/PraisonAIDocs (JS: docs/js, Rust: docs/rust)
|
||||
- Extension points: src/praisonaiui/*, docs/*, tests/*
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
MANDATORY PROCESS (NO IMPLEMENTATION)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
STEP 1 — Acceptance Criteria
|
||||
- Translate request into testable criteria: API, CLI, docs, test expectations, perf constraints.
|
||||
|
||||
STEP 2 — Repo Inventory (evidence-based)
|
||||
- Go through ALL relevant files, understand current logic end-to-end.
|
||||
- Inventory with evidence:
|
||||
- Public APIs: modules/classes/functions and exports
|
||||
- Protocols/adapters/hooks and extension points
|
||||
- CLI commands, options, help text
|
||||
- Integrations (db/observability/tools)
|
||||
- Tests (unit/integration), fixtures, CI config
|
||||
- Docs (Mintlify), examples, recipes
|
||||
- Provide: file paths + key symbols + grep counts + entry points.
|
||||
- Identify DRY opportunities.
|
||||
|
||||
STEP 3 — Detailed Analysis
|
||||
- Architecture and behavior: control flow, data flow, concurrency (sync/async), multi-agent interactions, dependency boundaries (core/wrapper/tools), failure modes.
|
||||
- Highlight invariants: protocol-driven core, lazy imports, optional deps.
|
||||
|
||||
STEP 4 — Detailed Review
|
||||
- Evaluate against principles: agent-centricity, API simplicity, DRY, perf, optional deps + lazy imports, async/multi-agent safety, test coverage, CLI parity, docs clarity.
|
||||
- Concrete evidence for each judgment.
|
||||
|
||||
STEP 5 — Gap Analysis
|
||||
- Compare acceptance criteria vs current state. Checklist:
|
||||
- UI Core, CLI, Docs, Tests, Exports, Perf, Multi-agent + async
|
||||
- Each gap: severity, impact, risk, recommended location (core/wrapper/tools).
|
||||
|
||||
STEP 6 — Critical Review
|
||||
- Risks, footguns, maintenance concerns:
|
||||
- API ambiguity, edge cases, backward compat
|
||||
- Coupling violations, perf regressions, concurrency hazards
|
||||
- Misuse risks, operational concerns
|
||||
- Mitigation strategies and "safe by default" recommendations.
|
||||
|
||||
STEP 7 — Plan
|
||||
- Step-by-step (do not implement): tests (TDD) → implementation → CLI → docs → verification
|
||||
- Exact files to change/create. Migration/compat plan. Rollback plan. Verification commands. Perf checks. Multi-agent + async test strategy.
|
||||
|
||||
REAL AGENTIC TEST definition (MUST include in every verification plan):
|
||||
- A "real agentic test" = agent ACTUALLY RUNS and calls the LLM:
|
||||
1. Create Agent with the feature being tested
|
||||
2. Call `agent.start("a real task prompt")` — NOT just constructing the object
|
||||
3. Agent MUST call LLM and produce text response
|
||||
4. Print full output so dev can see it worked end-to-end
|
||||
- Example:
|
||||
```python
|
||||
from praisonaiagents import Agent
|
||||
agent = Agent(name="test", instructions="You are a helpful assistant")
|
||||
result = agent.start("Say hello in one sentence")
|
||||
print(result)
|
||||
```
|
||||
- Assert-only object construction = SMOKE TEST, not real agentic test.
|
||||
- Both smoke AND real agentic tests required.
|
||||
|
||||
STEP 8 — Proposal
|
||||
- Minimal, agent-centric design and API/CLI surface:
|
||||
- protocols/hooks in core; implementations in wrapper/tools
|
||||
- Clear defaults and explicit overrides
|
||||
- Multi-agent resource isolation/sharing
|
||||
- Error model and observability hooks
|
||||
- Include: "Simple API" examples, CLI UX, docs outline, paid upgrade path.
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
REQUIRED OUTPUT (in order):
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
1) Acceptance Criteria
|
||||
2) Inventory (evidence: paths/symbols/exports/grep counts)
|
||||
3) Detailed Analysis (architecture + flows + invariants)
|
||||
4) Detailed Review (quality vs principles, evidence-based)
|
||||
5) Gap Analysis (checklist + severity/impact/placement)
|
||||
6) Critical Review (risks + mitigations)
|
||||
7) Plan (step-by-step + file list + verification strategy)
|
||||
8) Proposal (agent-centric design + API/CLI/docs outline)
|
||||
|
||||
Hard rules: DO NOT implement. DO NOT write code. DO NOT claim done. Every claim must reference specific files/symbols.
|
||||
@@ -1,228 +0,0 @@
|
||||
---
|
||||
description: Audit existing docs against live code, then create a comprehensive GitHub issue in PraisonAIDocs with correct, tested information ready for a writer/agent to implement immediately
|
||||
---
|
||||
|
||||
# Create PraisonAIDocs Issue Workflow
|
||||
|
||||
Audit code → Compare with existing docs → Draft correct content → Create issue.
|
||||
|
||||
> **When to use this:** A feature is already implemented in PraisonAI but the docs are missing, outdated, or wrong. You need to file a self-contained docs issue in `MervinPraison/PraisonAIDocs` that a writer or agent can act on without asking follow-up questions.
|
||||
> **When NOT to use this:** Use `@[/create-github-issue]` for new integrations that need external research. Use `@[/local-fix]` if you are writing the docs yourself.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Identify the Feature & Existing Docs
|
||||
|
||||
### 1a. Find the relevant doc file
|
||||
|
||||
```bash
|
||||
ls /Users/praison/PraisonAIDocs/docs/<section>/
|
||||
cat /Users/praison/PraisonAIDocs/docs/<section>/<feature>.mdx
|
||||
```
|
||||
|
||||
Key doc sections:
|
||||
- `docs/observability/` — tracing providers (Langfuse, LangSmith, etc.)
|
||||
- `docs/tools/` — tool integrations
|
||||
- `docs/features/` — agent features
|
||||
- `docs/cli/` — CLI commands
|
||||
- `docs/guides/` — how-to guides
|
||||
|
||||
### 1b. Read the existing doc fully
|
||||
|
||||
Note every claim that needs verification:
|
||||
- Install commands
|
||||
- Import statements
|
||||
- API method names and signatures
|
||||
- Environment variable names
|
||||
- CLI commands
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Audit the Live Code
|
||||
|
||||
### 2a. Find the source implementation
|
||||
|
||||
```bash
|
||||
# Search praisonaiagents core SDK
|
||||
grep -rn "<feature>" /Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/ 2>&1 | grep -v ".pyc"
|
||||
|
||||
# Search praisonai wrapper (CLI, integrations)
|
||||
grep -rn "<feature>" /Users/praison/praisonai-package/src/praisonai/praisonai/ 2>&1 | grep -v ".pyc"
|
||||
|
||||
# Search praisonai-tools
|
||||
grep -rn "<feature>" /Users/praison/PraisonAI-tools/ 2>&1 | grep -v ".pyc"
|
||||
```
|
||||
|
||||
### 2b. Read all relevant source files end-to-end
|
||||
|
||||
Read every file that implements the feature. For each file capture:
|
||||
- Actual class/function names and signatures
|
||||
- Required vs optional parameters
|
||||
- Environment variables read (exact names)
|
||||
- What gets called internally (trace the call chain)
|
||||
- Any version-specific behavior
|
||||
|
||||
Key files to always check:
|
||||
| File pattern | What to look for |
|
||||
|---|---|
|
||||
| `praisonaiagents/obs/__init__.py` | `_LazyObsModule`, factory methods, `auto()` |
|
||||
| `praisonai_tools/observability/providers/<name>_provider.py` | `init()`, `is_available()`, `shutdown()`, `flush()` |
|
||||
| `praisonai/observability/<name>.py` | CLI sink adapter, event handling |
|
||||
| `praisonai/cli/commands/<name>.py` | All CLI sub-commands and options |
|
||||
| `praisonai/__init__.py` | Global env var overrides that may interfere |
|
||||
|
||||
### 2c. Test the feature live
|
||||
|
||||
Run minimal test scripts to verify the actual behavior:
|
||||
|
||||
```bash
|
||||
# Test the import works
|
||||
python3 -c "from praisonaiagents.obs import obs; provider = obs.<name>(); print(type(provider).__name__, provider._initialized)"
|
||||
|
||||
# Test CLI commands
|
||||
praisonai <feature> --help
|
||||
praisonai <feature> <subcommand>
|
||||
|
||||
# Verify traces/output appear
|
||||
timeout 30 praisonai <feature> <subcommand> --limit 5
|
||||
```
|
||||
|
||||
### 2d. Build a "What's Wrong" table
|
||||
|
||||
For each doc claim that is incorrect, record:
|
||||
|
||||
| Current Doc (Wrong) | Correct |
|
||||
|---|---|
|
||||
| wrong install command | correct install |
|
||||
| wrong import | correct import |
|
||||
| non-existent method | actual method |
|
||||
| wrong env var name | actual env var |
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Draft the Issue
|
||||
|
||||
The issue body must be **self-contained and implementation-ready**. A writer should be able to update the doc by reading only the issue — no follow-up questions.
|
||||
|
||||
### Required sections:
|
||||
|
||||
```markdown
|
||||
## Overview
|
||||
One paragraph: what doc file needs updating, why it's wrong, and the end goal.
|
||||
State explicitly: "All code in this issue has been tested and verified working."
|
||||
|
||||
## What's Wrong With the Current Docs
|
||||
Table: Current (Wrong) | Correct
|
||||
Cover: install commands, imports, API methods, env vars, missing sections.
|
||||
|
||||
## Correct Architecture (How It Actually Works)
|
||||
Explain the actual internal call chain so the writer understands context.
|
||||
Include a text diagram if helpful.
|
||||
|
||||
## Required Install
|
||||
Exact pip commands, nothing more.
|
||||
|
||||
## Environment Variables
|
||||
Table: Variable | Required | Description
|
||||
Show bash export examples for both cloud and self-hosted.
|
||||
|
||||
## Python Usage
|
||||
|
||||
### Quickstart (Recommended)
|
||||
Full working code with correct imports, init, agent run, and flush.
|
||||
|
||||
### Auto-Detection
|
||||
Document obs.auto() or equivalent if applicable.
|
||||
|
||||
### Additional Patterns
|
||||
Any other valid usage patterns (explicit provider, multi-agent, etc.).
|
||||
|
||||
## CLI Usage (if applicable)
|
||||
All sub-commands with flags and examples.
|
||||
Include an end-to-end CLI session example.
|
||||
|
||||
## Configuration File (if applicable)
|
||||
Document any config files that are auto-created or auto-read.
|
||||
|
||||
## What Output Looks Like
|
||||
Show what traces/output actually look like after a successful run.
|
||||
|
||||
## Version Compatibility Notes
|
||||
Document any breaking changes between SDK versions that affect usage.
|
||||
|
||||
## Files to Update
|
||||
Table: File | Change
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Checkbox list — each item must be specific and verifiable
|
||||
|
||||
## References
|
||||
List all source files read (with absolute paths).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Create the Issue
|
||||
|
||||
### 4a. Write body to a temp file
|
||||
|
||||
```bash
|
||||
cat > /tmp/docs_issue_<feature>.md << 'EOF'
|
||||
<issue body>
|
||||
EOF
|
||||
```
|
||||
|
||||
### 4b. Create via `gh` CLI
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--repo MervinPraison/PraisonAIDocs \
|
||||
--title "Docs: <action verb> <feature> page — <one-line summary of what's wrong>" \
|
||||
--label "documentation" \
|
||||
--body-file /tmp/docs_issue_<feature>.md
|
||||
```
|
||||
|
||||
**Title format:** `Docs: Rewrite/Update/Add <Feature> page — <what's wrong or missing>`
|
||||
|
||||
Examples:
|
||||
- `Docs: Rewrite Langfuse integration page with correct Langfuse v4 API and CLI commands`
|
||||
- `Docs: Add obs.auto() documentation to observability overview`
|
||||
- `Docs: Fix LangSmith install command and update import paths`
|
||||
|
||||
### 4c. Verify
|
||||
|
||||
```bash
|
||||
gh issue view <number> --repo MervinPraison/PraisonAIDocs | head -30
|
||||
```
|
||||
|
||||
Confirm the URL: `https://github.com/MervinPraison/PraisonAIDocs/issues/<number>`
|
||||
|
||||
---
|
||||
|
||||
## Checklist — Before Creating the Issue
|
||||
|
||||
- [ ] Existing doc file read completely
|
||||
- [ ] All source files implementing the feature read end-to-end (not skimmed)
|
||||
- [ ] Feature tested live — not just code-read
|
||||
- [ ] "What's Wrong" table is complete and specific
|
||||
- [ ] All code examples in the issue are copy-pastable and tested
|
||||
- [ ] All env var names are verified against source (not guessed)
|
||||
- [ ] All CLI commands verified with `--help` and live run
|
||||
- [ ] Acceptance criteria are specific and verifiable (not vague)
|
||||
- [ ] References list includes all source file paths read
|
||||
- [ ] Issue is self-contained — writer needs no follow-up
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference — Common Mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---|---|
|
||||
| Documenting what the code *should* do, not what it *does* | Run it. Test it. Document the actual behavior. |
|
||||
| Copying import paths from docs being replaced | Always verify imports against source files |
|
||||
| Missing the "What's Wrong" table | This is the most important section — be explicit |
|
||||
| Vague acceptance criteria like "docs are updated" | Write specific, testable criteria: "install command is `pip install langfuse`" |
|
||||
| Not checking for interfering globals (e.g. `OTEL_SDK_DISABLED`) | Always grep `__init__.py` files for env var overrides |
|
||||
| Forgetting `provider.flush()` in examples | Async buffers need explicit flush before process exit |
|
||||
| Not testing with a real API key | Code-reading alone misses runtime errors |
|
||||
| Using `timeout` too short for first-run (downloads, auth) | Use `timeout 120` for agent runs, `timeout 30` for CLI |
|
||||
@@ -1,308 +0,0 @@
|
||||
---
|
||||
description: Research a topic in-depth, analyze both external and local codebases, and create a comprehensive GitHub issue — ready for another agent/developer to act on immediately
|
||||
---
|
||||
|
||||
# Create GitHub Issue Workflow
|
||||
|
||||
Research → Clone & Analyze → PraisonAI Analysis → Draft → Create Issue.
|
||||
|
||||
> **When to use this:** You need to create a detailed, implementation-ready GitHub issue for a new integration, feature, or benchmark. The issue must contain enough context that another agent or developer can implement it without asking further questions.
|
||||
> **When NOT to use this:** Use `@[/local-fix]` if you are implementing the change yourself, not just filing an issue.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Online Research
|
||||
|
||||
### 1a. Read official sources
|
||||
|
||||
Research the topic from all primary sources: official site, GitHub repo, documentation, blog posts.
|
||||
|
||||
```bash
|
||||
# Example searches (adapt to your topic)
|
||||
# - Official site / announcement pages
|
||||
# - GitHub README and docs
|
||||
# - Third-party write-ups (e.g. Snorkel AI, Epoch AI)
|
||||
# - Framework documentation (core concepts, agents, running)
|
||||
```
|
||||
|
||||
URLs to read for each source (use `read_url_content` tool):
|
||||
- Official announcement / news page
|
||||
- GitHub repository README (multiple chunks if large)
|
||||
- Framework/integration documentation pages
|
||||
- Any relevant blog posts or analysis
|
||||
|
||||
**Capture for the issue:**
|
||||
- What is it? Purpose and design goals
|
||||
- Key terminology and concepts (with definitions)
|
||||
- Architecture overview
|
||||
- Current leaderboard / ecosystem state
|
||||
- References list (all URLs)
|
||||
|
||||
### 1b. Read paginated content
|
||||
|
||||
For large pages, read additional chunks:
|
||||
|
||||
```
|
||||
view_content_chunk(document_id=<url>, position=2)
|
||||
view_content_chunk(document_id=<url>, position=3)
|
||||
view_content_chunk(document_id=<url>, position=4)
|
||||
```
|
||||
|
||||
Continue until all relevant sections are read (core concepts, agent types, running instructions, integration API).
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Clone & Analyze External Codebase
|
||||
|
||||
### 2a. Clone the repository
|
||||
|
||||
```bash
|
||||
git clone <repo-url> ~/<repo-name> --depth=1
|
||||
```
|
||||
|
||||
### 2b. Explore structure
|
||||
|
||||
```bash
|
||||
ls -la ~/<repo-name>/
|
||||
ls -la ~/<repo-name>/src/
|
||||
```
|
||||
|
||||
Key files to read (adapt paths to repo):
|
||||
- `AGENTS.md` / `CLAUDE.md` / `README.md` — architecture overview
|
||||
- Base class files (e.g. `base.py` for agents, environments)
|
||||
- Factory / registry files (how things are registered)
|
||||
- Model/config files (data structures agents must populate)
|
||||
- Enum files (valid names, types)
|
||||
- Example agent implementations (minimal + full-featured)
|
||||
- `pyproject.toml` — Python version, dependencies
|
||||
|
||||
**Capture for the issue:**
|
||||
- Repository structure diagram
|
||||
- Key file paths with line counts
|
||||
- Base class interface (all abstract methods with signatures)
|
||||
- How to register a new agent (enum + factory pattern)
|
||||
- Data models the agent must populate (`AgentContext`, etc.)
|
||||
- Example agent implementations (minimal and production)
|
||||
- CLI commands to run the integration
|
||||
- Environment variables required
|
||||
|
||||
### 2c. Read base classes end-to-end
|
||||
|
||||
Read every relevant base class completely. For agent integrations:
|
||||
|
||||
```
|
||||
read_file(base.py) # BaseAgent / BaseInstalledAgent
|
||||
read_file(factory.py) # AgentFactory registration
|
||||
read_file(models/agent/name.py) # AgentName enum
|
||||
read_file(models/agent/context.py) # AgentContext fields
|
||||
read_file(examples/agents/minimal_agent.py) # Minimal example
|
||||
read_file(agents/installed/reference_agent.py) # Full example
|
||||
```
|
||||
|
||||
### 2d. Read a reference implementation
|
||||
|
||||
Pick the most complete existing agent implementation (e.g. `codex.py`, `gemini_cli.py`) and read it fully. This reveals:
|
||||
- Install pattern (system packages → user packages)
|
||||
- Version detection (`get_version_command` / `parse_version`)
|
||||
- `@with_prompt_template` decorator usage
|
||||
- `populate_context_post_run` for token tracking
|
||||
- ATIF trajectory support (`SUPPORTS_ATIF`)
|
||||
- `CliFlag` / `EnvVar` declarative config
|
||||
- `exec_as_root` vs `exec_as_agent` usage
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Analyze PraisonAI Codebase
|
||||
|
||||
### 3a. Identify relevant components
|
||||
|
||||
```bash
|
||||
ls /Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/
|
||||
ls /Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/tools/
|
||||
ls /Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/agent/
|
||||
```
|
||||
|
||||
Key files to read for agent integration issues:
|
||||
|
||||
| File | What to look for |
|
||||
|------|-----------------|
|
||||
| `praisonaiagents/tools/shell_tools.py` | `execute_command`, approval decorators |
|
||||
| `praisonaiagents/agent/agent.py` | `Agent.start()`, `Agent.chat()`, token tracking |
|
||||
| `praisonaiagents/approval/` | `@require_approval`, auto-approval backend |
|
||||
| `praisonaiagents/eval/` | Evaluation framework hooks |
|
||||
| `praisonaiagents/agents/agents.py` | `AgentTeam` multi-agent |
|
||||
| `pyproject.toml` | Current version, optional dependencies |
|
||||
|
||||
### 3b. Map integration points
|
||||
|
||||
For each PraisonAI component, document:
|
||||
- What it does
|
||||
- How it maps to the external system's interface
|
||||
- What needs bridging (e.g. wrapping `environment.exec()` as a tool)
|
||||
- Known gotchas (e.g. `@require_approval` must be bypassed in containers)
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Draft the Issue
|
||||
|
||||
The issue body must be self-contained. Another agent must be able to implement the feature by reading only the issue — no follow-up questions.
|
||||
|
||||
### Required sections:
|
||||
|
||||
```markdown
|
||||
## Overview
|
||||
One paragraph: what, why, and the end goal.
|
||||
|
||||
## Background: What is <X>?
|
||||
- Purpose and design goals
|
||||
- Key statistics (task count, solve rates, etc.)
|
||||
- Why <X> + PraisonAI is valuable
|
||||
- Current ecosystem / leaderboard state
|
||||
|
||||
## <X> Architecture (Codebase Analysis)
|
||||
> Repo analyzed locally: `~/<repo-name>` (cloned at `~/<repo-name>`)
|
||||
|
||||
### Core Concepts
|
||||
Table: Concept | Description
|
||||
|
||||
### Two (or N) Integration Types
|
||||
Code examples for each type with full signatures.
|
||||
|
||||
### Key File Locations in <X> Codebase
|
||||
Directory tree with annotations for each important file.
|
||||
|
||||
### Data Models
|
||||
Full class definitions the agent must populate.
|
||||
|
||||
### How to Run (CLI)
|
||||
All relevant CLI commands with flags and examples.
|
||||
|
||||
## PraisonAI Architecture (Relevant to This Integration)
|
||||
Table: Component | Location | Relevance
|
||||
|
||||
### PraisonAI Execution Model
|
||||
How PraisonAI currently handles the relevant operations, and what must be adapted.
|
||||
|
||||
## Proposed Implementation Plan
|
||||
### Approach: <Recommended> (with justification)
|
||||
|
||||
### Phase 1: Minimal Proof-of-Concept
|
||||
Full working code example.
|
||||
|
||||
### Phase 2: Production Implementation
|
||||
Full working code example.
|
||||
|
||||
### Phase N: Advanced Features
|
||||
(ATIF, multi-agent, etc.)
|
||||
|
||||
## Files to Create / Modify
|
||||
### New files (praisonai-package)
|
||||
Table: File | Purpose
|
||||
|
||||
### Modifications to <External Repo> (PR upstream)
|
||||
Table: File | Change
|
||||
|
||||
## Technical Considerations
|
||||
Subsections for:
|
||||
- Container/environment dependencies
|
||||
- API key forwarding
|
||||
- Safety/approval bypass
|
||||
- Token tracking
|
||||
- Parallel execution safety
|
||||
|
||||
## Job / Config Example
|
||||
Working YAML config + CLI invocation.
|
||||
|
||||
## Use Cases Unlocked
|
||||
Table: Use Case | How
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Checkbox list of verifiable outcomes
|
||||
|
||||
## Implementation Notes for the Assigned Agent/Developer
|
||||
### Key <X> Files to Read First
|
||||
Numbered list with file paths and line counts.
|
||||
|
||||
### Key PraisonAI Files to Read
|
||||
Numbered list with file paths.
|
||||
|
||||
### Critical Integration Points
|
||||
Numbered list of the exact code-level bridges needed.
|
||||
|
||||
### Architecture Decision
|
||||
Why the chosen approach (installed vs external, etc.) with trade-offs.
|
||||
|
||||
### Installation & Testing Commands
|
||||
Copy-pastable commands to install, verify, and run.
|
||||
|
||||
### Upstream PR
|
||||
What to submit upstream and where.
|
||||
|
||||
## References
|
||||
Bullet list of all URLs used.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Create the Issue
|
||||
|
||||
### 5a. Create via `gh` CLI
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--repo <org>/<repo> \
|
||||
--title "Feature: <Descriptive Title>" \
|
||||
--label "enhancement" \
|
||||
--body "<issue body>"
|
||||
```
|
||||
|
||||
**Title format:** `Feature: <What> with <Integration> (<Framework/Version>)`
|
||||
|
||||
Example:
|
||||
```bash
|
||||
gh issue create \
|
||||
--repo MervinPraison/PraisonAI \
|
||||
--title "Feature: Integrate PraisonAI Agents with Terminal-Bench 2.0 (Harbor Framework)" \
|
||||
--label "enhancement" \
|
||||
--body "..."
|
||||
```
|
||||
|
||||
### 5b. Verify the issue was created
|
||||
|
||||
```bash
|
||||
gh issue view <issue-number> --repo <org>/<repo> | head -20
|
||||
```
|
||||
|
||||
The output URL confirms success: `https://github.com/<org>/<repo>/issues/<number>`
|
||||
|
||||
---
|
||||
|
||||
## Checklist — Before Creating the Issue
|
||||
|
||||
- [ ] All primary documentation URLs read (including paginated chunks)
|
||||
- [ ] External repo cloned locally and analyzed
|
||||
- [ ] Base classes read end-to-end (not just skimmed)
|
||||
- [ ] At least one reference implementation read fully
|
||||
- [ ] PraisonAI codebase analyzed for integration points
|
||||
- [ ] Issue body has working code examples (not pseudocode)
|
||||
- [ ] All file paths are absolute and verified to exist
|
||||
- [ ] CLI commands are copy-pastable and complete
|
||||
- [ ] Acceptance criteria are verifiable (not vague)
|
||||
- [ ] References section includes all URLs used
|
||||
- [ ] Issue is self-contained — no "see docs for details" without the details
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference — Common Mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---------|-----|
|
||||
| Pseudocode in examples | Use real, runnable code with imports |
|
||||
| Vague file paths like `agents/` | Use absolute paths like `~/harbor/src/harbor/agents/base.py` |
|
||||
| Missing `--depth=1` on clone | Large repos take forever; always use shallow clone |
|
||||
| Only reading chunk 0 of a URL | Read chunks 1–4+ for paginated content |
|
||||
| Skipping the factory/registry file | This is where registration happens; always read it |
|
||||
| Not reading a reference agent | Pattern is not obvious from base class alone |
|
||||
| Forgetting API key forwarding section | Always document how secrets are passed to containers |
|
||||
| Skipping `populate_context_post_run` | Harbor uses this for token tracking and leaderboard data |
|
||||
| Missing upstream PR instructions | Specify exact files to modify upstream for first-class support |
|
||||
@@ -1,190 +0,0 @@
|
||||
---
|
||||
description: create and publish a post on mer.vin using praisonaiwp
|
||||
---
|
||||
|
||||
## Config
|
||||
|
||||
- Server: `default` → `https://mer.vin`
|
||||
- Config: `~/.praisonaiwp/config.yaml`
|
||||
- Category for PraisonAI features: `PraisonAI`
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Compose the content
|
||||
|
||||
Structure every post as:
|
||||
1. **Intro paragraph** — one sentence, what the feature solves
|
||||
2. **Mermaid diagram** — architecture/flow (see block format below)
|
||||
3. **Sections** — H2 headings, tables > prose, code blocks for usage
|
||||
4. **Performance/summary** — table with concrete numbers
|
||||
|
||||
Keep it technical. Lead with diagrams and tables, not paragraphs.
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Mermaid block format (merpress)
|
||||
|
||||
> **Creating merpress:** Install the [Merpress – Mermaid for WordPress](https://wordpress.org/plugins/merpress/) plugin via `wp plugin install merpress --activate --allow-root` on the server. It adds the `wp:merpress/mermaidjs` block used below.
|
||||
|
||||
All posts use the native `wp:merpress/mermaidjs` block. Use this exact format:
|
||||
|
||||
```
|
||||
<!-- wp:merpress/mermaidjs {"align":"full"} -->
|
||||
<div class="wp-block-merpress-mermaidjs diagram-source-mermaid alignfull"><pre class="mermaid">%%{init: {"theme": "base", "themeVariables": {"background": "transparent", "lineColor": "#000000"}}}%%
|
||||
graph TD
|
||||
A[Input] --> B[Agent]
|
||||
B --> C[Tool]
|
||||
C --> D[Output]
|
||||
|
||||
classDef hook fill:#189AB4,color:#fff
|
||||
classDef agent fill:#8B0000,color:#fff
|
||||
classDef decision fill:#444,color:#fff
|
||||
|
||||
class B agent
|
||||
class C hook
|
||||
</pre></div>
|
||||
<!-- /wp:merpress/mermaidjs -->
|
||||
```
|
||||
|
||||
**Do NOT use:** `[mermaid]...[/mermaid]` shortcode — that is the wrong format.
|
||||
|
||||
Color scheme:
|
||||
- `#8B0000` (dark red) — agents, inputs, outputs
|
||||
- `#189AB4` (teal) — tools, hooks
|
||||
- `#444` — decisions/conditionals
|
||||
|
||||
---
|
||||
|
||||
## Step 2a — SVG/image upload via SSH
|
||||
|
||||
`praisonaiwp media upload` correctly SFTPs the file to `/tmp/` on the server, but
|
||||
`_execute_wp()` in `~/praisonaiwp-cli/praisonaiwp/core/wp_client.py` never appends
|
||||
`--allow-root`. Use direct SSH instead.
|
||||
|
||||
**SVG upload (Safe SVG plugin active on mer.vin):**
|
||||
|
||||
```bash
|
||||
# 1. SCP SVG to server
|
||||
scp -i ~/.ssh/id_ed25519 /path/to/diagram.svg <SSH_USER>@<SERVER_IP>:/tmp/
|
||||
|
||||
# 2. Import via WP-CLI — must pass --user=<admin> so Safe SVG capability check passes
|
||||
ssh -i ~/.ssh/id_ed25519 <SSH_USER>@<SERVER_IP> \
|
||||
"cd <WP_ROOT> && \
|
||||
wp media import /tmp/diagram.svg --post_id=<POST_ID> \
|
||||
--title='Title' --alt='Alt' --user=praison --allow-root --porcelain"
|
||||
# → returns media ID
|
||||
|
||||
# 3. Get the URL
|
||||
ssh -i ~/.ssh/id_ed25519 <SSH_USER>@<SERVER_IP> \
|
||||
"cd <WP_ROOT> && \
|
||||
wp post get <MEDIA_ID> --field=guid --allow-root"
|
||||
```
|
||||
|
||||
> **Key:** `--user=praison` is required — Safe SVG checks upload capability against the
|
||||
> current WP user. Without it, even with the plugin active, SVG imports are blocked.
|
||||
|
||||
**PNG fallback (if Safe SVG not available):**
|
||||
|
||||
```bash
|
||||
rsvg-convert -w 1360 /path/to/diagram.svg -o /tmp/diagram_2x.png
|
||||
# Then follow the same SSH steps above using the .png file (no --user needed)
|
||||
```
|
||||
|
||||
Use this Gutenberg image block in the post content:
|
||||
|
||||
```
|
||||
<!-- wp:image {"id":<MEDIA_ID>,"sizeSlug":"full","linkDestination":"none"} -->
|
||||
<figure class="wp-block-image size-full"><img src="<IMAGE_URL>" alt="Alt text" class="wp-image-<MEDIA_ID>"/></figure>
|
||||
<!-- /wp:image -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3 — Create the post
|
||||
|
||||
```bash
|
||||
praisonaiwp create "Post Title" \
|
||||
--status publish \
|
||||
--content '<FULL GUTENBERG CONTENT>'
|
||||
```
|
||||
|
||||
Note the returned **Post ID** from the output.
|
||||
|
||||
---
|
||||
|
||||
## Step 4 — Set category
|
||||
|
||||
```bash
|
||||
praisonaiwp update <POST_ID> --category "PraisonAI"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — Validate mermaid format
|
||||
|
||||
```bash
|
||||
ssh -i ~/.ssh/id_ed25519 <SSH_USER>@<SERVER_IP> \
|
||||
"cd <WP_ROOT> && \
|
||||
wp post get <POST_ID> --field=post_content --allow-root | grep -i mermaid"
|
||||
```
|
||||
|
||||
Expected output must contain `wp:merpress/mermaidjs`, not `[mermaid]`.
|
||||
|
||||
---
|
||||
|
||||
## Key Gutenberg blocks reference
|
||||
|
||||
```
|
||||
<!-- wp:paragraph --><p>text</p><!-- /wp:paragraph -->
|
||||
|
||||
<!-- wp:heading --><h2 class="wp-block-heading">Title</h2><!-- /wp:heading -->
|
||||
|
||||
<!-- wp:heading {"level":3} --><h3 class="wp-block-heading">Sub</h3><!-- /wp:heading -->
|
||||
|
||||
<!-- wp:code --><pre class="wp-block-code"><code>code here</code></pre><!-- /wp:code -->
|
||||
|
||||
<!-- wp:table -->
|
||||
<figure class="wp-block-table"><table>
|
||||
<thead><tr><th>Col</th></tr></thead>
|
||||
<tbody><tr><td>Val</td></tr></tbody>
|
||||
</table></figure>
|
||||
<!-- /wp:table -->
|
||||
|
||||
<!-- wp:list --><ul class="wp-block-list"><li>item</li></ul><!-- /wp:list -->
|
||||
|
||||
<!-- wp:separator --><hr class="wp-block-separator has-alpha-channel-opacity"/><!-- /wp:separator -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Full example command
|
||||
|
||||
```bash
|
||||
praisonaiwp create "Feature Name: What It Does" \
|
||||
--status publish \
|
||||
--content '<!-- wp:paragraph -->
|
||||
<p>One sentence intro.</p>
|
||||
<!-- /wp:paragraph -->
|
||||
|
||||
<!-- wp:heading -->
|
||||
<h2 class="wp-block-heading">Architecture</h2>
|
||||
<!-- /wp:heading -->
|
||||
|
||||
<!-- wp:merpress/mermaidjs {"align":"full"} -->
|
||||
<div class="wp-block-merpress-mermaidjs diagram-source-mermaid alignfull"><pre class="mermaid">%%{init: {"theme": "base", "themeVariables": {"background": "transparent", "lineColor": "#000000"}}}%%
|
||||
graph TD
|
||||
A[Start] --> B[Agent]
|
||||
class B agent
|
||||
classDef agent fill:#8B0000,color:#fff
|
||||
</pre></div>
|
||||
<!-- /wp:merpress/mermaidjs -->
|
||||
|
||||
<!-- wp:code -->
|
||||
<pre class="wp-block-code"><code>from praisonaiagents import Agent
|
||||
agent = Agent(name="example")
|
||||
result = agent.start("task")</code></pre>
|
||||
<!-- /wp:code -->'
|
||||
|
||||
# Then set category:
|
||||
praisonaiwp update <ID> --category "PraisonAI"
|
||||
```
|
||||
@@ -1,677 +0,0 @@
|
||||
---
|
||||
description: End-to-end workflow — deep analysis → GitHub issue → wait for implementing agents → create PR if missing → wait for reviewing agents → review PR locally → feedback to @claude → merge to main when robust per AGENTS.md
|
||||
---
|
||||
|
||||
# End-to-End: Analysis → Issue → PR → Review → Merge
|
||||
|
||||
Deep Analysis → Gap Analysis → Critical Review → Plan → Create Issue → **Wait for implementing agents** → **Create PR if missing** → **Wait for reviewers** → **Validate PR locally** → **Feedback to @claude** → **Re-review after fixes** → **Merge to main if robust**.
|
||||
|
||||
> **When to use this:** You want a fully hands-off delivery loop. You describe a feature/integration/fix; this workflow produces the issue, monitors implementation by other agents (Claude, Copilot, CodeRabbit), validates their PR locally against `AGENTS.md` principles, loops feedback until the PR is robust, and merges to `main`.
|
||||
> **When NOT to use this:** Use `/analysis-github-issue-create` if you only want the issue (no PR/merge). Use `/local-fix` if you are the implementer.
|
||||
|
||||
---
|
||||
|
||||
## PRINCIPLES (apply throughout)
|
||||
|
||||
- **Agent-centric**: Agents, workflows, sessions, tools, memory, multi-agent safety.
|
||||
- **Protocol-driven core**: `praisonaiagents` = lightweight, protocol-first (protocols/hooks/adapters only).
|
||||
- **DRY**: identify reuse; avoid duplication.
|
||||
- **No perf impact**: preserve import-time and hot-path; heavy deps optional + lazy.
|
||||
- **Async-safe + multi-agent safe** by default.
|
||||
- **Easy for non-developers**: "Few lines of code to do the task!"
|
||||
- **No competitor names in public surfaces**: Never mention competitor product, company, or project names in GitHub issues, PRs, commit messages, release notes, docs, or any other public-facing content. Refer to capabilities generically (e.g., "self-improving agent pattern", "external agent framework").
|
||||
- **Test before merge**: never merge unvalidated PRs. Always clone the branch locally and run the tests.
|
||||
- **Minimal code change**: prefer upstream one-line fixes over downstream workarounds.
|
||||
- **Autonomous polling — NEVER ask the user to "check now"**: after posting feedback to `@claude`, submitting a trigger comment, or any state that requires an external agent to push commits, the assistant itself waits ~10 minutes (`sleep 600`) and then re-checks. Do not stop and wait for the human to type "check now". Only surface control back to the human when a round is fully complete (PR merged or 3-round feedback cap hit) or a blocking decision is required (e.g. rebase strategy, conflicting feature intent).
|
||||
|
||||
---
|
||||
|
||||
## CANONICAL PATHS
|
||||
|
||||
```
|
||||
Core SDK: /Users/praison/praisonai-package/src/praisonai-agents (praisonaiagents)
|
||||
Wrapper: /Users/praison/praisonai-package/src/praisonai (praisonai)
|
||||
Tools: /Users/praison/PraisonAI-tools
|
||||
Docs: /Users/praison/PraisonAIDocs
|
||||
TypeScript: /Users/praison/praisonai-package/src/praisonai-ts
|
||||
AGENTS.md: /Users/praison/praisonai-package/src/praisonai-agents/AGENTS.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# PART A — ANALYSIS & ISSUE (Phases 1–9)
|
||||
|
||||
These phases are identical to `/analysis-github-issue-create`. Execute them in order. **Do not implement any code** in these phases — they produce analysis and an issue only.
|
||||
|
||||
## Phase 1 — Acceptance Criteria
|
||||
|
||||
Translate the request into testable criteria:
|
||||
- API expectations (classes, methods, signatures)
|
||||
- CLI expectations (commands, flags, help text)
|
||||
- Documentation expectations (pages, examples)
|
||||
- Test expectations (unit, integration, smoke, real agentic)
|
||||
- Performance constraints (import time, hot-path)
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — External Research (if applicable)
|
||||
|
||||
### 2a. Read official sources
|
||||
|
||||
If analyzing an external integration, research from primary sources:
|
||||
|
||||
```bash
|
||||
# Use read_url_content tool for:
|
||||
# - Official site / announcement pages
|
||||
# - GitHub README and docs
|
||||
# - Framework documentation
|
||||
# - Third-party write-ups
|
||||
```
|
||||
|
||||
**Capture:**
|
||||
- What is it? Purpose and design goals
|
||||
- Key terminology and concepts
|
||||
- Architecture overview
|
||||
- Current ecosystem state
|
||||
- References list (all URLs)
|
||||
|
||||
### 2b. Clone & analyze external codebase (if applicable)
|
||||
|
||||
```bash
|
||||
git clone <repo-url> ~/<repo-name> --depth=1
|
||||
ls -la ~/<repo-name>/
|
||||
```
|
||||
|
||||
Key files to read:
|
||||
- `AGENTS.md` / `README.md` — architecture overview
|
||||
- Base class files (abstract methods, signatures)
|
||||
- Factory / registry files (registration pattern)
|
||||
- Model/config files (data structures)
|
||||
- Example implementations (minimal + full-featured)
|
||||
- `pyproject.toml` / `package.json` — dependencies
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — PraisonAI Codebase Inventory
|
||||
|
||||
### 3a. Inventory with evidence
|
||||
|
||||
Go through ALL relevant files, understand current logic end-to-end.
|
||||
|
||||
```bash
|
||||
# Core SDK
|
||||
ls /Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/
|
||||
grep -r "class.*Protocol" praisonaiagents/ --include="*.py" | wc -l
|
||||
|
||||
# Wrapper
|
||||
ls /Users/praison/praisonai-package/src/praisonai/praisonai/
|
||||
ls /Users/praison/praisonai-package/src/praisonai/praisonai/cli/commands/
|
||||
|
||||
# TypeScript
|
||||
ls /Users/praison/praisonai-package/src/praisonai-ts/src/
|
||||
```
|
||||
|
||||
**Document:**
|
||||
- Public APIs: modules/classes/functions and exports
|
||||
- Protocols/adapters/hooks and extension points
|
||||
- CLI commands, options, help text
|
||||
- Integrations (db/observability/tools)
|
||||
- Tests (unit/integration), fixtures, CI config
|
||||
- Docs (Mintlify), examples, recipes
|
||||
|
||||
Provide: **file paths + key symbols + grep counts + entry points**.
|
||||
|
||||
### 3b. Identify DRY opportunities
|
||||
|
||||
- Existing abstractions that can be reused
|
||||
- Duplicated code that should be consolidated
|
||||
- Existing protocols before creating new ones
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Detailed Analysis
|
||||
|
||||
### 4a. Architecture and behavior
|
||||
|
||||
- Control flow and data flow
|
||||
- Concurrency model (sync/async)
|
||||
- Multi-agent interactions
|
||||
- Dependency boundaries (core/wrapper/tools)
|
||||
- Failure modes and error handling
|
||||
|
||||
### 4b. Invariants check
|
||||
|
||||
Verify these are preserved:
|
||||
- [ ] Protocol-driven core (no heavy impls in `praisonaiagents`)
|
||||
- [ ] Lazy imports (optional deps never at module level)
|
||||
- [ ] Backward compatible (public API changes need deprecation)
|
||||
- [ ] Safe defaults (new features opt-in)
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Gap Analysis
|
||||
|
||||
Compare acceptance criteria vs current state.
|
||||
|
||||
### Checklist
|
||||
|
||||
| Area | Current State | Gap | Severity | Impact | Placement |
|
||||
|------|---------------|-----|----------|--------|-----------|
|
||||
| Core SDK | | | | | |
|
||||
| Wrapper | | | | | |
|
||||
| Tools/plugins | | | | | |
|
||||
| CLI | | | | | |
|
||||
| Docs | | | | | |
|
||||
| Tests | | | | | |
|
||||
| Exports | | | | | |
|
||||
| Perf | | | | | |
|
||||
| Multi-agent + async | | | | | |
|
||||
|
||||
### Gap severity levels
|
||||
- **Critical**: Blocks functionality
|
||||
- **High**: Significant limitation
|
||||
- **Medium**: Missing feature
|
||||
- **Low**: Nice-to-have
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — Critical Review
|
||||
|
||||
### 6a. Risks and footguns
|
||||
|
||||
- API ambiguity or edge cases
|
||||
- Backward compatibility concerns
|
||||
- Coupling violations
|
||||
- Performance regressions
|
||||
- Concurrency hazards
|
||||
- Misuse risks
|
||||
- Operational concerns
|
||||
|
||||
### 6b. Mitigation strategies
|
||||
|
||||
For each risk, document:
|
||||
- "Safe by default" recommendation
|
||||
- Explicit opt-in for dangerous behavior
|
||||
- Documentation warnings
|
||||
|
||||
---
|
||||
|
||||
## Phase 7 — Implementation Plan
|
||||
|
||||
Step-by-step plan (DO NOT implement):
|
||||
|
||||
### 7a. Test-first (TDD)
|
||||
|
||||
1. Unit tests for new functionality
|
||||
2. Integration tests for cross-component behavior
|
||||
3. Smoke tests for quick validation
|
||||
4. **Real agentic tests** (REQUIRED):
|
||||
```python
|
||||
from praisonaiagents import Agent
|
||||
agent = Agent(name="test", instructions="You are helpful")
|
||||
result = agent.start("Say hello in one sentence")
|
||||
print(result) # Must call LLM and produce response
|
||||
```
|
||||
|
||||
### 7b. Implementation order
|
||||
|
||||
1. Tests (TDD)
|
||||
2. Core implementation
|
||||
3. CLI integration
|
||||
4. Documentation
|
||||
5. Verification
|
||||
|
||||
### 7c. Files to change/create
|
||||
|
||||
| File | Action | Purpose |
|
||||
|------|--------|---------|
|
||||
| | | |
|
||||
|
||||
### 7d. Verification commands
|
||||
|
||||
```bash
|
||||
# Unit tests
|
||||
pytest tests/unit/test_<feature>.py -v
|
||||
|
||||
# Integration tests
|
||||
pytest tests/integration/test_<feature>.py -v
|
||||
|
||||
# Smoke test
|
||||
python -c "from praisonaiagents import <Feature>; print('OK')"
|
||||
|
||||
# Real agentic test
|
||||
python examples/<feature>_example.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 8 — Draft GitHub Issue
|
||||
|
||||
The issue must be **self-contained**. Another agent must be able to implement by reading only the issue.
|
||||
|
||||
### Required sections
|
||||
|
||||
```markdown
|
||||
## Overview
|
||||
One paragraph: what, why, and the end goal.
|
||||
|
||||
## Background
|
||||
- Purpose and design goals
|
||||
- Why this is valuable
|
||||
- Current state / ecosystem
|
||||
|
||||
## Architecture Analysis
|
||||
### Current Implementation
|
||||
- Key files and their purposes
|
||||
- Integration points
|
||||
- Data flow
|
||||
|
||||
### Key File Locations
|
||||
| File | Purpose | Lines |
|
||||
|------|---------|-------|
|
||||
|
||||
## Gap Analysis Summary
|
||||
### Critical Gaps
|
||||
| Gap | Impact | Effort |
|
||||
|-----|--------|--------|
|
||||
|
||||
### Feature Gaps
|
||||
| Feature | Current Support | Gap |
|
||||
|---------|-----------------|-----|
|
||||
|
||||
## Proposed Implementation
|
||||
### Phase 1: Minimal
|
||||
Working code example.
|
||||
|
||||
### Phase 2: Production
|
||||
Working code example.
|
||||
|
||||
## Files to Create / Modify
|
||||
### New files
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
|
||||
### Modified files
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
|
||||
## Technical Considerations
|
||||
- Dependencies
|
||||
- Performance impact
|
||||
- Safety / approval
|
||||
- Multi-agent safety
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Verifiable checkbox list
|
||||
|
||||
## Implementation Notes
|
||||
### Key Files to Read First
|
||||
1. `path/to/file.py` (N lines) — purpose
|
||||
|
||||
### Critical Integration Points
|
||||
1. Where X connects to Y
|
||||
|
||||
### Testing Commands
|
||||
```bash
|
||||
# Copy-pastable commands
|
||||
```
|
||||
|
||||
## References
|
||||
- [Link](url)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 9 — Create GitHub Issue
|
||||
|
||||
### 9a. Create via `gh` CLI
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--repo MervinPraison/PraisonAI \
|
||||
--title "<Type>: <Descriptive Title>" \
|
||||
--body-file /tmp/issue-body.md
|
||||
```
|
||||
|
||||
**Title formats:**
|
||||
- `Feature: <What>` — new functionality
|
||||
- `Integration: <External System>` — external integration
|
||||
- `Fix: <Problem>` — bug fix proposal
|
||||
|
||||
### 9b. Record the issue number
|
||||
|
||||
```bash
|
||||
ISSUE_NUM=$(gh issue view <number> --repo MervinPraison/PraisonAI --json number --jq '.number')
|
||||
echo "Tracking issue #$ISSUE_NUM"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# PART B — IMPLEMENTATION MONITORING (Phases 10–15)
|
||||
|
||||
After the issue is filed, other agents (`@claude`, GitHub Copilot agent, CodeRabbit) pick it up automatically. This part watches, shepherds, validates, and merges.
|
||||
|
||||
## Phase 10 — Wait ~10 min for implementing agents
|
||||
|
||||
After `gh issue create`, Claude and Copilot typically start work within seconds and finish a first pass in 5–15 minutes.
|
||||
|
||||
```bash
|
||||
echo "Waiting 10 minutes for implementing agents..."
|
||||
echo "Start: $(date)"
|
||||
sleep 600
|
||||
echo "End: $(date)"
|
||||
```
|
||||
|
||||
### Then check: did they open a PR?
|
||||
|
||||
```bash
|
||||
REPO=MervinPraison/PraisonAI
|
||||
ISSUE_NUM=<number>
|
||||
|
||||
# Check for PRs that reference the issue
|
||||
gh pr list --repo $REPO --state open --search "fixes #$ISSUE_NUM OR closes #$ISSUE_NUM" --json number,title,headRefName
|
||||
|
||||
# Also check for branches matching claude/issue-<N>-* naming convention
|
||||
gh api repos/$REPO/branches --paginate --jq ".[] | select(.name | startswith(\"claude/issue-$ISSUE_NUM\")) | .name"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 11 — Create PR if none exists
|
||||
|
||||
If Claude pushed a branch but did not open a PR, open one yourself.
|
||||
|
||||
```bash
|
||||
REPO=MervinPraison/PraisonAI
|
||||
ISSUE_NUM=<number>
|
||||
BRANCH=$(gh api repos/$REPO/branches --paginate --jq ".[] | select(.name | startswith(\"claude/issue-$ISSUE_NUM\")) | .name" | head -1)
|
||||
|
||||
if [ -n "$BRANCH" ]; then
|
||||
TITLE=$(gh api repos/$REPO/commits/$BRANCH --jq '.commit.message' | head -1)
|
||||
gh pr create --repo $REPO --head "$BRANCH" --base main \
|
||||
--title "$TITLE" \
|
||||
--body "Automated PR from Claude's work on issue #$ISSUE_NUM.
|
||||
|
||||
Branch: \`$BRANCH\`
|
||||
|
||||
Closes #$ISSUE_NUM"
|
||||
fi
|
||||
```
|
||||
|
||||
### If no branch exists after 10 minutes
|
||||
|
||||
Re-trigger Claude by commenting on the issue, then wait another 10 minutes and re-check:
|
||||
|
||||
```bash
|
||||
gh issue comment $ISSUE_NUM --repo $REPO \
|
||||
--body "@claude please pick up this issue — full analysis and plan are in the issue body."
|
||||
sleep 600
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 12 — Wait ~10 min for reviewing agents
|
||||
|
||||
Once a PR exists, `CodeRabbit`, `Copilot`, and CI pipelines run. Give them time to complete.
|
||||
|
||||
```bash
|
||||
echo "Waiting 10 minutes for PR reviewers and CI..."
|
||||
sleep 600
|
||||
```
|
||||
|
||||
### Collect status
|
||||
|
||||
```bash
|
||||
PR=<pr-number>
|
||||
gh pr view $PR --repo $REPO --json state,mergeable,mergeStateStatus,updatedAt,commits,files \
|
||||
| python -c "
|
||||
import json,sys
|
||||
d=json.load(sys.stdin)
|
||||
print(f\" State: {d['state']} Mergeable: {d['mergeable']} MergeState: {d['mergeStateStatus']}\")
|
||||
print(f\" Commits: {len(d['commits'])}\")
|
||||
for f in d['files']:
|
||||
print(f\" {f['path']}: +{f['additions']} -{f['deletions']}\")
|
||||
"
|
||||
|
||||
# CI & review checks
|
||||
gh pr view $PR --repo $REPO --json statusCheckRollup > /tmp/pr-checks.json
|
||||
python -c "
|
||||
import json
|
||||
for c in json.load(open('/tmp/pr-checks.json'))['statusCheckRollup']:
|
||||
s = c.get('conclusion') or c.get('status','?')
|
||||
name = c.get('name') or c.get('context','?')
|
||||
if s and s not in ('SKIPPED',):
|
||||
print(f' {name}: {s}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 13 — Validate the PR locally
|
||||
|
||||
**Never merge an unvalidated PR.** Always clone the branch and run tests.
|
||||
|
||||
```bash
|
||||
REPO_URL=https://github.com/MervinPraison/PraisonAI.git
|
||||
BRANCH=<branch-name>
|
||||
WORKDIR=/tmp/pr-validate
|
||||
|
||||
rm -rf $WORKDIR
|
||||
git clone --depth 1 --branch "$BRANCH" $REPO_URL $WORKDIR
|
||||
cd $WORKDIR
|
||||
|
||||
# Files touched by the PR
|
||||
gh pr view $PR --repo $REPO --json files --jq '.files[].path'
|
||||
|
||||
# Run the tests for changed files — ALWAYS use timeout (user global rule)
|
||||
timeout 120 python -m pytest <test-paths> -v --tb=short
|
||||
|
||||
# Critical invariant checks (adapt per feature):
|
||||
# 1) Lazy-import: heavy deps never imported at module level
|
||||
timeout 30 python - <<'PY'
|
||||
import sys
|
||||
from praisonai.observability import <NewThing> # example
|
||||
assert 'heavy_dep' not in sys.modules, "eager import — violates AGENTS.md §4.2"
|
||||
print("OK: lazy import preserved")
|
||||
PY
|
||||
|
||||
# 2) Cold-import benchmark (no regression)
|
||||
timeout 30 python -c "import time; t=time.time(); import praisonaiagents; print(f'{(time.time()-t)*1000:.1f} ms')"
|
||||
```
|
||||
|
||||
### Mergeability gate
|
||||
|
||||
A PR is **ready to merge only if ALL of these are true**:
|
||||
|
||||
- [ ] `gh pr view` reports `mergeable=MERGEABLE` and `mergeStateStatus` in `CLEAN`/`UNSTABLE` (not `DIRTY`/`BLOCKED`).
|
||||
- [ ] All `test (3.x)` matrix jobs report `SUCCESS`.
|
||||
- [ ] Local `pytest` on the changed test files passes with **zero failures** (skipped/xfailed tests are OK).
|
||||
- [ ] Lazy-import invariant preserved (if the feature adds an optional dep).
|
||||
- [ ] Cold-import time within ±2 % of `main` (AGENTS.md §4.2).
|
||||
- [ ] No files outside the issue's declared scope were changed.
|
||||
- [ ] The diff respects all invariants in AGENTS.md §4.6.
|
||||
|
||||
If **any** is false → go to Phase 14 (feedback). Do not merge.
|
||||
|
||||
---
|
||||
|
||||
## Phase 14 — Feedback to `@claude` when issues found
|
||||
|
||||
When validation fails, post a precise, actionable comment tagging `@claude`, referencing the exact test name, error, file, and the AGENTS.md principle violated.
|
||||
|
||||
```bash
|
||||
gh pr comment $PR --repo $REPO --body "$(cat <<'EOF'
|
||||
Hold on merge: validated locally on HEAD `<short-sha>` and found these issues:
|
||||
|
||||
**Test failures:**
|
||||
```
|
||||
FAILED tests/.../test_x.py::TestY::test_z
|
||||
AssertionError: <actual-message>
|
||||
```
|
||||
|
||||
**Root cause:** <one-line diagnosis referencing the exact file and line>.
|
||||
|
||||
**AGENTS.md violation(s):**
|
||||
- §<section>: <principle>
|
||||
|
||||
**Requested fix (minimal):**
|
||||
- Change `<file>:<line>` to `<what>`.
|
||||
- Or update the test assertion to `<what>` (if the test is wrong, not the code).
|
||||
|
||||
**What already passes:**
|
||||
- N/M tests pass.
|
||||
- Lazy-import invariant preserved ✅ (or not — state explicitly).
|
||||
|
||||
@claude please push a fix. Follow AGENTS.md principles: minimal change, protocol-driven, no perf impact, lazy imports, backward-compatible, safe defaults. Make sure the PR is robust — run the tests locally before force-pushing.
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
### Loop
|
||||
|
||||
After commenting:
|
||||
|
||||
```bash
|
||||
echo "Waiting 10 minutes for Claude to push fixes..."
|
||||
sleep 600
|
||||
# → return to Phase 12 (fetch new commits, re-run checks)
|
||||
```
|
||||
|
||||
**The assistant runs this `sleep 600` itself — it does NOT pause the loop to ask the user "check now".** After the 10-minute wait completes, the assistant immediately re-fetches the PR, re-runs the test suite, and either merges, posts the next feedback round, or reports a final status. The human is only prompted when:
|
||||
- The PR merges successfully (report + move to next issue).
|
||||
- The 3-round feedback cap is hit (escalate).
|
||||
- A design decision is needed that the assistant cannot make unilaterally (e.g. "should `allow` policy persist or not?").
|
||||
|
||||
Repeat Phases 12 → 13 → 14 until the mergeability gate in Phase 13 is fully green, or escalate to a human after 3 failed rounds.
|
||||
|
||||
### When the PR has merge conflicts
|
||||
|
||||
If `mergeStateStatus=DIRTY`, ask Claude to rebase rather than resolving conflicts yourself on non-trivial logic:
|
||||
|
||||
```bash
|
||||
gh pr comment $PR --repo $REPO --body "@claude this PR has merge conflicts with \`main\` (PR #<X> was merged, touching the same regions). Please rebase onto latest \`main\`, re-run \`pytest <paths>\`, and force-push."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 15 — Merge to `main`
|
||||
|
||||
Once Phase 13's gate is fully green:
|
||||
|
||||
### 15a. Final diff review against AGENTS.md
|
||||
|
||||
```bash
|
||||
gh pr diff $PR --repo $REPO | less
|
||||
```
|
||||
|
||||
**Hard gate — every box must be ticked before merge:**
|
||||
|
||||
- [ ] **Protocol-driven core (§4.1)**: no heavy implementations leaked into `praisonaiagents`.
|
||||
- [ ] **No perf impact (§4.2)**: lazy imports confirmed; import benchmark within ±2 %.
|
||||
- [ ] **DRY (§4.3)**: no new duplication; existing protocols/adapters reused where possible.
|
||||
- [ ] **Agent-centric (§4.4)**: API centers on agents/sessions/tools/memory.
|
||||
- [ ] **Async-safe + multi-agent safe (§4.5)**: no shared mutable globals; locks where needed.
|
||||
- [ ] **Invariants preserved (§4.6)**: backward compatible, safe defaults, deterministic tests.
|
||||
- [ ] **Naming conventions (§4.9)**: `XProtocol` for interfaces, `XAdapter` for impls, `add_*`/`get_*`/`save`/`load` verbs.
|
||||
- [ ] No `.md` files added beyond those explicitly requested (per user global rule).
|
||||
- [ ] Tests run locally with `timeout` — never hang (per user global rule).
|
||||
|
||||
### 15b. Merge
|
||||
|
||||
```bash
|
||||
gh pr merge $PR --repo $REPO --squash --delete-branch
|
||||
# --squash preserves linear main; --delete-branch keeps the repo clean
|
||||
```
|
||||
|
||||
### 15c. Verify
|
||||
|
||||
```bash
|
||||
gh pr view $PR --repo $REPO --json state,mergedAt,mergeCommit
|
||||
gh issue view $ISSUE_NUM --repo $REPO --json state # should auto-close
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Orchestration Snippet (one-shot reference)
|
||||
|
||||
For a single end-to-end invocation, chain Part B phases:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
REPO=MervinPraison/PraisonAI
|
||||
ISSUE_NUM=<fill>
|
||||
|
||||
# Phase 10: wait for implementing agents
|
||||
sleep 600
|
||||
|
||||
# Phase 11: ensure PR exists
|
||||
BRANCH=$(gh api repos/$REPO/branches --paginate \
|
||||
--jq ".[] | select(.name | startswith(\"claude/issue-$ISSUE_NUM\")) | .name" | head -1)
|
||||
PR=$(gh pr list --repo $REPO --state open --head "$BRANCH" --json number --jq '.[0].number' 2>/dev/null || true)
|
||||
if [ -z "$PR" ] && [ -n "$BRANCH" ]; then
|
||||
TITLE=$(gh api repos/$REPO/commits/$BRANCH --jq '.commit.message' | head -1)
|
||||
gh pr create --repo $REPO --head "$BRANCH" --base main \
|
||||
--title "$TITLE" --body "Closes #$ISSUE_NUM"
|
||||
PR=$(gh pr list --repo $REPO --state open --head "$BRANCH" --json number --jq '.[0].number')
|
||||
fi
|
||||
echo "Tracking PR #$PR"
|
||||
|
||||
# Phase 12: wait for reviewers + CI
|
||||
sleep 600
|
||||
|
||||
# Phases 13–14: validate + feedback loop (cap at 3 rounds)
|
||||
for round in 1 2 3; do
|
||||
echo "=== Validation round $round ==="
|
||||
# clone + pytest (per feature) — if green break; else gh pr comment + sleep 600
|
||||
break # placeholder
|
||||
done
|
||||
|
||||
# Phase 15: merge
|
||||
gh pr merge $PR --repo $REPO --squash --delete-branch
|
||||
gh issue view $ISSUE_NUM --repo $REPO --json state
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist — Before Merging
|
||||
|
||||
- [ ] Issue exists and describes the work
|
||||
- [ ] PR exists and references the issue (`Closes #N`)
|
||||
- [ ] Branch was fetched and tests were run **locally** — not just CI-trusted
|
||||
- [ ] All PR-relevant tests pass with zero failures
|
||||
- [ ] CI matrix (3.10 / 3.11 / 3.12) is all green
|
||||
- [ ] Lazy-import / cold-import invariants verified if optional deps added
|
||||
- [ ] Diff reviewed against every AGENTS.md §4 principle
|
||||
- [ ] `mergeStateStatus` in `CLEAN`/`UNSTABLE`, never `DIRTY`/`BLOCKED`
|
||||
- [ ] No files outside the issue's scope were changed
|
||||
- [ ] If feedback was given, `@claude` had a chance to respond and fixed everything
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference — Common Mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---------|-----|
|
||||
| Merging without running tests locally | Always `git clone` the branch and run `pytest` |
|
||||
| Resolving complex conflicts manually | Ask `@claude` to rebase instead |
|
||||
| Trusting CI alone | CI jobs can be skipped / out-of-date; local validation is source of truth |
|
||||
| Vague feedback to `@claude` | Every comment must cite file, line, test name, error, and AGENTS.md section |
|
||||
| Waiting forever | Cap loops at 3 rounds, then escalate to a human |
|
||||
| Running commands without `timeout` | Always `timeout 60 ...` per user global rule |
|
||||
| Creating `.md` docs proactively | Don't — user rule forbids unrequested `.md` files |
|
||||
| Skipping diff review | Every merge needs a full-diff AGENTS.md pass |
|
||||
|
||||
---
|
||||
|
||||
## Hard Rules
|
||||
|
||||
1. **Never merge without local test validation.**
|
||||
2. **Never merge when `mergeStateStatus = DIRTY` or `BLOCKED`.**
|
||||
3. **Every `@claude` comment must be actionable** — file, line, exact fix, AGENTS.md ref.
|
||||
4. **Cap feedback loops at 3 rounds** — escalate after that, don't spin forever.
|
||||
5. **Use `--squash --delete-branch`** to keep `main` linear and the repo clean.
|
||||
6. **Always verify** the issue auto-closed after merge.
|
||||
7. **All `run_command` calls use `timeout`** to avoid hangs (user global rule).
|
||||
8. **No proactive `.md` creation** beyond this workflow file (user global rule).
|
||||
9. **Never ask the user "check now"**: between rounds the assistant runs `sleep 600` itself and keeps driving. Only return control to the human on merge, 3-round cap, or an irresolvable design decision.
|
||||
@@ -1,771 +0,0 @@
|
||||
---
|
||||
description: Gap Implementation Prompts — Sequential agent tasks for PraisonAIUI feature gaps
|
||||
---
|
||||
|
||||
# Gap Implementation Prompts
|
||||
|
||||
Execute these prompts **sequentially**, one at a time. Each prompt is self-contained with context, analysis steps, and implementation instructions. Complete one fully (analysis → implementation → verification) before starting the next.
|
||||
|
||||
Reference: gap_analysis.md in the project's brain directory for full context.
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## PROMPT 1: Channel Management Tab (G1 — Phase 1, Critical)
|
||||
|
||||
You are an expert AI engineer. Your task: **Add a Channel Management dashboard tab to PraisonAIUI** that surfaces the existing bot channel infrastructure from the PraisonAI package.
|
||||
|
||||
### Context
|
||||
|
||||
PraisonAI package already has a full channel/bot system:
|
||||
- **Bots directory**: `~/praisonai-package/src/praisonai/praisonai/bots/` (26 files)
|
||||
- Discord bot: `discord.py`, `_discord_approval.py`
|
||||
- Slack bot: `slack.py`, `_slack_approval.py`
|
||||
- Telegram bot: `telegram.py`, `_telegram_approval.py`
|
||||
- WhatsApp bot: `whatsapp.py`, `_whatsapp_web_adapter.py`
|
||||
- Base infra: `bot.py`, `_session.py`, `_rate_limit.py`, `_resilience.py`, `_approval.py`, `_approval_base.py`, `_http_approval.py`, `_webhook_approval.py`, `media.py`, `_commands.py`, `_debounce.py`, `_ack.py`, `_chunk.py`, `_protocol_mixin.py`, `_config_schema.py`, `_registry.py`
|
||||
- **Gateway**: `~/praisonai-package/src/praisonai/praisonai/gateway/server.py` (1102 lines, 41KB)
|
||||
- `WebSocketGateway.health()` — returns per-channel bot health status
|
||||
- `WebSocketGateway.start_channels(channels_cfg)` — starts bot instances from config
|
||||
- `WebSocketGateway._create_bot(channel_type, token, agent, config, ch_cfg)` — creates bot per channel
|
||||
- `WebSocketGateway._run_bot_safe(name, bot)` — runs with error isolation
|
||||
- `WebSocketGateway._inject_routing_handler(channel_name, bot)` — routing-aware handlers
|
||||
|
||||
PraisonAIUI server: `~/PraisonAIUI/src/praisonaiui/server.py` — Starlette app with SSE streaming, existing dashboard tabs via `/api/*` endpoints and `@page()` decorator.
|
||||
|
||||
PraisonAIUI frontend dashboard: `~/PraisonAIUI/src/praisonaiui/templates/frontend/plugins/` — JavaScript plugins for dashboard tabs (e.g., `topnav.js` for tab rendering).
|
||||
|
||||
### PHASE 1 — Analysis (MUST complete before implementing)
|
||||
|
||||
1. **Inventory the bot system**: Read every file in `~/praisonai-package/src/praisonai/praisonai/bots/`. Understand:
|
||||
- How each bot is initialized (constructor params, tokens, agent binding)
|
||||
- What status/health information each bot exposes
|
||||
- How `_resilience.py` tracks bot health
|
||||
- How `_config_schema.py` defines channel configuration
|
||||
- How `_registry.py` registers available channels
|
||||
|
||||
2. **Inventory the gateway**: Read `~/praisonai-package/src/praisonai/praisonai/gateway/server.py`. Understand:
|
||||
- `WebSocketGateway.health()` — what data it returns about channels
|
||||
- `start_channels()` — how channels are started from YAML config
|
||||
- `_create_bot()` — bot factory pattern
|
||||
- Channel routing: `_determine_routing_context()`, `_resolve_agent_for_message()`
|
||||
|
||||
3. **Inventory PraisonAIUI dashboard**: Read `~/PraisonAIUI/src/praisonaiui/server.py`. Understand:
|
||||
- How existing `/api/*` endpoints work (pattern for adding new ones)
|
||||
- How `@page()` decorator registers dashboard pages
|
||||
- How `_registered_pages` dict works
|
||||
- How dashboard tabs are rendered in the frontend
|
||||
|
||||
4. **Inventory the frontend**: Read `~/PraisonAIUI/src/praisonaiui/templates/frontend/plugins/topnav.js` and other dashboard plugins. Understand:
|
||||
- How tabs are dynamically rendered
|
||||
- How tab data is fetched from `/api/*` endpoints
|
||||
- The pattern for adding a new dashboard tab
|
||||
|
||||
5. **Gap Analysis**: Document exactly what's missing:
|
||||
- Backend: API endpoint to query channel status
|
||||
- Frontend: Dashboard tab component for channels
|
||||
- Integration: How PraisonAIUI will communicate with the gateway for channel health
|
||||
|
||||
6. **Plan**: Produce a step-by-step implementation plan listing exact files to create/modify.
|
||||
|
||||
### PHASE 2 — Implementation (MUST)
|
||||
|
||||
1. **Backend — Add `/api/channels` endpoint** in `~/PraisonAIUI/src/praisonaiui/server.py`:
|
||||
- `GET /api/channels` — Returns list of configured channels with status (name, type, health, connected, last_active)
|
||||
- `POST /api/channels/{name}/restart` — Restart a specific channel bot
|
||||
- The endpoint should integrate with the gateway's `health()` method or maintain its own channel registry
|
||||
- Follow the exact pattern of existing `/api/overview`, `/api/config` endpoints
|
||||
|
||||
2. **Frontend — Add Channels dashboard page**:
|
||||
- Create a new dashboard plugin or add to existing dashboard rendering
|
||||
- Show a card/table for each channel: icon, name, status (online/offline/error), message count, last activity
|
||||
- Add status indicators (green/yellow/red dots)
|
||||
- Add restart button per channel
|
||||
- Follow the existing dashboard tab rendering pattern from `topnav.js`
|
||||
|
||||
3. **Register the tab**: Ensure the Channels tab appears in the dashboard navigation alongside existing tabs (Agents, Config, Logs)
|
||||
|
||||
### PHASE 3 — Verification (MUST)
|
||||
|
||||
1. Run the PraisonAIUI dev server and verify the Channels tab appears
|
||||
2. Verify `/api/channels` returns correct data
|
||||
3. Verify the UI renders channel cards with accurate status
|
||||
4. Test with at least one bot configured and verify status updates
|
||||
5. Verify no regressions in existing dashboard tabs
|
||||
6. Document what was implemented and what remains
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## PROMPT 2: Scheduler/Cron Tab (G2 — Phase 1, Critical)
|
||||
|
||||
You are an expert AI engineer. Your task: **Add a Scheduler dashboard tab to PraisonAIUI** that surfaces the existing AgentScheduler from the PraisonAI package.
|
||||
|
||||
### Context
|
||||
|
||||
PraisonAI package has a complete scheduler system:
|
||||
- **Scheduler directory**: `~/praisonai-package/src/praisonai/praisonai/scheduler/` (7 files)
|
||||
- `agent_scheduler.py` (21KB) — `AgentScheduler` class:
|
||||
- `__init__(agent, task, config, on_success, on_failure, timeout, max_cost)`
|
||||
- `start(schedule_expr, max_retries, run_immediately)` — schedule expressions: `"hourly"`, `"daily"`, `"*/6h"`, `"3600"` (seconds)
|
||||
- `stop()` — graceful shutdown
|
||||
- `get_stats()` — execution stats including cost
|
||||
- `execute_once()` — one-time run
|
||||
- `from_yaml(yaml_path, ...)` — create from agents.yaml
|
||||
- `from_recipe(recipe_name, ...)` — create from recipe
|
||||
- `start_from_yaml_config()` — start using YAML schedule config
|
||||
- `daemon_manager.py` (7KB) — background process lifecycle
|
||||
- `state_manager.py` (4KB) — persistent execution state
|
||||
- `base.py` (4KB) — `ScheduleParser`, `PraisonAgentExecutor` base classes
|
||||
- `yaml_loader.py` (6KB) — YAML schedule config loading
|
||||
- **Top-level**: `~/praisonai-package/src/praisonai/praisonai/agent_scheduler.py` (11KB) — convenience wrapper
|
||||
|
||||
PraisonAIUI: `~/PraisonAIUI/src/praisonaiui/server.py` — Starlette app. Existing pattern: API endpoints return JSON, dashboard renders tabs.
|
||||
|
||||
### PHASE 1 — Analysis (MUST complete before implementing)
|
||||
|
||||
1. **Read the full scheduler system**: Go through every file in `~/praisonai-package/src/praisonai/praisonai/scheduler/`:
|
||||
- `agent_scheduler.py` — understand the full `AgentScheduler` lifecycle (init → start → _run_schedule → _execute_with_retry → stop)
|
||||
- `base.py` — understand `ScheduleParser.parse()` for schedule expression formats
|
||||
- `daemon_manager.py` — understand how daemon processes are managed (start/stop/status)
|
||||
- `state_manager.py` — understand how execution state is persisted (where, format)
|
||||
- `yaml_loader.py` — understand YAML config format for schedules
|
||||
|
||||
2. **Understand the data model**: What data does a scheduled agent have?
|
||||
- Schedule expression, agent identity, task description, max retries, timeout, max cost
|
||||
- Execution stats: total_runs, successful_runs, failed_runs, total_cost, last_run, next_run
|
||||
|
||||
3. **Inventory PraisonAIUI**: Read `server.py` to understand the pattern for adding CRUD API endpoints.
|
||||
|
||||
4. **Gap Analysis**: Document exactly what's needed:
|
||||
- API: CRUD endpoints for schedules (list, create, update, delete, run-now, get-stats)
|
||||
- Storage: Where to persist schedule definitions (YAML file? database? in-memory?)
|
||||
- Frontend: Scheduler tab with schedule list, create/edit form, run history
|
||||
|
||||
5. **Plan**: Step-by-step with exact files to create/modify.
|
||||
|
||||
### PHASE 2 — Implementation (MUST)
|
||||
|
||||
1. **Backend — Add Scheduler API endpoints** in `~/PraisonAIUI/src/praisonaiui/server.py`:
|
||||
- `GET /api/schedules` — List all scheduled agents with status and stats
|
||||
- `POST /api/schedules` — Create a new schedule (agent, task, schedule_expr, max_retries, timeout, max_cost)
|
||||
- `PUT /api/schedules/{id}` — Update schedule configuration
|
||||
- `DELETE /api/schedules/{id}` — Remove a schedule
|
||||
- `POST /api/schedules/{id}/run` — Trigger immediate execution
|
||||
- `POST /api/schedules/{id}/stop` — Stop a running schedule
|
||||
- `GET /api/schedules/{id}/stats` — Get execution statistics
|
||||
- Integrate with `AgentScheduler` class from praisonai-package, importing it appropriately
|
||||
|
||||
2. **Backend — Schedule persistence**:
|
||||
- Store schedule definitions in a YAML/JSON file alongside the existing config
|
||||
- Load schedules on server startup and start them automatically
|
||||
- Track run history in-memory with periodic flush
|
||||
|
||||
3. **Frontend — Add Scheduler dashboard page**:
|
||||
- Schedule list: table/cards showing each schedule (name, expression, status, last run, next run, cost)
|
||||
- Create/Edit form: agent selector, task input, schedule expression picker (presets: hourly/daily/weekly + custom cron), retry/timeout/cost settings
|
||||
- Run history: expandable section per schedule showing past executions with results
|
||||
- Action buttons: Start, Stop, Run Now, Edit, Delete
|
||||
- Status indicators: Running (green pulse), Stopped (gray), Failed (red)
|
||||
|
||||
4. **Register the tab**: Add Scheduler tab to dashboard navigation.
|
||||
|
||||
### PHASE 3 — Verification (MUST)
|
||||
|
||||
1. Create a test schedule with a simple agent task and verify it appears in the UI
|
||||
2. Test start/stop/run-now actions
|
||||
3. Verify execution stats update after runs
|
||||
4. Verify schedules persist across server restarts
|
||||
5. Verify no regressions in existing functionality
|
||||
6. Document what was implemented
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## PROMPT 3: Jobs Management Tab (G3 — Phase 1, Critical)
|
||||
|
||||
You are an expert AI engineer. Your task: **Add a Jobs Management dashboard tab to PraisonAIUI** that surfaces the existing async Jobs API from the PraisonAI package.
|
||||
|
||||
### Context
|
||||
|
||||
PraisonAI package has a complete async jobs system:
|
||||
- **Jobs directory**: `~/praisonai-package/src/praisonai/praisonai/jobs/` (6 files)
|
||||
- `executor.py` (14KB) — `JobExecutor` class:
|
||||
- `__init__(store, max_concurrent, default_timeout, cleanup_interval)`
|
||||
- `submit(job)` — submit job for execution
|
||||
- `cancel(job_id)` — cancel running job
|
||||
- `start()` / `stop()` — executor lifecycle
|
||||
- `register_progress_callback(job_id, callback)` — real-time progress
|
||||
- `_run_agent(job)` / `_run_recipe(job)` / `_run_praisonai_agents(job)` — multiple execution modes
|
||||
- `_send_webhook(job)` — webhook notifications on completion
|
||||
- `get_stats()` — executor statistics
|
||||
- `router.py` (11KB) — FastAPI router (`create_router(store, executor)`):
|
||||
- `POST /jobs` → `submit_job` (returns 202 + Location header + Retry-After)
|
||||
- `GET /jobs` → `list_jobs` (filter by status, session_id, pagination)
|
||||
- `GET /jobs/{id}/status` → `get_job_status`
|
||||
- `GET /jobs/{id}/result` → `get_job_result` (409 if not complete)
|
||||
- `DELETE /jobs/{id}/cancel` → `cancel_job` (409 if already complete)
|
||||
- `DELETE /jobs/{id}` → `delete_job` (only completed)
|
||||
- `GET /jobs/{id}/stream` → `stream_job` (SSE: status/progress/result/error events)
|
||||
- Supports idempotency via `Idempotency-Key` header
|
||||
- `models.py` (10KB) — `Job`, `JobStatus`, `JobSubmitRequest`, `JobSubmitResponse`, `JobStatusResponse`, `JobResultResponse`, `JobListResponse`
|
||||
- `store.py` (7KB) — `JobStore` — in-memory + persistent storage
|
||||
- `server.py` (5KB) — standalone server mounting the router
|
||||
|
||||
### PHASE 1 — Analysis (MUST complete before implementing)
|
||||
|
||||
1. **Read the full jobs system**: Go through every file in `~/praisonai-package/src/praisonai/praisonai/jobs/`:
|
||||
- `models.py` — understand all DTOs and status enum
|
||||
- `store.py` — understand storage backend (how jobs are persisted, queried)
|
||||
- `executor.py` — understand execution lifecycle (submit → execute → complete/fail)
|
||||
- `router.py` — understand all HTTP endpoints and their contracts
|
||||
- `server.py` — understand how the standalone server mounts the router
|
||||
|
||||
2. **Determine integration approach**: The jobs router is a FastAPI router. PraisonAIUI uses Starlette. Determine:
|
||||
- Can the jobs router be mounted directly in PraisonAIUI's Starlette app?
|
||||
- Or do we need to adapt the endpoints?
|
||||
- How to share the `JobStore` and `JobExecutor` instances with the main app
|
||||
|
||||
3. **Gap Analysis**: Document what's needed:
|
||||
- Backend: Mount or adapt the jobs router into PraisonAIUI
|
||||
- Frontend: Jobs dashboard showing job list, status, progress, results with real-time SSE updates
|
||||
|
||||
4. **Plan**: Step-by-step with exact files.
|
||||
|
||||
### PHASE 2 — Implementation (MUST)
|
||||
|
||||
1. **Backend — Mount Jobs API** in PraisonAIUI:
|
||||
- Initialize `JobStore` and `JobExecutor` in `create_app()`
|
||||
- Mount the jobs router at `/api/jobs/*` or adapt endpoints to Starlette
|
||||
- Ensure the executor starts when the app starts and stops when it stops
|
||||
|
||||
2. **Frontend — Add Jobs dashboard page**:
|
||||
- Jobs list: table with columns (ID, agent, status, progress %, submitted, duration, cost)
|
||||
- Status badges: Pending (gray), Running (blue pulse), Completed (green), Failed (red), Cancelled (yellow)
|
||||
- Real-time progress: Use SSE from `/jobs/{id}/stream` to update progress bars
|
||||
- Job detail view: expandable row showing full result, error message, webhook status
|
||||
- Actions: Submit new job (form), Cancel running job, Delete completed job
|
||||
- Filters: by status, date range, agent
|
||||
|
||||
3. **Register the tab**: Add Jobs tab to dashboard navigation.
|
||||
|
||||
### PHASE 3 — Verification (MUST)
|
||||
|
||||
1. Submit a test job via the UI and verify it appears in the list
|
||||
2. Verify real-time progress updates via SSE
|
||||
3. Test cancel and delete actions
|
||||
4. Verify job results are displayed correctly after completion
|
||||
5. Verify no regressions
|
||||
6. Document what was implemented
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## PROMPT 4: Usage Analytics Upgrade (G6 — Phase 1, Critical)
|
||||
|
||||
You are an expert AI engineer. Your task: **Upgrade PraisonAIUI's usage analytics** from basic token counters to per-model cost tracking with time-series charts.
|
||||
|
||||
### Context
|
||||
|
||||
Current state in PraisonAIUI (`~/PraisonAIUI/src/praisonaiui/server.py`):
|
||||
- `_usage_stats` — simple in-memory dict tracking basic token counts
|
||||
- `GET /api/usage` — returns this dict as JSON
|
||||
- No cost calculation, no per-model breakdown, no time-series data, no charts
|
||||
|
||||
OpenClaw comparison: ~80KB of usage view code with per-model costs, per-session breakdown, time-series charts, export functionality.
|
||||
|
||||
### PHASE 1 — Analysis (MUST complete before implementing)
|
||||
|
||||
1. **Read PraisonAIUI usage tracking**: Read `server.py` and search for `_usage_stats`, understand:
|
||||
- Where/when usage is tracked (during `run_agent`, on SSE events)
|
||||
- What data is currently captured (input_tokens, output_tokens, total_tokens)
|
||||
- How the data flows from agent execution to the stats dict
|
||||
|
||||
2. **Research model pricing**: Understand common LLM pricing models:
|
||||
- OpenAI: per-1K tokens, different rates for input vs output, varies by model
|
||||
- Anthropic: per-1K tokens, input vs output
|
||||
- Google: per-1K tokens
|
||||
- Design a cost table data structure
|
||||
|
||||
3. **Design time-series storage**: Plan how to store usage data over time:
|
||||
- In-memory ring buffer with periodic flush to disk? SQLite? JSON file?
|
||||
- Granularity: per-request? per-minute? per-hour?
|
||||
- Retention: how much history to keep?
|
||||
|
||||
4. **Plan**: Step-by-step with exact files.
|
||||
|
||||
### PHASE 2 — Implementation (MUST)
|
||||
|
||||
1. **Backend — Enhanced usage tracking**:
|
||||
- Create a `UsageTracker` class (or enhance the existing tracking in `server.py`):
|
||||
- Track per-request: model, input_tokens, output_tokens, cost, timestamp, session_id, agent_name
|
||||
- Maintain aggregations: by model, by session, by agent, by time period
|
||||
- Cost calculation: configurable cost table (price per 1K input/output tokens per model)
|
||||
- Update `/api/usage` to return rich data:
|
||||
- `GET /api/usage` — summary (total cost, total tokens, by model, by period)
|
||||
- `GET /api/usage/details` — detailed time-series data for charts
|
||||
- `GET /api/usage/models` — per-model breakdown
|
||||
- `GET /api/usage/sessions` — per-session breakdown
|
||||
|
||||
2. **Backend — Cost table**:
|
||||
- Default cost table with common LLM model pricing
|
||||
- Configurable via YAML config (`cost_per_model` section)
|
||||
- Auto-detect model from provider responses
|
||||
|
||||
3. **Frontend — Usage analytics dashboard**:
|
||||
- Summary cards: Total cost ($), Total tokens, Requests count, Avg cost per request
|
||||
- Chart: Token/cost usage over time (line chart, selectable time range: 1h/24h/7d/30d)
|
||||
- Model breakdown: Bar chart or table showing cost per model
|
||||
- Session breakdown: Table showing per-session usage
|
||||
- Use a lightweight charting library (e.g., Chart.js via CDN, or SVG-based inline charts)
|
||||
|
||||
4. **Persistence**: Save usage data to a JSON/SQLite file so it survives server restarts.
|
||||
|
||||
### PHASE 3 — Verification (MUST)
|
||||
|
||||
1. Run an agent chat and verify usage data is captured with model and cost
|
||||
2. Verify `/api/usage` returns enriched data
|
||||
3. Verify charts render correctly in the dashboard
|
||||
4. Verify data persists across server restarts
|
||||
5. Verify no performance impact on chat response times
|
||||
6. Document what was implemented
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## PROMPT 5: Skills/Tools Management Tab (G4 — Phase 2, High)
|
||||
|
||||
You are an expert AI engineer. Your task: **Add a Skills/Tools Management dashboard tab to PraisonAIUI** that surfaces available tools and allows enable/disable/configuration.
|
||||
|
||||
### Context
|
||||
|
||||
PraisonAI package has tool infrastructure:
|
||||
- **Capabilities**: `~/praisonai-package/src/praisonai/praisonai/capabilities/` (27 files)
|
||||
- `skills.py` (3KB) — skills endpoint
|
||||
- `completions.py`, `responses.py`, `assistants.py`, `files.py`, `images.py`, `audio.py`, `embeddings.py`, `fine_tuning.py`, `batches.py`, `guardrails.py`, `moderations.py`, `ocr.py`, `rag.py`, `realtime.py`, `rerank.py`, `search.py`, `videos.py`, `mcp.py`, `a2a.py`, `messages.py`, `vector_stores.py`, `container_files.py`, `containers.py`, `passthrough.py`
|
||||
- **Tool resolver**: `~/praisonai-package/src/praisonai/praisonai/tool_resolver.py` (14KB) — dynamic tool resolution by name
|
||||
- **Tools directory**: `~/praisonai-package/src/praisonai/praisonai/tools/` — audio.py, glob_tool.py, grep_tool.py, multiedit.py
|
||||
- **Inbuilt tools**: `~/praisonai-package/src/praisonai/praisonai/inbuilt_tools/` — autogen_tools.py
|
||||
- **Skills examples**: `~/praisonai-package/examples/skills/` — basic_skill_usage.py, create_skill_example.py, custom_skill_example.py
|
||||
|
||||
### PHASE 1 — Analysis (MUST complete before implementing)
|
||||
|
||||
1. **Read the tool/skills system**:
|
||||
- `capabilities/skills.py` — understand the skills endpoint interface
|
||||
- `tool_resolver.py` — understand how tools are discovered, resolved, loaded
|
||||
- `tools/` directory — understand the built-in tool pattern
|
||||
- `capabilities/__init__.py` — understand how capabilities are registered and discovered
|
||||
- Skills examples — understand the user-facing skill creation pattern
|
||||
|
||||
2. **Understand capability registration**: How does PraisonAI know which capabilities are available?
|
||||
- Are they auto-discovered? Explicitly registered? Config-driven?
|
||||
- Can individual capabilities be enabled/disabled?
|
||||
|
||||
3. **Gap Analysis**: Document what's needed:
|
||||
- API: Endpoint to list tools, get tool details, enable/disable, set API keys
|
||||
- Frontend: Skills tab with tool catalog, status toggles, API key configuration
|
||||
- Integration: How to wire capability enable/disable to the provider system
|
||||
|
||||
4. **Plan**: Step-by-step with exact files.
|
||||
|
||||
### PHASE 2 — Implementation (MUST)
|
||||
|
||||
1. **Backend — Skills API** in PraisonAIUI:
|
||||
- `GET /api/skills` — List all available tools/skills with status (name, type, enabled, description, required_keys)
|
||||
- `PUT /api/skills/{name}` — Enable/disable a skill
|
||||
- `PUT /api/skills/{name}/config` — Set API keys or configuration for a skill
|
||||
- `GET /api/skills/{name}` — Get detailed info about a specific skill
|
||||
|
||||
2. **Frontend — Skills dashboard page**:
|
||||
- Tool catalog: Grid/list of available tools with icons, names, descriptions
|
||||
- Status toggles: Enable/disable switch per tool
|
||||
- Configuration: Expandable config section per tool for API keys and settings
|
||||
- Categories: Group by type (built-in, capabilities, custom)
|
||||
- Search/filter: Find tools by name or category
|
||||
|
||||
3. **Register the tab**: Add Skills tab to dashboard navigation.
|
||||
|
||||
### PHASE 3 — Verification (MUST)
|
||||
|
||||
1. Verify the skills list loads with correct tool inventory
|
||||
2. Test enable/disable toggle and verify it affects agent tool availability
|
||||
3. Test API key configuration
|
||||
4. Verify no regressions
|
||||
5. Document what was implemented
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## PROMPT 6: Agent CRUD from Dashboard (G7 — Phase 2, High)
|
||||
|
||||
You are an expert AI engineer. Your task: **Add full Agent CRUD (Create, Update, Delete) to the PraisonAIUI dashboard**, extending beyond the current read-only agent listing.
|
||||
|
||||
### Context
|
||||
|
||||
Current state:
|
||||
- PraisonAIUI `server.py`: `GET /agents` returns a list of registered agents (read-only)
|
||||
- PraisonAI gateway: `WebSocketGateway.register_agent(agent, agent_id)` and `unregister_agent(agent_id)` exist
|
||||
- Agents are currently registered programmatically via Python code, not from the UI
|
||||
|
||||
OpenClaw comparison: Full agent CRUD with file editing (system prompt, instructions), tool profile overrides (allow/deny lists), identity management (name, avatar).
|
||||
|
||||
### PHASE 1 — Analysis (MUST complete before implementing)
|
||||
|
||||
1. **Read the agent system end-to-end**:
|
||||
- `~/PraisonAIUI/src/praisonaiui/server.py` — how agents are registered, listed, used during `run_agent`
|
||||
- `~/praisonai-package/src/praisonai/praisonai/gateway/server.py` — `register_agent()`, `unregister_agent()`, `get_agent()`, `list_agents()`, `_create_agents_from_config()`
|
||||
- Understand the Agent class from praisonaiagents: what properties can be configured?
|
||||
|
||||
2. **Understand agent configuration format**:
|
||||
- How are agents defined in YAML? What fields?
|
||||
- System prompt, instructions, tool lists, model selection, temperature, etc.
|
||||
- How are agents loaded from config at startup?
|
||||
|
||||
3. **Design the CRUD model**: What data does agent create/update need?
|
||||
- Name, description, system prompt, instructions, model, temperature
|
||||
- Tool allow/deny lists
|
||||
- Avatar/icon
|
||||
|
||||
4. **Plan**: Step-by-step with exact files.
|
||||
|
||||
### PHASE 2 — Implementation (MUST)
|
||||
|
||||
1. **Backend — Agent CRUD endpoints** in PraisonAIUI:
|
||||
- `GET /agents` — (existing) List agents with full details
|
||||
- `POST /agents` — Create a new agent (name, description, system_prompt, instructions, model, tools, config)
|
||||
- `PUT /agents/{id}` — Update agent configuration
|
||||
- `DELETE /agents/{id}` — Remove an agent
|
||||
- `GET /agents/{id}` — Get detailed agent info including system prompt and tools
|
||||
- Persist agent definitions to a YAML/JSON file
|
||||
|
||||
2. **Frontend — Agent editor**:
|
||||
- Agent list with Create New button
|
||||
- Agent editor form: name, description, model selector, temperature slider
|
||||
- System prompt editor: multi-line text area with syntax highlighting
|
||||
- Instructions editor: multi-line text area
|
||||
- Tool configuration: checkbox list of available tools
|
||||
- Save/Cancel/Delete buttons
|
||||
- Inline validation
|
||||
|
||||
3. **Integration**: New/updated agents should be live-registerable without server restart.
|
||||
|
||||
### PHASE 3 — Verification (MUST)
|
||||
|
||||
1. Create a new agent from the dashboard and verify it appears in the list
|
||||
2. Edit an agent's system prompt and verify the change takes effect in chat
|
||||
3. Delete an agent and verify it's removed
|
||||
4. Verify agents persist across server restarts
|
||||
5. Document what was implemented
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## PROMPT 7: Exec Approval Dashboard (G5 — Phase 2, High)
|
||||
|
||||
You are an expert AI engineer. Your task: **Add an Execution Approval dashboard to PraisonAIUI** that surfaces the existing approval system from the PraisonAI package bots.
|
||||
|
||||
### Context
|
||||
|
||||
PraisonAI package has a comprehensive approval system:
|
||||
- **Approval infrastructure** in `~/praisonai-package/src/praisonai/praisonai/bots/`:
|
||||
- `_approval.py` — Core approval logic
|
||||
- `_approval_base.py` — Base class for approval backends
|
||||
- `_discord_approval.py` — Discord-specific approval flow
|
||||
- `_slack_approval.py` — Slack-specific approval flow
|
||||
- `_telegram_approval.py` — Telegram-specific approval flow
|
||||
- `_http_approval.py` — HTTP webhook-based approvals
|
||||
- `_webhook_approval.py` — Webhook notification for approvals
|
||||
|
||||
The approval system allows agents to request human approval before executing certain actions (tool calls, external API calls, destructive operations).
|
||||
|
||||
### PHASE 1 — Analysis (MUST complete before implementing)
|
||||
|
||||
1. **Read the full approval system**:
|
||||
- `_approval_base.py` — understand the base protocol/interface for approvals
|
||||
- `_approval.py` — understand the core approval lifecycle (request → pending → approve/deny)
|
||||
- `_http_approval.py` — understand the HTTP-based approval mechanism (this is most relevant for UI integration)
|
||||
- Each channel-specific approval file — understand how they present approval requests
|
||||
|
||||
2. **Understand the approval data model**:
|
||||
- What information is in an approval request? (agent, tool, arguments, risk level, timestamp)
|
||||
- What are the possible actions? (approve, deny, approve-always, deny-always)
|
||||
- How are policies stored? (auto-approve lists, always-deny lists)
|
||||
|
||||
3. **Determine integration approach**:
|
||||
- Can `_http_approval.py` be extended to serve as the UI backend?
|
||||
- Or do we need a separate approval queue accessible from PraisonAIUI?
|
||||
- Real-time: WebSocket for instant approval notifications?
|
||||
|
||||
4. **Plan**: Step-by-step with exact files.
|
||||
|
||||
### PHASE 2 — Implementation (MUST)
|
||||
|
||||
1. **Backend — Approval API** in PraisonAIUI:
|
||||
- `GET /api/approvals` — List pending approval requests
|
||||
- `POST /api/approvals/{id}/approve` — Approve a request
|
||||
- `POST /api/approvals/{id}/deny` — Deny a request
|
||||
- `GET /api/approvals/policies` — List approval policies (auto-approve, always-deny)
|
||||
- `PUT /api/approvals/policies` — Update policies
|
||||
- `GET /api/approvals/history` — Past approval decisions
|
||||
- WebSocket or SSE endpoint for real-time approval notifications
|
||||
|
||||
2. **Frontend — Approval dashboard page**:
|
||||
- Pending queue: Cards showing each pending request with agent name, action, arguments, risk level, timestamp
|
||||
- Approve/Deny buttons with optional "always" checkbox
|
||||
- Policy editor: Configure auto-approve/deny rules per tool, per agent
|
||||
- History: Table of past approvals with decision, timestamp, details
|
||||
- Real-time: New approvals appear instantly via WebSocket/SSE
|
||||
- Notification badge on the tab showing pending count
|
||||
|
||||
3. **Register the tab**: Add Approvals tab to dashboard navigation with badge.
|
||||
|
||||
### PHASE 3 — Verification (MUST)
|
||||
|
||||
1. Configure an agent with an approval-required tool
|
||||
2. Trigger the tool and verify an approval request appears in the dashboard
|
||||
3. Approve it and verify the agent continues execution
|
||||
4. Deny a request and verify the agent handles it gracefully
|
||||
5. Test auto-approve policy and verify it works
|
||||
6. Document what was implemented
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## PROMPT 8: OpenAI-Compatible API Routes (G — Phase 2, High)
|
||||
|
||||
You are an expert AI engineer. Your task: **Mount PraisonAI's 27 OpenAI-compatible capability endpoints in PraisonAIUI** so they are accessible via `/v1/*` routes.
|
||||
|
||||
### Context
|
||||
|
||||
PraisonAI package has 27 OpenAI-compatible capability endpoints:
|
||||
- **Directory**: `~/praisonai-package/src/praisonai/praisonai/capabilities/` (27 files)
|
||||
- Key endpoints: `completions.py`, `responses.py`, `assistants.py`, `files.py`, `images.py`, `audio.py`, `embeddings.py`, `fine_tuning.py`, `batches.py`, `guardrails.py`, `moderations.py`, `ocr.py`, `rag.py`, `realtime.py`, `rerank.py`, `search.py`, `skills.py`, `videos.py`, `mcp.py`, `a2a.py`, `messages.py`, `vector_stores.py`, `container_files.py`, `containers.py`, `passthrough.py`
|
||||
- `__init__.py` (9KB) — likely contains registration/routing logic
|
||||
|
||||
PraisonAIUI uses Starlette. The capabilities likely use FastAPI routers.
|
||||
|
||||
### PHASE 1 — Analysis (MUST complete before implementing)
|
||||
|
||||
1. **Read `capabilities/__init__.py`**: Understand how capabilities are registered, what router/app they expose
|
||||
2. **Read `completions.py`**: Understand the endpoint pattern (request/response format, OpenAI compatibility)
|
||||
3. **Read `responses.py`**: Understand the responses API endpoint
|
||||
4. **Understand the mount pattern**: How to integrate FastAPI routers into Starlette apps
|
||||
5. **Plan**: Determine which capabilities to mount, routing prefix (`/v1/`), authentication, and configuration
|
||||
|
||||
### PHASE 2 — Implementation (MUST)
|
||||
|
||||
1. **Mount capabilities in PraisonAIUI**:
|
||||
- Import the capabilities router/app from praisonai-package
|
||||
- Mount at `/v1/` prefix in PraisonAIUI's Starlette app (in `create_app()`)
|
||||
- Ensure proper CORS, authentication, and error handling
|
||||
- Key routes: `/v1/chat/completions`, `/v1/responses`, `/v1/embeddings`, `/v1/images/generations`, etc.
|
||||
|
||||
2. **Configuration**: Add capability enable/disable flags in PraisonAIUI config YAML
|
||||
|
||||
3. **Documentation**: Add API docs endpoint or link to capability documentation
|
||||
|
||||
### PHASE 3 — Verification (MUST)
|
||||
|
||||
1. Test `/v1/chat/completions` with a standard OpenAI SDK client
|
||||
2. Test `/v1/responses` endpoint
|
||||
3. Verify compatibility with OpenAI Python SDK
|
||||
4. Verify no regressions in existing PraisonAIUI functionality
|
||||
5. Document the available endpoints
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## PROMPT 9: Real-Time Log Streaming (G9 — Phase 3, Polish)
|
||||
|
||||
You are an expert AI engineer. Your task: **Upgrade PraisonAIUI's log viewer from polling to real-time WebSocket streaming**.
|
||||
|
||||
### Context
|
||||
|
||||
Current state in PraisonAIUI (`~/PraisonAIUI/src/praisonaiui/server.py`):
|
||||
- `_log_buffer` — in-memory deque (500 entries max)
|
||||
- `GET /api/logs` — returns the entire buffer as JSON (polling-based)
|
||||
- Frontend polls this endpoint periodically
|
||||
|
||||
Goal: Real-time log tailing via WebSocket, with level filtering and search.
|
||||
|
||||
### PHASE 1 — Analysis (MUST complete before implementing)
|
||||
|
||||
1. **Read current logging implementation**: Search `server.py` for `_log_buffer`, understand how logs are captured and stored
|
||||
2. **Understand Python logging integration**: How are Python logger messages routed to `_log_buffer`?
|
||||
3. **Design WebSocket approach**: Plan the WebSocket endpoint, message format, filtering protocol
|
||||
4. **Plan**: Step-by-step with exact files.
|
||||
|
||||
### PHASE 2 — Implementation (MUST)
|
||||
|
||||
1. **Backend — WebSocket log endpoint**:
|
||||
- `WS /api/logs/stream` — WebSocket endpoint that streams log entries in real-time
|
||||
- Support filter parameters: `level` (DEBUG/INFO/WARNING/ERROR), `search` (text match)
|
||||
- Keep the existing `GET /api/logs` for backward compatibility
|
||||
- Use Python logging handler that broadcasts to connected WebSocket clients
|
||||
|
||||
2. **Frontend — Enhanced log viewer**:
|
||||
- Real-time log display with auto-scroll
|
||||
- Level filter buttons (DEBUG, INFO, WARNING, ERROR) with color coding
|
||||
- Search box for text filtering
|
||||
- Pause/resume button to stop auto-scroll
|
||||
- Clear button
|
||||
- Timestamp formatting
|
||||
- Log level color coding (gray=DEBUG, blue=INFO, yellow=WARNING, red=ERROR)
|
||||
|
||||
### PHASE 3 — Verification (MUST)
|
||||
|
||||
1. Connect to the WebSocket and verify real-time log streaming
|
||||
2. Test level filtering
|
||||
3. Test search filtering
|
||||
4. Verify auto-scroll and pause/resume
|
||||
5. Verify backward compatibility of `GET /api/logs`
|
||||
6. Document what was implemented
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## PROMPT 10: Config Form Editor (G8 — Phase 3, Polish)
|
||||
|
||||
You are an expert AI engineer. Your task: **Upgrade PraisonAIUI's config editor from raw YAML to a schema-driven form editor**.
|
||||
|
||||
### Context
|
||||
|
||||
Current state:
|
||||
- PraisonAIUI `server.py`: `GET /api/config` returns raw YAML, `POST /api/config` writes raw YAML
|
||||
- PraisonAI package: `bots/_config_schema.py` — configuration schema definition
|
||||
- No form rendering, no validation, no guided editing
|
||||
|
||||
OpenClaw comparison: Full schema-validated form rendering with live apply.
|
||||
|
||||
### PHASE 1 — Analysis (MUST complete before implementing)
|
||||
|
||||
1. **Read current config handling**: `server.py` → `api_config_handler`, `load_config_from_yaml`
|
||||
2. **Read `_config_schema.py`**: Understand the config schema format (JSON Schema? Custom?)
|
||||
3. **Understand the config structure**: What sections exist? (provider, model, channels, agents, scheduler, etc.)
|
||||
4. **Design form rendering**: Plan how to render schema-driven forms in the frontend
|
||||
5. **Plan**: Step-by-step with exact files.
|
||||
|
||||
### PHASE 2 — Implementation (MUST)
|
||||
|
||||
1. **Backend — Config schema endpoint**:
|
||||
- `GET /api/config/schema` — Return the config schema (JSON Schema format)
|
||||
- `POST /api/config/validate` — Validate config changes before applying
|
||||
- `POST /api/config/apply` — Apply config changes with validation and live reload
|
||||
|
||||
2. **Frontend — Form editor**:
|
||||
- Tab within the Config page: "Form View" vs "YAML View" toggle
|
||||
- Auto-generated form from JSON Schema:
|
||||
- Text inputs for strings, number inputs for numbers
|
||||
- Toggle switches for booleans
|
||||
- Dropdowns for enums (model selection, provider selection)
|
||||
- Nested sections with collapsible panels
|
||||
- Validation: Real-time validation with error messages
|
||||
- Save button with confirmation
|
||||
- Reset to defaults button
|
||||
- Keep raw YAML editor as alternative view
|
||||
|
||||
### PHASE 3 — Verification (MUST)
|
||||
|
||||
1. Verify the form renders all config sections correctly
|
||||
2. Test editing a config value via form and verify it's saved
|
||||
3. Test validation with invalid values
|
||||
4. Verify toggle between form and YAML views
|
||||
5. Verify config changes take effect without restart (where possible)
|
||||
6. Document what was implemented
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## PROMPT 11: Session Advanced Operations (G10 — Phase 3, Polish)
|
||||
|
||||
You are an expert AI engineer. Your task: **Add advanced session operations to PraisonAIUI**: reset context, compact memory, and session preview.
|
||||
|
||||
### Context
|
||||
|
||||
Current state in PraisonAIUI (`server.py`):
|
||||
- `GET /sessions` — List sessions
|
||||
- `GET /sessions/{id}` — Get session detail
|
||||
- `GET /sessions/{id}/runs` — Get message history
|
||||
- `DELETE /sessions/{id}` — Delete session
|
||||
- `PATCH /sessions/{id}` — Rename/tag session
|
||||
- `POST /sessions` — Create session
|
||||
|
||||
Missing (present in OpenClaw): Reset context (clear memory but keep session), Compact memory (summarize old messages to reduce context), Preview (rich preview of session content).
|
||||
|
||||
### PHASE 1 — Analysis (MUST complete before implementing)
|
||||
|
||||
1. **Read current session system** in `server.py`: Understand how sessions store messages, how context is managed
|
||||
2. **Read session system in praisonai-package**: `bots/_session.py` — understand session state management
|
||||
3. **Design**: Plan reset (clear messages, keep metadata), compact (LLM-summarize old messages), preview (formatted message display)
|
||||
4. **Plan**: Step-by-step with exact files.
|
||||
|
||||
### PHASE 2 — Implementation (MUST)
|
||||
|
||||
1. **Backend — Advanced session endpoints**:
|
||||
- `POST /sessions/{id}/reset` — Clear all messages but keep session metadata
|
||||
- `POST /sessions/{id}/compact` — Summarize old messages using the LLM, replace them with a summary message
|
||||
- `GET /sessions/{id}/preview` — Return formatted preview (first/last messages, total count, token estimate)
|
||||
|
||||
2. **Frontend — Enhanced session management**:
|
||||
- Add action buttons to session list: Reset, Compact, Preview
|
||||
- Reset confirmation dialog
|
||||
- Compact: Show before/after message count and token savings
|
||||
- Preview: Modal showing session summary without loading full history
|
||||
|
||||
### PHASE 3 — Verification (MUST)
|
||||
|
||||
1. Test reset: verify messages are cleared, session metadata preserved
|
||||
2. Test compact: verify old messages are replaced with a summary
|
||||
3. Test preview: verify formatted preview is returned
|
||||
4. Verify no regressions in existing session operations
|
||||
5. Document what was implemented
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## PROMPT 12: Auth Enhancements (G11 — Phase 3, Polish)
|
||||
|
||||
You are an expert AI engineer. Your task: **Enhance PraisonAIUI's authentication** from a single `require_auth` flag to multi-mode auth support.
|
||||
|
||||
### Context
|
||||
|
||||
Current state in PraisonAIUI (`server.py`):
|
||||
- `require_auth: bool` parameter in `create_app()` — single flag
|
||||
- No token management, no API key support, no user-level access control
|
||||
|
||||
OpenClaw comparison: Token + password + trusted-proxy + device auth modes.
|
||||
|
||||
PraisonAI package security: `~/praisonai-package/src/praisonai/praisonai/security/` — security module (read this first).
|
||||
|
||||
### PHASE 1 — Analysis (MUST complete before implementing)
|
||||
|
||||
1. **Read current auth**: `server.py` → understand how `require_auth` is implemented
|
||||
2. **Read praisonai-package security**: `~/praisonai-package/src/praisonai/praisonai/security/` — understand what security infrastructure exists
|
||||
3. **Design multi-mode auth**:
|
||||
- API key auth (for programmatic access)
|
||||
- Token/session auth (for dashboard users)
|
||||
- Optional password auth (for initial setup)
|
||||
4. **Plan**: Step-by-step with exact files.
|
||||
|
||||
### PHASE 2 — Implementation (MUST)
|
||||
|
||||
1. **Backend — Auth middleware**:
|
||||
- API key authentication: `X-API-Key` header or `?api_key=` query param
|
||||
- Session token authentication: JWT or session cookie for dashboard
|
||||
- Configurable auth mode in YAML config
|
||||
- Auth middleware in Starlette that checks configured mode
|
||||
|
||||
2. **Frontend — Auth UI**:
|
||||
- Login page (if password auth enabled)
|
||||
- API key display/rotation in settings
|
||||
- Session management (logout, token refresh)
|
||||
|
||||
3. **Configuration**: Auth section in YAML config with mode selection and credentials
|
||||
|
||||
### PHASE 3 — Verification (MUST)
|
||||
|
||||
1. Test API key auth with curl
|
||||
2. Test session auth via dashboard login
|
||||
3. Verify unauthenticated requests are rejected
|
||||
4. Verify auth can be disabled for development
|
||||
5. Document auth configuration options
|
||||
@@ -1,81 +0,0 @@
|
||||
---
|
||||
description: PraisonAIUI product categories and differentiation
|
||||
---
|
||||
|
||||
# UI Product Categories
|
||||
|
||||
PraisonAIUI supports three distinct styles, each serving a different use case:
|
||||
|
||||
## 1. Chat (`style: chat`)
|
||||
- Full-screen conversational interface (like ChatGPT)
|
||||
- Sidebar with session/conversation history
|
||||
- Streaming responses, thinking indicators, tool calls
|
||||
- Best for: single-agent chat, customer support, Q&A bots
|
||||
|
||||
## 2. Playground (`style: playground`)
|
||||
- Input/output panel layout
|
||||
- Agent selection, model switching, endpoint configuration
|
||||
- Session management with agent profiles
|
||||
- Best for: multi-agent experimentation, developer testing, agent debugging
|
||||
|
||||
## 3. UI Components (Widget mode)
|
||||
- Embeddable components (copilot widget, sidebar panel, floating button)
|
||||
- Integrates into existing apps/docs sites
|
||||
- Configurable position: bottom-right, bottom-left, top-right, top-left
|
||||
- Best for: adding AI to existing products, documentation copilots
|
||||
|
||||
## Key Differentiators
|
||||
- **Chat** = conversation-first, full-page, session history
|
||||
- **Playground** = multi-agent, experimentation, side-by-side panels
|
||||
- **Components** = embeddable widgets for existing apps
|
||||
|
||||
|
||||
When using AI, we mainly and primarily use PraisonAI as the backend ~/praisonai-package
|
||||
When using Platform, we mainly and primarily use PraisonAI (Gateway) as the backend ~/praisonai-package
|
||||
We will also support other providers, but PraisonAI will be the primary.
|
||||
PraisonAI already has memory, knowledge, session management, and more. So where possible we will use PraisonAI's features.
|
||||
|
||||
## PraisonAI Backend Capabilities (~/praisonai-package)
|
||||
|
||||
The backend (`praisonaiagents`) already provides these features. The UI's job is to surface them:
|
||||
|
||||
- **Gateway**: EventType enum (20 types), GatewayEvent, GatewayMessage, GatewaySessionProtocol, GatewayClientProtocol
|
||||
- **Streaming**: StreamEventType (REQUEST_START, FIRST_TOKEN, DELTA_TEXT, DELTA_TOOL_CALL, TOOL_CALL_END, STREAM_END, ERROR), StreamEvent, StreamMetrics, StreamEventEmitter
|
||||
- **Memory**: Short-term, long-term, user-specific, auto-memory, file memory, rules, workflows (76KB+ implementation)
|
||||
- **Knowledge**: RAG, vector store, chunking, query engine, rerankers, readers (41KB+ knowledge.py)
|
||||
- **Sessions**: Full Session API with state persistence, agent chat history, memory/knowledge integration
|
||||
- **Hooks**: Registry, middleware, runner, events, types (65KB+ system)
|
||||
- **Approval**: Full human-in-the-loop approval with backends, registry, protocols
|
||||
- **Bots/Channels**: Telegram (via gateway.yaml channel routing), extensible to Slack/Discord/WhatsApp etc. (Via Gateway)
|
||||
- **Other**: MCP, guardrails, planning, sandbox, plugins, tools, thinking, escalation, checkpoints
|
||||
|
||||
## Goal of PraisonAIUI
|
||||
|
||||
One of the primary goals is: **make the web UI enable and surface these existing PraisonAI backend features**.
|
||||
Except for the web UI itself, PraisonAI supports everything. This project fills that gap.
|
||||
|
||||
## Provider Protocol Architecture (Extensibility)
|
||||
|
||||
PraisonAIUI is **provider-agnostic**. The architecture uses a protocol-driven design so any AI backend can be swapped in:
|
||||
|
||||
- **`BaseProvider`** (`src/praisonaiui/provider.py`): Abstract base class any backend implements. Only `run()` is required — yields `RunEvent` objects.
|
||||
- **`RunEvent`**: Structured dataclass with `type` (27 `RunEventType` values), optional fields for content, tool calls, reasoning, errors, agent info, and arbitrary `extra_data`.
|
||||
- **`PraisonAIProvider`** (`src/praisonaiui/providers/__init__.py`): Default implementation wrapping the `@aiui.reply` callback system. Maps legacy queue events to `RunEvent`.
|
||||
|
||||
### Swapping Providers
|
||||
|
||||
```python
|
||||
import praisonaiui
|
||||
|
||||
# Use any custom provider:
|
||||
praisonaiui.set_provider(MyLangChainProvider())
|
||||
# or
|
||||
praisonaiui.set_provider(MyCrewAIProvider())
|
||||
```
|
||||
|
||||
### Design Principles
|
||||
- **Protocol-first**: All communication between UI and backend goes through `RunEvent` protocol — no tight coupling
|
||||
- **PraisonAI primary, others welcome**: PraisonAI is the default, but the architecture doesn't lock you in
|
||||
- **Frontend already ready**: The frontend `useSSE.ts` hook and components (`ToolCallDisplay`, `ThinkingSteps`, `MultimediaElements`) already handle all 27 `RunEventType` values — swapping the backend requires no frontend changes
|
||||
|
||||
Aim is by default it need to be protocol driven, so we can easily extend, or replace any providers or function accordingly. At the same time it also need to be capable of handling clients, and the clients will be of config driven, same like chainlit or yaml config and it should work.
|
||||
@@ -1,839 +0,0 @@
|
||||
---
|
||||
description: Update install.sh and deploy PraisonAI to Kubernetes via Helm (CI/CD Pipeline)
|
||||
---
|
||||
|
||||
# Install.sh Update & Helm Deployment Workflow
|
||||
|
||||
Complete guide for updating the PraisonAI install script and deploying to Kubernetes via the full CI/CD pipeline.
|
||||
|
||||
**⚠️ CRITICAL**: This workflow contains **NO SECRETS**. All sensitive values (tokens, passwords) must be passed via environment variables or external secret management.
|
||||
|
||||
## 📁 Key Locations (MUST KNOW)
|
||||
|
||||
### Scripts
|
||||
| File/Resource | Absolute Path | Purpose |
|
||||
|---------------|---------------|----------|
|
||||
| **install.sh** | `/Users/praison/praisonai-package/src/praisonai/scripts/install.sh` | Main bash installer |
|
||||
| **install.ps1** | `/Users/praison/praisonai-package/src/praisonai/scripts/install.ps1` | PowerShell installer |
|
||||
|
||||
### CI/CD Pipeline (GitHub → ACR → Helm → K8s)
|
||||
| File/Resource | Absolute Path | Purpose |
|
||||
|---------------|---------------|----------|
|
||||
| **GitHub Workflow** | `/Users/praison/Sites/localhost/praisonai/.github/workflows/azure-pipeline.yaml` | CI/CD pipeline triggered on git push |
|
||||
| **Dockerfile.php** | `/Users/praison/Sites/localhost/praisonai/Dockerfile.php` | PHP container build |
|
||||
| **Dockerfile.nginx** | `/Users/praison/Sites/localhost/praisonai/Dockerfile.nginx` | Nginx container build |
|
||||
| **Dockerfile.init** | `/Users/praison/Sites/localhost/praisonai/Dockerfile.init` | Init container build |
|
||||
|
||||
### Helm Deployment
|
||||
| File/Resource | Absolute Path | Purpose |
|
||||
|---------------|---------------|----------|
|
||||
| **Helm Charts** | `/Users/praison/repos/person/helmcharts/` | All Kubernetes deployments |
|
||||
| **wb_azure Chart** | `/Users/praison/repos/person/helmcharts/charts/wb_azure/` | PraisonAI WordPress deployment |
|
||||
| **Production Values** | `/Users/praison/Sites/localhost/praisonai/values-praisonai-production.yaml` | Production Helm config |
|
||||
| **Local Values** | `/Users/praison/Sites/localhost/praisonai/values-local.yaml` | Local development config |
|
||||
| **Deployment Docs** | `/Users/praison/Sites/localhost/praisonai/DEPLOYMENT.md` | Deployment documentation |
|
||||
| **Deployment Makefile** | `/Users/praison/Sites/localhost/praisonai/Makefile` | Deployment automation |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Full CI/CD Pipeline Overview
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ Git Push │────▶│ GitHub Actions │────▶│ Azure ACR │
|
||||
│ (master) │ │ azure-pipeline │ │ Image Build │
|
||||
└─────────────────┘ └──────────────────┘ └────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ Kubernetes │◀────│ Helm Upgrade │◀────│ Update Image │
|
||||
│ Deployment │ │ (values.yaml) │ │ Tag in Values │
|
||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
### Pipeline Steps:
|
||||
1. **Git push** to master branch
|
||||
2. **GitHub Actions** triggers (`.github/workflows/azure-pipeline.yaml`)
|
||||
3. **Build** Docker images (nginx, php, init)
|
||||
4. **Push** to Azure Container Registry (ACR)
|
||||
5. **Update** Helm values with new image tag
|
||||
6. **Deploy** using Helm upgrade
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Phase 0 - Fully Automated CI/CD Pipeline
|
||||
|
||||
### Complete Auto-Deploy Architecture
|
||||
|
||||
```
|
||||
Git Push ──▶ Build Images ──▶ Trigger Deploy ──▶ Helm Upgrade ──▶ Production
|
||||
│ │ │ │
|
||||
│ ▼ ▼ ▼
|
||||
│ ACR Push helmcharts wb_azure chart
|
||||
│ (pa-php:SHA) repository (K8s deploy)
|
||||
│
|
||||
└─── install.sh ────────────────────────────────────────────────▶ praison.ai/install.sh
|
||||
```
|
||||
|
||||
### Step 0.1: Build Workflow (Automatic on Git Push)
|
||||
|
||||
**File**: `/Users/praison/Sites/localhost/praisonai/.github/workflows/azure-pipeline.yaml`
|
||||
|
||||
**Repository**: `https://github.com/MervinPraison/praison.ai`
|
||||
|
||||
This workflow triggers on every push to `master`:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [master]
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
1. **Syncs install.sh** from PraisonAI repository (only if changed!)
|
||||
- Checks out `MervinPraison/PraisonAI`
|
||||
- Compares `install.sh` and `install.ps1` with existing web files
|
||||
- **Only copies if files have actually changed** (avoids unnecessary redeploys)
|
||||
- This ensures `https://praison.ai/install.sh` is always latest
|
||||
2. Downloads env files from Azure Storage
|
||||
3. Builds multi-arch Docker images (linux/amd64, linux/arm64)
|
||||
4. Pushes to Azure Container Registry: `praison.azurecr.io/pa/`
|
||||
5. **Triggers Helm deployment** via `repository_dispatch` event
|
||||
|
||||
**Key Step - Automatic Deploy Trigger:**
|
||||
```yaml
|
||||
- name: Trigger Helm Deployment
|
||||
run: |
|
||||
SHORT_SHA=$(git rev-parse --short HEAD)
|
||||
curl -X POST \
|
||||
-H "Authorization: token ${{ secrets.HELM_REPO_TOKEN }}" \
|
||||
-d '{
|
||||
"event_type": "deploy_wb_azure",
|
||||
"client_payload": {
|
||||
"image_tag": "'"$SHORT_SHA"'",
|
||||
"source_repo": "'"${{ github.repository }}"'",
|
||||
"source_commit": "'"${{ github.sha }}"'"
|
||||
}
|
||||
}' \
|
||||
https://api.github.com/repos/praison/helmcharts/dispatches
|
||||
```
|
||||
|
||||
### Step 0.2: Deploy Workflow (Triggered Automatically)
|
||||
|
||||
**File**: `/Users/praison/repos/person/helmcharts/.github/workflows/helm-upgrade-with-image.yml`
|
||||
|
||||
Listens for `repository_dispatch` events:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
repository_dispatch:
|
||||
types: [deploy_wb_azure, deploy_tcs_azure, deploy_tamilmanna_azure]
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
1. Receives image tag from build workflow
|
||||
2. Runs `helm upgrade --install wb_azure` with new image tag
|
||||
3. Waits for rollout to complete
|
||||
4. Verifies deployment
|
||||
|
||||
**Result**: Every git push automatically builds AND deploys!
|
||||
|
||||
### Required GitHub Secrets
|
||||
|
||||
For the automated CI/CD to work, you need these secrets configured:
|
||||
|
||||
**In praisonai site repository** (`https://github.com/MervinPraison/praison.ai`):
|
||||
| Secret | Purpose |
|
||||
|--------|---------|
|
||||
| `AZURE_CREDENTIALS` | Azure login for ACR and AKS |
|
||||
| `AZURE_USERNAME` | ACR username |
|
||||
| `AZURE_PASSWORD` | ACR password |
|
||||
| `AZURE_STORAGE_KEY` | Download env files from Azure Storage |
|
||||
| `HELM_REPO_TOKEN` | **NEW**: Trigger deploy workflow in helmcharts repo |
|
||||
|
||||
**In helmcharts repository** (`/Users/praison/repos/person/helmcharts/.github/workflows/`):
|
||||
| Secret | Purpose |
|
||||
|--------|---------|
|
||||
| `AZURE_CREDENTIALS` | Azure login for AKS |
|
||||
| `AKS_CLUSTER_NAME` | Kubernetes cluster name |
|
||||
| `AKS_RESOURCE_GROUP` | Azure resource group |
|
||||
|
||||
**To add HELM_REPO_TOKEN**:
|
||||
1. Go to GitHub Settings → Developer settings → Personal access tokens
|
||||
2. Create token with `repo` scope
|
||||
3. Add as secret `HELM_REPO_TOKEN` in https://github.com/MervinPraison/praison.ai
|
||||
|
||||
**Current status**: ✅ Already configured (set via `gh secret set`)!
|
||||
|
||||
**Images built:**
|
||||
- `praison.azurecr.io/pa/pa-nginx:SHORT_SHA`
|
||||
- `praison.azurecr.io/pa/pa-nginx:master`
|
||||
- `praison.azurecr.io/pa/pa-php:SHORT_SHA`
|
||||
- `praison.azurecr.io/pa/pa-php:master`
|
||||
- `praison.azurecr.io/pa/pa-init:SHORT_SHA`
|
||||
- `praison.azurecr.io/pa/pa-init:master`
|
||||
|
||||
### Step 0.2: Update Helm Values with New Image Tag
|
||||
|
||||
After the ACR build completes, update the Helm values file to use the new image:
|
||||
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
|
||||
# Get the short SHA from the latest commit (matches the Docker tag)
|
||||
SHORT_SHA=$(git rev-parse --short HEAD)
|
||||
|
||||
# Update values file with new image tag
|
||||
helm upgrade praisonai /Users/praison/repos/person/helmcharts/charts/wb_azure \
|
||||
-f values-praisonai-production.yaml \
|
||||
--set image.tag=$SHORT_SHA \
|
||||
--namespace default \
|
||||
--timeout 10m
|
||||
```
|
||||
|
||||
**Alternative**: Update values file permanently:
|
||||
|
||||
```bash
|
||||
# Edit values-praisonai-production.yaml to set image.tag
|
||||
sed -i "s/tag: \".*\"/tag: \"$SHORT_SHA\"/" values-praisonai-production.yaml
|
||||
|
||||
# Then commit and push the updated values
|
||||
git add values-praisonai-production.yaml
|
||||
git commit -m "ci: update image tag to $SHORT_SHA"
|
||||
git push origin master
|
||||
```
|
||||
|
||||
### Step 0.3: Full Automated Script (For CI/CD Integration)
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# deploy-after-build.sh - Run after ACR build completes
|
||||
|
||||
set -e
|
||||
|
||||
SHORT_SHA=$(git rev-parse --short HEAD)
|
||||
NAMESPACE=default
|
||||
RELEASE_NAME=praisonai
|
||||
CHART_PATH=/Users/praison/repos/person/helmcharts/charts/wb_azure
|
||||
VALUES_FILE=/Users/praison/Sites/localhost/praisonai/values-praisonai-production.yaml
|
||||
|
||||
echo "🚀 Deploying PraisonAI with image tag: $SHORT_SHA"
|
||||
|
||||
# Update Helm deployment with new image tag
|
||||
helm upgrade --install $RELEASE_NAME $CHART_PATH \
|
||||
-f $VALUES_FILE \
|
||||
--set image.tag=$SHORT_SHA \
|
||||
--namespace $NAMESPACE \
|
||||
--timeout 10m \
|
||||
--atomic
|
||||
|
||||
echo "✅ Deployment complete!"
|
||||
echo ""
|
||||
echo "Verify with:"
|
||||
echo " kubectl get pods -n $NAMESPACE -l app.kubernetes.io/instance=$RELEASE_NAME"
|
||||
echo " helm status $RELEASE_NAME -n $NAMESPACE"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 0.4: Extend GitHub Actions for Automatic Helm Deployment
|
||||
|
||||
To make the CI/CD fully automated (build → deploy), extend the GitHub Actions workflow:
|
||||
|
||||
**File to edit**: `/Users/praison/Sites/localhost/praisonai/.github/workflows/azure-pipeline.yaml`
|
||||
|
||||
Add a new job after the `build` job:
|
||||
|
||||
```yaml
|
||||
deploy:
|
||||
needs: build # Wait for build to complete
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v2
|
||||
|
||||
- name: Azure Login
|
||||
uses: azure/login@v1
|
||||
with:
|
||||
creds: ${{ secrets.AZURE_CREDENTIALS }}
|
||||
|
||||
- name: Setup kubectl
|
||||
uses: azure/setup-kubectl@v3
|
||||
with:
|
||||
version: 'v1.28.0'
|
||||
|
||||
- name: Setup Helm
|
||||
uses: azure/setup-helm@v3
|
||||
with:
|
||||
version: 'v3.13.0'
|
||||
|
||||
- name: Get AKS credentials
|
||||
run: |
|
||||
az aks get-credentials \
|
||||
--resource-group your-resource-group \
|
||||
--name your-aks-cluster-name \
|
||||
--overwrite-existing
|
||||
|
||||
- name: Deploy with Helm
|
||||
run: |
|
||||
SHORT_SHA=$(git rev-parse --short HEAD)
|
||||
helm upgrade --install praisonai \
|
||||
/Users/praison/repos/person/helmcharts/charts/wb_azure \
|
||||
-f values-praisonai-production.yaml \
|
||||
--set image.tag=$SHORT_SHA \
|
||||
--namespace default \
|
||||
--timeout 10m \
|
||||
--atomic
|
||||
|
||||
- name: Verify deployment
|
||||
run: |
|
||||
kubectl rollout status deployment/php-nginx -n default
|
||||
helm status praisonai -n default
|
||||
```
|
||||
|
||||
**Requirements for automatic deploy:**
|
||||
1. GitHub repository secrets configured:
|
||||
- `AZURE_CREDENTIALS` - Azure service principal credentials
|
||||
- `AZURE_STORAGE_KEY` - For downloading env files
|
||||
- `AZURE_USERNAME` / `AZURE_PASSWORD` - ACR login
|
||||
2. AKS cluster access configured in Azure
|
||||
3. Helm and kubectl available in GitHub Actions runner
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Phase 1 — Update install.sh (Manual, When Needed)
|
||||
|
||||
### When to Update
|
||||
- New PraisonAI version released
|
||||
- New dependency requirements
|
||||
- New OS support needed
|
||||
- Bug fixes in installation process
|
||||
|
||||
### Step 1: Read Current install.sh
|
||||
|
||||
```bash
|
||||
# View the install script
|
||||
cat /Users/praison/praisonai-package/src/praisonai/scripts/install.sh
|
||||
```
|
||||
|
||||
Key sections in install.sh:
|
||||
- **Lines 1-50**: Header, usage, environment variables documentation
|
||||
- **Lines 51-150**: OS detection (macOS, Linux, Windows/WSL)
|
||||
- **Lines 151-300**: Python installation (version checks, package managers)
|
||||
- **Lines 301-450**: Virtual environment setup
|
||||
- **Lines 451-550**: PraisonAI package installation
|
||||
- **Lines 551-637**: PATH configuration, shell integration, verification
|
||||
|
||||
### Step 2: Make Changes
|
||||
|
||||
**Common Changes:**
|
||||
|
||||
#### Update Default Version
|
||||
```bash
|
||||
# Find this line (around line 70):
|
||||
PRAISONAI_VERSION="${PRAISONAI_VERSION:-latest}"
|
||||
|
||||
# Change to specific version if needed:
|
||||
PRAISONAI_VERSION="${PRAISONAI_VERSION:-1.5.0}"
|
||||
```
|
||||
|
||||
#### Add New Environment Variable
|
||||
```bash
|
||||
# Add to header section (after line 10, in the comment block):
|
||||
# PRAISONAI_NEW_FEATURE - Description (default: value)
|
||||
|
||||
# Add to actual code (around line 75):
|
||||
export PRAISONAI_NEW_FEATURE="${PRAISONAI_NEW_FEATURE:-default_value}"
|
||||
```
|
||||
|
||||
#### Update Python Version Requirements
|
||||
```bash
|
||||
# Find Python version check (around line 100-120):
|
||||
PYTHON_MIN_VERSION="3.9"
|
||||
|
||||
# Update if needed:
|
||||
PYTHON_MIN_VERSION="3.10"
|
||||
```
|
||||
|
||||
### Step 3: Test Changes
|
||||
|
||||
```bash
|
||||
# Test locally (dry run)
|
||||
cd /Users/praison/praisonai-package/src/praisonai/scripts
|
||||
bash install.sh --dry-run
|
||||
|
||||
# Test in Docker (full test)
|
||||
bash /Users/praison/praisonai-package/src/praisonai/scripts/test-install-smoke.sh
|
||||
```
|
||||
|
||||
### Step 4: Verify Both Scripts
|
||||
|
||||
```bash
|
||||
# Check install.sh syntax
|
||||
bash -n /Users/praison/praisonai-package/src/praisonai/scripts/install.sh
|
||||
|
||||
# Check install.ps1 syntax (if pwsh available)
|
||||
pwsh -Command "Get-Command /Users/praison/praisonai-package/src/praisonai/scripts/install.ps1"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Phase 2 — Deploy to Kubernetes (Helm)
|
||||
|
||||
### Pre-Deployment Checklist
|
||||
|
||||
```bash
|
||||
# 1. Verify kubectl connection
|
||||
kubectl get nodes
|
||||
|
||||
# 2. Check current Helm releases
|
||||
helm list -n default
|
||||
|
||||
# 3. Verify chart exists
|
||||
ls /Users/praison/repos/person/helmcharts/charts/wb_azure/
|
||||
```
|
||||
|
||||
### Deployment Types
|
||||
|
||||
#### A. Fresh Deployment (First Time)
|
||||
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
|
||||
# Option 1: Using Makefile
|
||||
make deploy
|
||||
|
||||
# Option 2: Manual helm command
|
||||
helm upgrade --install praisonai /Users/praison/repos/person/helmcharts/charts/wb_azure \
|
||||
-f values-praisonai-production.yaml \
|
||||
--namespace default \
|
||||
--timeout 10m \
|
||||
--atomic
|
||||
```
|
||||
|
||||
#### B. Update Existing Deployment
|
||||
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
|
||||
# Edit values file first
|
||||
vim values-praisonai-production.yaml
|
||||
|
||||
# Then apply
|
||||
make upgrade
|
||||
|
||||
# Or manually:
|
||||
helm upgrade praisonai /Users/praison/repos/person/helmcharts/charts/wb_azure \
|
||||
-f values-praisonai-production.yaml \
|
||||
--namespace default \
|
||||
--timeout 10m
|
||||
```
|
||||
|
||||
#### C. Local Development Deployment
|
||||
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
make local-deploy
|
||||
```
|
||||
|
||||
### Values File Structure
|
||||
|
||||
```yaml
|
||||
# /Users/praison/Sites/localhost/praisonai/values-praisonai-production.yaml
|
||||
|
||||
# Core settings
|
||||
replicaCount: 2
|
||||
|
||||
# Database
|
||||
dbHost: "10.0.0.11"
|
||||
dbUser: "bible_4"
|
||||
dbPassword: "changeme" # Override via --set
|
||||
|
||||
# OpenAI tokens (for plugin verification)
|
||||
openaiVerificationToken: "token-here"
|
||||
|
||||
# Feature toggles
|
||||
praisonai:
|
||||
enabled: true
|
||||
domain: praison.ai
|
||||
|
||||
whiteboard:
|
||||
enabled: true
|
||||
domain: whiteboard.gallery
|
||||
|
||||
# Disable other sites
|
||||
bible: { enabled: false }
|
||||
music: { enabled: false }
|
||||
save: { enabled: false }
|
||||
|
||||
# Resources
|
||||
resources:
|
||||
requests:
|
||||
cpu: 800m
|
||||
memory: 1024Mi
|
||||
limits:
|
||||
cpu: 2000m
|
||||
memory: 2048Mi
|
||||
|
||||
# Auto-scaling
|
||||
autoscaling:
|
||||
enabled: true
|
||||
minReplicas: 2
|
||||
maxReplicas: 10
|
||||
|
||||
# Ingress
|
||||
ingress:
|
||||
enabled: true
|
||||
className: nginx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Phase 3 — Verify Deployment
|
||||
|
||||
### Check Deployment Status
|
||||
|
||||
```bash
|
||||
# Using Makefile
|
||||
make status
|
||||
|
||||
# Manual checks
|
||||
helm status praisonai -n default
|
||||
kubectl get pods -l app.kubernetes.io/instance=praisonai -n default
|
||||
kubectl get svc -l app.kubernetes.io/instance=praisonai -n default
|
||||
```
|
||||
|
||||
### Verify All Resources
|
||||
|
||||
```bash
|
||||
# Pods should be Running
|
||||
kubectl get pods -n default | grep praisonai
|
||||
|
||||
# Services should be Active
|
||||
kubectl get svc -n default | grep praisonai
|
||||
|
||||
# Ingress should exist
|
||||
kubectl get ingress -n default | grep praisonai
|
||||
|
||||
# ConfigMaps
|
||||
kubectl get configmap -n default | grep nginx-config
|
||||
|
||||
# Secrets
|
||||
kubectl get secret -n default | grep db-password
|
||||
```
|
||||
|
||||
### Check Application Health
|
||||
|
||||
```bash
|
||||
# Port forward and test
|
||||
echo "Visit http://127.0.0.1:8080"
|
||||
kubectl port-forward svc/php-nginx 8080:80 -n default
|
||||
|
||||
# In another terminal:
|
||||
curl http://127.0.0.1:8080/test.php
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Phase 4 — Rollback (If Needed)
|
||||
|
||||
```bash
|
||||
# View revision history
|
||||
make history
|
||||
|
||||
# Rollback to previous revision
|
||||
make rollback
|
||||
|
||||
# Or manually:
|
||||
helm rollback praisonai 1 -n default
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Phase 5 — Troubleshooting
|
||||
|
||||
### Problem: "Resource exists and cannot be imported"
|
||||
|
||||
**Cause**: Existing Kubernetes resources not managed by Helm.
|
||||
|
||||
**Solution**: Adopt resources into Helm
|
||||
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
./scripts/adopt-resources.sh praisonai default
|
||||
```
|
||||
|
||||
Or manually annotate:
|
||||
|
||||
```bash
|
||||
# For any resource type
|
||||
kubectl annotate <resource-type> <name> \
|
||||
meta.helm.sh/release-name=praisonai \
|
||||
meta.helm.sh/release-namespace=default
|
||||
|
||||
kubectl label <resource-type> <name> \
|
||||
app.kubernetes.io/managed-by=Helm
|
||||
```
|
||||
|
||||
### Problem: Pods Not Starting
|
||||
|
||||
```bash
|
||||
# Check events
|
||||
kubectl get events -n default --sort-by='.lastTimestamp' | tail -20
|
||||
|
||||
# Check pod logs
|
||||
kubectl logs -l app.kubernetes.io/instance=praisonai -n default
|
||||
|
||||
# Describe pod for details
|
||||
kubectl describe pod <pod-name> -n default
|
||||
```
|
||||
|
||||
### Problem: Image Pull Errors
|
||||
|
||||
```bash
|
||||
# Check image pull secrets
|
||||
kubectl get secret acr-auth -n default
|
||||
|
||||
# Verify ACR auth exists
|
||||
kubectl create secret docker-registry acr-auth \
|
||||
--docker-server=praison.azurecr.io \
|
||||
--docker-username=<username> \
|
||||
--docker-password=<password> \
|
||||
-n default
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Phase 6 — Post-Deployment
|
||||
|
||||
### Update Documentation
|
||||
|
||||
If install.sh changed, update:
|
||||
1. `/Users/praison/PraisonAIDocs/docs/installation.mdx` — Installation docs
|
||||
2. `/Users/praison/praisonai-package/src/praisonai/scripts/README.md` — Script docs (if exists)
|
||||
|
||||
### Verify Website
|
||||
|
||||
```bash
|
||||
# Check praison.ai is accessible
|
||||
curl -I https://praison.ai
|
||||
|
||||
# Check whiteboard.gallery
|
||||
curl -I https://whiteboard.gallery
|
||||
```
|
||||
|
||||
### Monitor
|
||||
|
||||
```bash
|
||||
# Watch pods
|
||||
kubectl get pods -l app.kubernetes.io/instance=praisonai -n default -w
|
||||
|
||||
# Check resource usage
|
||||
kubectl top pods -l app.kubernetes.io/instance=praisonai -n default
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Reference: Helm Chart Structure
|
||||
|
||||
```
|
||||
/Users/praison/repos/person/helmcharts/charts/wb_azure/
|
||||
├── Chart.yaml # Chart metadata (name: wb, version: 1.0.1)
|
||||
├── values.yaml # Default values (fallback)
|
||||
├── templates/
|
||||
│ ├── deployment.yaml # Main php-nginx deployment
|
||||
│ ├── service.yaml # NodePort service
|
||||
│ ├── ingress.yaml # TLS + routing
|
||||
│ ├── nginx-configMap.yaml # Server configs
|
||||
│ ├── db-password-secret.yaml # DB credentials
|
||||
│ ├── pdb.yaml # Pod disruption budget
|
||||
│ ├── autoscalar.yml # HPA
|
||||
│ ├── cert-manager.yaml # TLS certificates
|
||||
│ └── _helpers.tpl # Template helpers
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Commands Reference
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| Deploy | `make deploy` |
|
||||
| Update | `make upgrade` |
|
||||
| Status | `make status` |
|
||||
| History | `make history` |
|
||||
| Rollback | `make rollback` |
|
||||
| Logs | `make logs` |
|
||||
| Restart | `make restart` |
|
||||
| Local dev | `make local-deploy` |
|
||||
| Dry run | `make dry-run` |
|
||||
| Lint | `make lint` |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Critical Rules
|
||||
|
||||
1. **Never commit SQL dumps**: `.gitignore` already excludes `*.sql` files
|
||||
2. **Never commit secrets**: Use `--set` or external secret management
|
||||
3. **Always test install.sh** after changes (use test-install-smoke.sh)
|
||||
4. **Always verify deployment** with `make status` after Helm operations
|
||||
5. **Use Infrastructure as Code**: All changes via Helm values files, never manual kubectl
|
||||
6. **Version control**: Commit values files (without secrets), never commit generated manifests
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Getting Help
|
||||
|
||||
If stuck:
|
||||
|
||||
1. Check `/Users/praison/Sites/localhost/praisonai/DEPLOYMENT.md` for detailed docs
|
||||
2. Check `/Users/praison/Sites/localhost/praisonai/INFRASTRUCTURE_AS_CODE_SUMMARY.md` for quick reference
|
||||
3. Run `helm status praisonai -n default` for deployment status
|
||||
4. Run `kubectl get events -n default` for cluster events
|
||||
5. View install.sh comments for usage examples (lines 1-50)
|
||||
|
||||
---
|
||||
|
||||
## 🔄 CI/CD Pipeline Summary (For New Agents)
|
||||
|
||||
### Complete Workflow (Fully Automated!)
|
||||
|
||||
```
|
||||
Developer Push ──────────────────────────────────────────────▶ Production
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐
|
||||
│ 1. Git Push to │───▶│ 2. GitHub Actions │───▶│ 3. Sync │
|
||||
│ master │ │ Trigger │ │ install.sh │
|
||||
└─────────────────┘ └──────────────────┘ └────────┬─────────┘
|
||||
│
|
||||
┌────────────────────────┘
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ 4. Azure ACR │
|
||||
│ Build Images │
|
||||
│ + Push │
|
||||
└────────┬─────────┘
|
||||
│
|
||||
──────▶┌──────────────────┐
|
||||
│ 5. Trigger Deploy│
|
||||
│ (repository_ │
|
||||
│ dispatch) │
|
||||
└────────┬─────────┘
|
||||
│
|
||||
┌─────────────────┐ ┌──────────────────┐ │
|
||||
│ 7. Production │◀───│ 6. Helm Upgrade │◀──┘
|
||||
│ Running │ │ Deploy │
|
||||
│ (includes │ │ │
|
||||
│ install.sh) │ │ │
|
||||
└─────────────────┘ └──────────────────┘
|
||||
```
|
||||
|
||||
**🎉 Fully Automated**: Git push → Build → Deploy (No manual steps!)
|
||||
|
||||
### Automatic install.sh Sync
|
||||
|
||||
**Key Point**: The workflow automatically syncs `install.sh` from `MervinPraison/PraisonAI` repository **only if changed**:
|
||||
|
||||
```yaml
|
||||
- name: Checkout PraisonAI for install.sh
|
||||
uses: actions/checkout@v2
|
||||
with:
|
||||
repository: MervinPraison/PraisonAI
|
||||
path: praisonai-package
|
||||
|
||||
- name: Sync install.sh to web folder (if changed)
|
||||
run: |
|
||||
# Only sync if files have actually changed
|
||||
if ! diff -q praisonai-package/src/praisonai/scripts/install.sh ./web/install.sh; then
|
||||
cp praisonai-package/src/praisonai/scripts/install.sh ./web/install.sh
|
||||
fi
|
||||
```
|
||||
|
||||
**Optimization**: Uses `diff` to compare files - only copies when install.sh or install.ps1 have actually changed. This avoids unnecessary Docker layer rebuilds and deployments.
|
||||
|
||||
**Result**: `https://praison.ai/install.sh` is automatically updated **only when the source files change**!
|
||||
|
||||
### How install.sh is Served
|
||||
|
||||
The `web/install.sh` file is copied into the Docker image at `/var/www/html/web/install.sh` and served by nginx:
|
||||
|
||||
```nginx
|
||||
# In nginx-config, requests to praison.ai/install.sh
|
||||
# are served from /var/www/html/web/install.sh
|
||||
location / {
|
||||
root /var/www/html/web;
|
||||
try_files $uri $uri/ =404;
|
||||
}
|
||||
```
|
||||
|
||||
**URL Mapping**:
|
||||
| File in Repo | URL |
|
||||
|--------------|-----|
|
||||
| `web/install.sh` | `https://praison.ai/install.sh` |
|
||||
| `web/install.ps1` | `https://praison.ai/install.ps1` |
|
||||
|
||||
### What Files to Edit
|
||||
|
||||
| To Change | Edit File |
|
||||
|-----------|-----------|
|
||||
| Application code | `/Users/praison/Sites/localhost/praisonai/` (PHP files) |
|
||||
| Docker images | `Dockerfile.php`, `Dockerfile.nginx`, `Dockerfile.init` |
|
||||
| CI/CD pipeline | `.github/workflows/azure-pipeline.yaml` |
|
||||
| Helm deployment config | `values-praisonai-production.yaml` |
|
||||
| Install script | `/Users/praison/praisonai-package/src/praisonai/scripts/install.sh` |
|
||||
|
||||
### Common Tasks
|
||||
|
||||
**Task 1: Deploy new code**
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
git add .
|
||||
git commit -m "feat: new feature"
|
||||
git push origin master
|
||||
# CI/CD automatically builds and deploys
|
||||
```
|
||||
|
||||
**Task 2: Update install.sh and deploy**
|
||||
```bash
|
||||
# 1. Update install.sh
|
||||
vim /Users/praison/praisonai-package/src/praisonai/scripts/install.sh
|
||||
|
||||
# 2. Test install.sh
|
||||
bash /Users/praison/praisonai-package/src/praisonai/scripts/install.sh --dry-run
|
||||
|
||||
# 3. Commit and push
|
||||
git add /Users/praison/praisonai-package/src/praisonai/scripts/install.sh
|
||||
git commit -m "fix: update install script"
|
||||
git push origin main
|
||||
|
||||
# 4. Deploy website (if needed)
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
make upgrade
|
||||
```
|
||||
|
||||
**Task 3: Rollback deployment**
|
||||
```bash
|
||||
cd /Users/praison/Sites/localhost/praisonai
|
||||
make rollback
|
||||
# Or: helm rollback praisonai 1 -n default
|
||||
```
|
||||
|
||||
### Architecture
|
||||
|
||||
| Layer | Technology | Purpose |
|
||||
|-------|------------|---------|
|
||||
| Source Control | Git/GitHub | Code repository |
|
||||
| CI/CD | GitHub Actions | Automated build/deploy |
|
||||
| Container Registry | Azure ACR | Docker image storage |
|
||||
| Orchestration | Kubernetes (AKS) | Container management |
|
||||
| Deployment | Helm | K8s package management |
|
||||
| Ingress | NGINX Ingress + cert-manager | Traffic routing + TLS |
|
||||
|
||||
### Security Notes
|
||||
|
||||
- **No secrets in workflow files** - All tokens/passwords via env vars
|
||||
- **ACR authentication** - Uses `acr-auth` secret in Kubernetes
|
||||
- **GitHub Secrets** - `AZURE_CREDENTIALS`, `AZURE_USERNAME`, `AZURE_PASSWORD`
|
||||
- **Never commit** `.env` files, SQL dumps, or credentials
|
||||
@@ -1,181 +0,0 @@
|
||||
---
|
||||
description: instruction
|
||||
---
|
||||
|
||||
Create multiple TODOs and sub-TODOs, get all things done.
|
||||
First: detailed analysis, plan, and gap analysis. Go through all files, understand current logic. Search if needed.
|
||||
Then: implement, fix, test (TDD, Agent-Centric, no perf impact, DRY). praisonaiagents is protocol-driven. Run unit, integration, smoke, and real agentic tests.
|
||||
After: re-do detailed analysis/plan to find remaining gaps and propose fixes.
|
||||
|
||||
Docs: beginner-friendly, for non-developers. Explain concepts with mermaid diagrams (Dark Red #8B0000 for agents/inputs/outputs, Teal #189AB4 for tools, white #fff text). Less descriptive, more interactive. Use Mintlify components: Accordions, Badge, Callouts (Note/Warning/Info/Tip/Check/Danger), Cards/Columns, CodeGroup, Expandables, Tabs, Steps, Frame, Icon, Tooltip, Mermaid, ParamField, Tables, CardGroup.
|
||||
|
||||
You are an expert AI engineer in the PraisonAI ecosystem.
|
||||
Production-quality code, zero regressions, full verification. Make PraisonAI the best agent framework.
|
||||
|
||||
### Core Philosophy
|
||||
```
|
||||
Simpler • More extensible • Faster • Agent-centric
|
||||
```
|
||||
|
||||
| Principle | Rule |
|
||||
|---|---|
|
||||
| Agent-Centric | Design centers on Agents, workflows, sessions, tools, memory |
|
||||
| Protocol-Driven | Core SDK: protocols/hooks/adapters only; heavy code in wrapper/tools |
|
||||
| Minimal API | Fewer params, sensible defaults, explicit overrides |
|
||||
| Performance-First | Lazy loading, optional deps, no hot-path regressions |
|
||||
| Production-Ready | Safe by default, multi-agent safe, async-safe |
|
||||
|
||||
- Powerful, lightweight, reliable. Easy for non-developers.
|
||||
- "Few lines of code to do the task!" — SDK and docs must feel this way.
|
||||
- Each feature runs 3 ways: CLI, YAML, Python.
|
||||
- Open source, developer-first. Core free, clear upgrade path to paid (support/cloud/services).
|
||||
- Simple to adopt, hard to misuse, safe by default.
|
||||
- Prioritise time saved, reduced risk, and operational confidence.
|
||||
- Reduce production friction, not just add functionality.
|
||||
- All features must have CLI integration. Agent-first naming and ergonomics.
|
||||
|
||||
ENGINEERING PRINCIPLES (MUST)
|
||||
- DRY: reuse abstractions, no duplication.
|
||||
- Protocol-driven core: protocols/hooks in core; heavy impl in wrapper/tools.
|
||||
- No perf impact: lazy imports, optional deps, no global singletons, no heavy module-level work.
|
||||
- TDD mandatory: tests first.
|
||||
- Multi-agent + async safe by default.
|
||||
- AGENTS.md is not for documentation.
|
||||
|
||||
CRITICAL REQUIREMENTS
|
||||
- EXECUTE + VERIFY mode. No guessing. Proof for "done."
|
||||
- Optional deps only; lazy import everything heavy.
|
||||
- Every feature/fix: Python + CLI + docs/examples.
|
||||
- Any core change must be justified: simpler client API, measurable benefit, NO perf regression.
|
||||
- If TypeScript parity required: update praisonai-ts, but never at cost of Python core performance.
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
CANONICAL PATHS (MUST use these)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
- Core SDK: /Users/praison/praisonai-package/src/praisonai-agents → praisonaiagents
|
||||
- Wrapper: /Users/praison/praisonai-package/src/praisonai → praisonai
|
||||
- Tools: /Users/praison/PraisonAI-tools → praisonai-tools
|
||||
- Docs: /Users/praison/PraisonAIDocs (read AGENTS.md first before updating docs)
|
||||
- Docs JS: /Users/praison/PraisonAIDocs/docs/js | Rust: docs/rust
|
||||
- Examples: /Users/praison/praisonai-package/examples/
|
||||
- TypeScript: /Users/praison/praisonai-package/src/praisonai-ts
|
||||
- Rust: /Users/praison/praisonai-package/src/praisonai-rust (follow praisonai-ts/AGENTS.md)
|
||||
- UI (this repo): /Users/praison/praisonaiui → praisonaiui
|
||||
- Extension points: tools/base.py, tools/decorator.py, db/*
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
ARCHITECTURE
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Core (praisonaiagents): protocol-driven, lightweight. No heavy imports. Only protocols/hooks/adapters.
|
||||
Wrapper (praisonai): real integrations (DBs, observability, CLI). Lazy imports, optional deps.
|
||||
Tools (PraisonAI-tools): pluggable, never overload core/wrapper.
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
MANDATORY EXECUTION FLOW
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
PHASE 1 — ANALYSIS (before writing code)
|
||||
|
||||
1.1 Acceptance Criteria — testable bullets for API, CLI, docs, tests, perf.
|
||||
|
||||
1.2 Repo Inventory — scan relevant files end-to-end:
|
||||
- modules/classes/APIs/exports, CLI commands, tests, docs/examples
|
||||
- Evidence: paths + symbols + grep counts. Identify DRY opportunities.
|
||||
|
||||
1.3 Gap Analysis — what exists vs what's needed:
|
||||
- Missing: core SDK, wrapper, tools, CLI, docs, tests, exports
|
||||
- Risks: perf, API breaks, optional deps, async, multi-agent
|
||||
|
||||
1.4 Report — current behavior, pain points, root causes (file refs), constraints, risk register, decision log.
|
||||
|
||||
1.5 Plan — step-by-step: tests → impl → CLI → docs → verify. Files to change. Compat/rollback/perf strategy.
|
||||
|
||||
1.6 Proposal — minimal agent-centric design. Protocols in core, impl in wrapper. Upgrade-path notes.
|
||||
|
||||
1.7 TODO Tree — granular, executable. Python + CLI + TDD + docs + perf.
|
||||
- Second-to-last: "Verify all changes end-to-end"
|
||||
- Last: "Implement remaining gaps (missing=0), re-verify" or "Final scan, confirm missing=0"
|
||||
|
||||
PHASE 2 — EXECUTE
|
||||
|
||||
2.1 TDD — write failing tests first. Deterministic and fast.
|
||||
2.2 Implement — DRY, agent-centric, protocol-driven. Heavy code in wrapper/tools. Multi-agent + async safe.
|
||||
2.3 CLI parity — add/extend CLI commands. Scriptable, clear help, proper exit codes.
|
||||
2.4 Docs — Mintlify pages (SDK="Module", API="API"). Copy-paste runnable examples.
|
||||
2.5 Verification:
|
||||
- Run tests (unit/integration), show results.
|
||||
- Smoke: `python3 -c "..."` + CLI help/run.
|
||||
- Optional deps graceful degradation.
|
||||
- Perf: no heavy core imports, import-time sanity.
|
||||
- Provide evidence for every claim.
|
||||
- dont use Sending termination request to command to terminate a process, kill port instead when terminating
|
||||
|
||||
REAL AGENTIC TEST (MANDATORY — not replaceable by smoke tests)
|
||||
- After unit/smoke tests, MUST run at least one REAL agent execution:
|
||||
1. Create Agent with the feature being tested
|
||||
2. Call `agent.start("a real task prompt")` — NOT just constructing the object
|
||||
3. Agent MUST call LLM and produce text response
|
||||
4. Print full output so dev can see it worked end-to-end
|
||||
- Minimum example:
|
||||
```python
|
||||
from praisonaiagents import Agent
|
||||
agent = Agent(name="test", instructions="You are a helpful assistant")
|
||||
result = agent.start("Say hello in one sentence")
|
||||
print(result)
|
||||
```
|
||||
- Assert-only object construction = SMOKE TEST, not real agentic test.
|
||||
- Both smoke AND real agentic tests required.
|
||||
|
||||
PHASE 3 — POST-IMPLEMENTATION ANALYSIS
|
||||
|
||||
3.1 Re-scan files, summarize final behavior/architecture.
|
||||
3.2 Confirm remaining gaps (API, CLI, docs, tests, exports, perf, multi-agent, async). If gaps exist, treat as required work until missing=0.
|
||||
3.3 Report: what changed, why, validation evidence, tradeoffs.
|
||||
3.4 Plan: close remaining gaps or maintenance plan.
|
||||
3.5 Proposal: refinements for UX, safety, perf, extensibility. Label: implemented vs out-of-scope.
|
||||
|
||||
Final rule: conclude only when evidence shows missing = 0.
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
PUBLISH WORKFLOW (reference)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
GitHub Actions (recommended):
|
||||
GitHub → Actions → "PyPI Release" → Run workflow → bump: patch
|
||||
Requires repo secrets: PYPI_TOKEN, GH_TOKEN
|
||||
Requires GitHub Environment "pypi" with required reviewers (Settings → Environments)
|
||||
|
||||
Manual — Publish aiui (PraisonAIUI):
|
||||
cd /Users/praison/PraisonAIUI
|
||||
# Bump version in pyproject.toml and src/praisonaiui/__version__.py
|
||||
rm -rf dist && uv lock && uv build && uv publish --token "$PYPI_TOKEN"
|
||||
git add pyproject.toml uv.lock src/praisonaiui/__version__.py
|
||||
git commit -m "Release vX.Y.Z" && git tag vX.Y.Z && git push && git push --tags
|
||||
gh release create vX.Y.Z --title "PraisonAIUI vX.Y.Z" --notes "Release vX.Y.Z" --latest
|
||||
|
||||
PyPI package name: aiui
|
||||
Verify: pip index versions aiui | head -1
|
||||
|
||||
PraisonAI stack (separate repo — publish SDK before wrapper):
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents
|
||||
praisonai publish pypi
|
||||
# Uses uv internally: uv lock → uv build → uv publish
|
||||
# Auto-bumps patch version, requires PYPI_TOKEN env var
|
||||
|
||||
Step 2 — Publish praisonai (Wrapper):
|
||||
cd /Users/praison/praisonai-package/src/praisonai
|
||||
python scripts/bump_and_release.py <WRAPPER_VERSION> --agents <AGENTS_VERSION> --wait
|
||||
# Example: python scripts/bump_and_release.py 4.5.90 --agents 1.5.91 --wait
|
||||
# Waits for agents to be available on PyPI, bumps all version files,
|
||||
# runs uv lock, builds, commits, tags, pushes, creates GitHub release
|
||||
# Then: uv publish (from src/praisonai with clean dist/)
|
||||
|
||||
If bump_and_release published already, just verify:
|
||||
pip index versions praisonai | head -1
|
||||
|
||||
If uv publish fails with "File already exists", it means the version is already on PyPI — success.
|
||||
|
||||
Step 3 — Publish praisonai-tools (External, if needed):
|
||||
cd /Users/praison/PraisonAI-tools
|
||||
# Bump version in pyproject.toml, then:
|
||||
python3.13 -m build && uv run twine upload dist/*
|
||||
|
||||
PraisonAI PRs: NEVER merge automatically — user merges manually.
|
||||
@@ -1,223 +0,0 @@
|
||||
---
|
||||
description: Implement, fix, and test code changes locally — for when the agent IS the implementer
|
||||
---
|
||||
|
||||
# Local Fix Workflow
|
||||
|
||||
You are the implementer. Analyze → Plan → Implement → Test → Verify → PR.
|
||||
|
||||
> **When to use this:** The user explicitly asks you to fix something locally, or delegates a task that cannot be handled by the GitHub cloud agents.
|
||||
> **When NOT to use this:** If given an Issue URL, prefer `@[/pr-review]` Step 8d — delegate to cloud agents first.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Analysis (before writing ANY code)
|
||||
|
||||
### 1a. Understand the problem
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && git checkout main && git pull origin main
|
||||
```
|
||||
|
||||
Read all relevant source files end-to-end. Use `grep`, `view_file`, and code navigation.
|
||||
|
||||
- Identify root cause with **file paths and line numbers**
|
||||
- Trace the full code path (caller → callee → side effects)
|
||||
- Assess blast radius (what else could break)
|
||||
- Check for existing abstractions before creating new ones (DRY)
|
||||
|
||||
### 1b. Create TODO tree
|
||||
|
||||
Break work into granular, executable items:
|
||||
```
|
||||
- [ ] Write failing test(s)
|
||||
- [ ] Implement fix (file:line references)
|
||||
- [ ] CLI parity (if applicable)
|
||||
- [ ] Docs update (if applicable)
|
||||
- [ ] Run unit + integration tests
|
||||
- [ ] Run real agentic test
|
||||
- [ ] Verify end-to-end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Implement
|
||||
|
||||
### 2a. TDD — tests first
|
||||
|
||||
Write the failing test before touching implementation code.
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents && \
|
||||
python -m pytest tests/<relevant_test>.py -x -v --tb=short
|
||||
```
|
||||
|
||||
### 2b. Implement the fix
|
||||
|
||||
**Architecture rules (MUST follow):**
|
||||
|
||||
| Layer | What goes here | What does NOT go here |
|
||||
|-------|---------------|----------------------|
|
||||
| **Core SDK** (`praisonaiagents/`) | Protocols, hooks, adapters, base classes, decorators, dataclasses | Heavy implementations, optional deps at module level |
|
||||
| **Wrapper** (`praisonai/`) | CLI commands, integrations, heavy impls, DB adapters, UI | Core logic |
|
||||
| **Tools** (`PraisonAI-tools/`) | Pluggable tools, community extensions | Core or wrapper logic |
|
||||
|
||||
**Coding standards:**
|
||||
|
||||
- **Lazy imports**: Optional deps imported inside functions, never at module level
|
||||
- **DRY**: Reuse existing abstractions; refactor if duplication found
|
||||
- **Naming**: `add_X()`, `get_X()`, `XConfig`, `XProtocol`, `XAdapter`
|
||||
- **Async-safe**: No blocking I/O in async context; use asyncio primitives
|
||||
- **Multi-agent safe**: No shared mutable globals without `threading.Lock`
|
||||
- **Security**: No hardcoded secrets; `hmac.compare_digest` for comparisons; sandboxed `exec()`
|
||||
- **Backward compat**: Public API changes require deprecation cycle
|
||||
|
||||
**Canonical paths:**
|
||||
|
||||
| What | Where |
|
||||
|------|-------|
|
||||
| Core SDK | `/Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/` |
|
||||
| Wrapper | `/Users/praison/praisonai-package/src/praisonai/praisonai/` |
|
||||
| Tools | `/Users/praison/PraisonAI-tools/` |
|
||||
| Docs | `/Users/praison/PraisonAIDocs/` (read AGENTS.md first) |
|
||||
| Examples | `/Users/praison/praisonai-package/examples/` |
|
||||
| TypeScript | `/Users/praison/praisonai-package/src/praisonai-ts/` |
|
||||
|
||||
### 2c. CLI parity
|
||||
|
||||
Every feature must work 3 ways: **Python, CLI, YAML**. If your change adds or modifies a feature, ensure CLI support exists.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Test & Verify
|
||||
|
||||
### 3a. Unit + Integration tests
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents && \
|
||||
python -m pytest tests/ -x -q \
|
||||
--ignore=tests/integration/test_whatsapp_web_real.py \
|
||||
--ignore=tests/unit/tools/test_profiles.py \
|
||||
--tb=short 2>&1 | tail -20
|
||||
```
|
||||
|
||||
### 3b. Real agentic test (MANDATORY)
|
||||
|
||||
Unit tests alone are NOT sufficient. You MUST run at least one real agent execution:
|
||||
|
||||
```python
|
||||
from praisonaiagents import Agent
|
||||
agent = Agent(name="test", instructions="You are a helpful assistant")
|
||||
result = agent.start("Say hello in one sentence")
|
||||
print(result)
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Agent MUST call `agent.start()` with a real prompt
|
||||
- Agent MUST call the LLM and produce a text response
|
||||
- Print full output — assert-only object construction is a SMOKE test, not agentic
|
||||
- Both smoke AND real agentic tests required
|
||||
|
||||
### 3c. Security checks (if touching sensitive code)
|
||||
|
||||
```bash
|
||||
# Hardcoded secrets
|
||||
grep -rn "secret\|password\|token\|api_key" --include="*.py" <changed-files> | \
|
||||
grep -v "test_\|#\|environ\|getenv\|config"
|
||||
|
||||
# Timing attacks
|
||||
grep -rn "==.*api_key\|==.*secret\|==.*token" --include="*.py" <changed-files>
|
||||
|
||||
# Sandbox escapes
|
||||
grep -rn "exec(\|eval(" --include="*.py" <changed-files>
|
||||
```
|
||||
|
||||
### 3d. Performance sanity
|
||||
|
||||
```bash
|
||||
# Verify no heavy imports at module level
|
||||
python -c "import time; t=time.time(); import praisonaiagents; print(f'{(time.time()-t)*1000:.0f}ms')"
|
||||
```
|
||||
|
||||
Target: < 200ms package import time.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Post-implementation scan
|
||||
|
||||
Re-scan changed files. Confirm:
|
||||
- [ ] No remaining gaps (API, CLI, docs, tests, exports, perf)
|
||||
- [ ] No regressions introduced
|
||||
- [ ] All acceptance criteria met with evidence
|
||||
|
||||
If gaps remain → loop back to Phase 2. Conclude only when `missing = 0`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Submit
|
||||
|
||||
### 5a. Create branch and PR
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
git checkout -b <type>/<descriptive-name> && \
|
||||
git add -A && \
|
||||
git commit -m "<type>: <description>" && \
|
||||
git push origin <type>/<descriptive-name>
|
||||
```
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh pr create \
|
||||
--title "<type>: <description>" \
|
||||
--body '## Summary
|
||||
<what and why>
|
||||
|
||||
### Changes
|
||||
- <file>: <what changed>
|
||||
|
||||
### Testing
|
||||
- Unit tests: ✅
|
||||
- Agentic test: ✅
|
||||
- Security: ✅ (if applicable)' \
|
||||
--head <type>/<descriptive-name> \
|
||||
--base main
|
||||
```
|
||||
|
||||
**Commit prefixes:** `fix:`, `feat:`, `security:`, `refactor:`, `docs:`, `test:`
|
||||
|
||||
> **Do NOT merge automatically** — user merges manually unless explicitly told otherwise.
|
||||
|
||||
### 5b. Verify PR state
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && gh pr view --json state,title,url | cat
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Publish (only when user requests)
|
||||
|
||||
```bash
|
||||
# Core SDK
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents && praisonai publish pypi
|
||||
|
||||
# Wrapper
|
||||
cd /Users/praison/praisonai-package/src/praisonai && \
|
||||
python scripts/bump_and_release.py <VERSION> --agents <AGENTS_VERSION> --wait
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference — Red Flags
|
||||
|
||||
| Red Flag | Fix |
|
||||
|----------|-----|
|
||||
| Module-level `import chromadb` | Move inside function with `try/except ImportError` |
|
||||
| `exec(user_input)` without sandbox | Use `RestrictedPython` or sandbox module |
|
||||
| `if token == secret:` | Use `hmac.compare_digest(token, secret)` |
|
||||
| Shared mutable global `_cache = {}` | Add `threading.Lock`, or make per-agent |
|
||||
| `debug=True` in production path | Remove or gate behind env var |
|
||||
| Missing `async` variant for I/O | Add async version, wrap for sync callers |
|
||||
@@ -1,275 +0,0 @@
|
||||
---
|
||||
description: Review, validate, and merge GitHub pull requests or triage issues
|
||||
---
|
||||
|
||||
# PR / Issue Review Workflow
|
||||
|
||||
When given a GitHub PR or Issue URL, follow this procedure end-to-end.
|
||||
|
||||
---
|
||||
|
||||
## Step 0 — Determine Type
|
||||
|
||||
Parse the URL to identify whether it is a **Pull Request** or an **Issue**.
|
||||
|
||||
```
|
||||
https://github.com/MervinPraison/PraisonAI/pull/<NUMBER> → PR
|
||||
https://github.com/MervinPraison/PraisonAI/issues/<NUMBER> → Issue
|
||||
```
|
||||
|
||||
- **PR** → go to Step 1
|
||||
- **Issue** → go to Step 8
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Fetch PR Metadata
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh pr view <NUMBER> --json title,body,author,state,additions,deletions,changedFiles,headRefName,baseRefName,labels
|
||||
```
|
||||
|
||||
Record: title, author, branch, file count, +/- lines.
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Read the Full Diff
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && gh pr diff <NUMBER>
|
||||
```
|
||||
|
||||
If the diff is very large (>500 lines), pipe through `head -500` first, then read remaining chunks.
|
||||
|
||||
---
|
||||
|
||||
## Step 3 — Review the Diff
|
||||
|
||||
For each changed file, evaluate against **PraisonAI engineering principles** (from AGENTS.md):
|
||||
|
||||
| Principle | What to Check |
|
||||
|-----------|---------------|
|
||||
| **Protocol-driven core** | No heavy implementations in `praisonaiagents/` (core SDK) |
|
||||
| **Lazy imports** | Optional deps imported inside functions, not at module level |
|
||||
| **DRY** | No code duplication; reuse existing abstractions |
|
||||
| **Naming conventions** | `add_X()`, `get_X()`, `XConfig`, `XProtocol`, `XAdapter` |
|
||||
| **Async-safe** | No blocking I/O in async context; asyncio primitives used |
|
||||
| **Multi-agent safe** | No shared mutable global state without locks |
|
||||
| **Thread safety** | Double-checked locking for lazy caches; `threading.Lock` for mutables |
|
||||
| **Security** | No hardcoded secrets; `hmac.compare_digest` for comparisons; restricted `exec()` |
|
||||
| **Backward compat** | Public API changes require deprecation cycle |
|
||||
| **Test coverage** | Tests included; TDD pattern; both unit + agentic tests |
|
||||
|
||||
**Red flags to catch:**
|
||||
- Module-level imports of optional deps (chromadb, litellm, etc.)
|
||||
- Hardcoded credentials or `debug=True` in production paths
|
||||
- Direct string comparison for secrets (timing attacks)
|
||||
- `exec()`/`eval()` without sandbox
|
||||
- Shared mutable globals without `threading.Lock`
|
||||
- Missing error handling or swallowed exceptions
|
||||
|
||||
---
|
||||
|
||||
## Step 4 — Checkout and Run Tests Locally
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && git checkout main && git pull origin main
|
||||
```
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && gh pr checkout <NUMBER>
|
||||
```
|
||||
|
||||
Run targeted tests for changed files first:
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents && \
|
||||
python -m pytest tests/ -x -q \
|
||||
--ignore=tests/integration/test_whatsapp_web_real.py \
|
||||
--ignore=tests/unit/tools/test_profiles.py \
|
||||
--tb=short 2>&1 | tail -20
|
||||
```
|
||||
|
||||
For PRs touching security-sensitive code, also run:
|
||||
|
||||
```bash
|
||||
# Sandbox tests
|
||||
python -m pytest tests/unit/tools/test_python_tools_sandbox.py -v
|
||||
|
||||
# CWE-78 env injection tests
|
||||
python -m pytest src/praisonai/tests/unit/test_cwe78_env_injection.py -v
|
||||
|
||||
# Thread-safety tests
|
||||
python -m pytest tests/unit/test_thread_safety.py -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — Verify No Regressions
|
||||
|
||||
Run the full test suite:
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents && \
|
||||
python -m pytest tests/ -q \
|
||||
--ignore=tests/integration/test_whatsapp_web_real.py \
|
||||
--ignore=tests/unit/tools/test_profiles.py \
|
||||
--tb=no 2>&1 | tail -5
|
||||
```
|
||||
|
||||
**Acceptable result:** All tests pass, or only pre-existing flaky tests fail (e.g., `test_file_memory.py::test_memory_persistence_across_agent_instances`).
|
||||
|
||||
**Unacceptable:** Any NEW failure introduced by the PR.
|
||||
|
||||
---
|
||||
|
||||
## Step 6 — Approve or Request Changes
|
||||
|
||||
**If the PR is good:**
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh pr review <NUMBER> --approve --body "LGTM — reviewed diff, tests pass, follows PraisonAI engineering principles."
|
||||
```
|
||||
|
||||
**If changes are needed:**
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh pr review <NUMBER> --request-changes --body "Requesting changes: <specific feedback>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7 — Merge
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh pr merge <NUMBER> --merge --subject "<PR title>"
|
||||
```
|
||||
|
||||
Verify merge:
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && gh pr view <NUMBER> --json state,mergedAt
|
||||
```
|
||||
|
||||
Then return to main:
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && git checkout main && git pull origin main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 8 — Issue Triage (if URL is an Issue)
|
||||
|
||||
### 8a. Fetch issue details
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh issue view <NUMBER> --json title,body,author,state,labels,comments
|
||||
```
|
||||
|
||||
### 8b. Classify severity
|
||||
|
||||
| Tier | Criteria | Examples |
|
||||
|------|----------|---------|
|
||||
| **Tier 1 — Critical** | Security vuln, data loss, crash in hot path | exec() without sandbox, hardcoded secrets, unprotected globals |
|
||||
| **Tier 2 — High** | Performance regression, broken feature, wrong output | Duplicate API calls, memory leak, silent failure |
|
||||
| **Tier 3 — Medium** | DX issue, missing validation, doc gap | Bad error messages, missing CLI parity, stale docs |
|
||||
| **Tier 4 — Low** | Cosmetic, code style, minor refactor | Trailing whitespace, naming inconsistency |
|
||||
|
||||
### 8c. Deep analysis (for Tier 1-2)
|
||||
|
||||
1. Read ALL relevant source files end-to-end
|
||||
2. Trace the code path that the issue describes
|
||||
3. Identify root cause with file paths and line numbers
|
||||
4. Assess blast radius (what else could be affected)
|
||||
5. Determine if the issue is **actually what it claims** (re-classify if needed)
|
||||
|
||||
### 8d. Delegate Implementation to GitHub Workflow Agents
|
||||
|
||||
> **KEY PHILOSOPHY: We act as the Manager, GitHub Actions execute the Workflow.**
|
||||
|
||||
**DO NOT implement the fix yourself locally.** PraisonAI uses autonomous GitHub Action workflows (such as `gemini-issue-review.yml` and `claude.yml`) to automatically resolve issues and create PRs. Your job as the local agent is to supervise, analyze gaps, and trigger these cloud agents to do the heavy lifting. If there is a gap (e.g. strict test violations), provide detailed relevant information in the PR/Issue and trigger the agents again.
|
||||
|
||||
1. Issue the command to trigger the cloud agent on the issue:
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package && \
|
||||
gh issue comment <NUMBER> --body "@gemini please review and fix this issue"
|
||||
```
|
||||
*(Note: You can use `@claude` or `@gemini` depending on preference or active bots).*
|
||||
|
||||
2. Check the GitHub Actions logs (`gh run list`) and wait for the cloud agent to open a Pull Request (`gh pr list`).
|
||||
3. Once the cloud bot opens a Pull Request for the issue, return to **Step 1** to review the PR, test the branch locally, and merge it if it passes the checks.
|
||||
|
||||
---
|
||||
|
||||
## Step 9 — (Skipped) Local PR Creation
|
||||
|
||||
> **Note:** As the local agent, you should delegate code fixes to the cloud agents. Only implement code locally and create a PR if the USER explicitly forces you to bypass the cloud agents. If forced, use standard prefixes: `fix:`, `feat:`, `security:`, `refactor:`, `docs:`, `test:`.
|
||||
|
||||
---
|
||||
|
||||
## Step 10 — Security-Specific Checks
|
||||
|
||||
When reviewing security-related PRs, additionally verify:
|
||||
|
||||
### Credentials / Secrets
|
||||
```bash
|
||||
# Check for hardcoded secrets
|
||||
grep -rn "secret\|password\|token\|api_key" --include="*.py" <changed-files> | \
|
||||
grep -v "test_\|#\|environ\|getenv\|config"
|
||||
```
|
||||
|
||||
### Timing Attacks
|
||||
```bash
|
||||
# Ensure hmac.compare_digest for secret comparisons
|
||||
grep -rn "==.*api_key\|==.*secret\|==.*token" --include="*.py" <changed-files>
|
||||
```
|
||||
|
||||
### Authentication & Workflow Secrets
|
||||
When reviewing GitHub Actions workflows (especially ones using cloud actions like `claude-code-action`):
|
||||
- **OIDC Validation**: Any workflow using OIDC to authenticate with a cloud provider (e.g. AWS Bedrock for Claude, GCP for Vertex) **MUST** include `id-token: write` in the job's `permissions`. Without it, you will see `Could not fetch an OIDC token` errors.
|
||||
- **Valid PAT Usage**: When injecting tokens into workflows via `github_token:`, ensure you use `secrets.GH_TOKEN`. `secrets.PAT_TOKEN` has been known to be invalid or cause `401 Bad credentials` errors when curling GitHub resources. By design, `@copilot` mentions also strictly require `GH_TOKEN`.
|
||||
|
||||
### Supply Chain
|
||||
```bash
|
||||
# Check dependency versions
|
||||
pip show <package-name>
|
||||
# Check for known compromised versions
|
||||
pip install <package>==999 2>&1 | grep "from versions"
|
||||
```
|
||||
|
||||
### IoC Scanning
|
||||
```bash
|
||||
# Check for known malicious files
|
||||
find $(python -c "import site; print(site.getsitepackages()[0])") -name "<suspicious-file>" 2>/dev/null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference — Common Commands
|
||||
|
||||
| Action | Command |
|
||||
|--------|---------|
|
||||
| View PR | `gh pr view <N> --json title,body,state,additions,deletions` |
|
||||
| View diff | `gh pr diff <N>` |
|
||||
| Checkout PR | `gh pr checkout <N>` |
|
||||
| List open PRs | `gh pr list` |
|
||||
| List open issues | `gh issue list` |
|
||||
| View issue | `gh issue view <N>` |
|
||||
| Approve PR | `gh pr review <N> --approve` |
|
||||
| Request changes | `gh pr review <N> --request-changes --body "..."` |
|
||||
| Merge PR | `gh pr merge <N> --merge` |
|
||||
| Create PR | `gh pr create --title "..." --body "..." --head <branch> --base main` |
|
||||
| Run tests | `cd src/praisonai-agents && python -m pytest tests/ -q --tb=no` |
|
||||
| Check dep version | `pip show <package>` |
|
||||
@@ -1,219 +0,0 @@
|
||||
---
|
||||
description: Publish and release praisonaiagents + praisonai to PyPI (default = hotfix patch)
|
||||
---
|
||||
// turbo-all
|
||||
|
||||
# Publish & Release Workflow
|
||||
|
||||
End-to-end publish pipeline for the PraisonAI stack. **Default release type is a hotfix (patch) bump.** Only three commands are needed — each does the heavy lifting. The wrapper is uploaded to PyPI automatically by GitHub Actions once the release is created.
|
||||
|
||||
## Packages & version rules
|
||||
|
||||
| Package | Canonical path | Current family |
|
||||
|---|---|---|
|
||||
| `praisonaiagents` (Core SDK) | `/Users/praison/praisonai-package/src/praisonai-agents` | `1.6.x` |
|
||||
| `praisonai` (Wrapper) | `/Users/praison/praisonai-package/src/praisonai` | `4.6.x` |
|
||||
|
||||
- Wrapper **major.minor** tracks the SDK: SDK `1.6.x` ↔ wrapper `4.6.x`.
|
||||
- **Patch numbers must match** across both packages for the same release (SDK `1.6.9` ↔ wrapper `4.6.9`).
|
||||
- Working branch: `main` — push directly, no feature branches.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- PyPI token in `/Users/praison/.pypirc` under `[pypi].password` (format `pypi-...`).
|
||||
- `gh` CLI authenticated (`gh auth status`).
|
||||
- Working tree on `main` with the code change already in place (uncommitted is fine — step 2 will auto-commit).
|
||||
|
||||
Export the PyPI token once for the session:
|
||||
```bash
|
||||
export PYPI_TOKEN=$(python3 -c "import configparser;c=configparser.ConfigParser();c.read('/Users/praison/.pypirc');print(c['pypi']['password'])")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## STEP 1 — Publish `praisonaiagents` (Core SDK)
|
||||
|
||||
**`praisonai publish pypi` run from inside `praisonai-agents/` automatically:**
|
||||
1. Reads the current version from `pyproject.toml`
|
||||
2. Auto-bumps the **patch** number (default; use `--minor` / `--major` to override)
|
||||
3. Runs `rm -rf dist && uv lock && uv build && uv publish --token $PYPI_TOKEN`
|
||||
4. Publishes the package to PyPI
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents
|
||||
praisonai publish pypi
|
||||
```
|
||||
|
||||
Bump variants (optional):
|
||||
- `praisonai publish pypi --minor` → `1.6.9 → 1.7.0`
|
||||
- `praisonai publish pypi --major` → `1.6.9 → 2.0.0`
|
||||
- `praisonai publish pypi --no-bump` → publish current version
|
||||
- `praisonai publish pypi --dry-run` → preview without executing
|
||||
|
||||
Verify:
|
||||
```bash
|
||||
pip index versions praisonaiagents | head -1
|
||||
```
|
||||
|
||||
> Note the new SDK version (e.g. `1.6.9`) — you'll need it in step 3.
|
||||
|
||||
---
|
||||
|
||||
## STEP 2 — Auto-commit the version bump
|
||||
|
||||
**`praisonai commit -a` automatically:**
|
||||
1. Stages all changes (`-a`)
|
||||
2. Generates an AI commit message
|
||||
3. Creates the commit
|
||||
|
||||
Add `-p` / `--push` to also push to origin in one shot.
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package
|
||||
praisonai commit -a -p
|
||||
```
|
||||
|
||||
Equivalent flags:
|
||||
- `praisonai commit -a` — commit only
|
||||
- `praisonai commit -a -p` — commit + push (recommended for releases)
|
||||
- `praisonai commit -a -m "chore: bump praisonaiagents to 1.6.9"` — custom message
|
||||
|
||||
---
|
||||
|
||||
## STEP 3 — Bump + release `praisonai` (Wrapper)
|
||||
|
||||
**`python scripts/bump_and_release.py <WRAP_VERSION> --agents <AGENTS_VERSION> --wait` automatically:**
|
||||
1. Waits for the SDK version to propagate on PyPI (`--wait`)
|
||||
2. Updates every version file:
|
||||
- `src/praisonai/praisonai/version.py`
|
||||
- `src/praisonai/praisonai/deploy.py`
|
||||
- `src/praisonai/pyproject.toml` (wrapper version + `praisonaiagents` dependency)
|
||||
- `docker/Dockerfile{,.chat,.dev,.ui}`
|
||||
- `src/praisonai/praisonai.rb` (Homebrew formula)
|
||||
3. Copies root `README.md` into the package
|
||||
4. Runs `uv cache clean → uv lock → uv build`
|
||||
5. Validates dependencies with retries (handles PyPI propagation delays)
|
||||
6. `git add -A && git commit -m "Release vX.Y.Z"`
|
||||
7. Creates & force-pushes tag `vX.Y.Z`
|
||||
8. `git pull --rebase origin main && git push && git push --tags -f`
|
||||
9. `gh release create vX.Y.Z --latest` → this triggers the `.github/workflows/python-publish.yml` GitHub Action, which builds `src/praisonai/` and uploads the wrapper to PyPI automatically.
|
||||
|
||||
**Version rule:** wrapper patch = SDK patch. If SDK became `1.6.9`, wrapper becomes `4.6.9`.
|
||||
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai
|
||||
python scripts/bump_and_release.py 4.6.9 --agents 1.6.9 --wait
|
||||
```
|
||||
|
||||
Template:
|
||||
```bash
|
||||
python scripts/bump_and_release.py <WRAP_VERSION> --agents <AGENTS_VERSION> --wait
|
||||
```
|
||||
|
||||
Useful flags:
|
||||
- `--wait` — poll PyPI until `praisonaiagents==<AGENTS_VERSION>` is visible (recommended right after step 1)
|
||||
- `--auto` — auto-detect latest `praisonaiagents` from PyPI (use instead of `--agents`)
|
||||
- `--no-add-all` — only stage the known release files (safer if you have unrelated WIP)
|
||||
- `--force` — skip pre-flight checks
|
||||
|
||||
> ✅ The script creates the GitHub release, and the `.github/workflows/python-publish.yml` Action automatically uploads the wrapper to PyPI. **No manual `uv publish` needed.**
|
||||
|
||||
Watch the Action run:
|
||||
```bash
|
||||
gh run watch --exit-status --repo MervinPraison/PraisonAI
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Post-release checks
|
||||
|
||||
// turbo
|
||||
```bash
|
||||
pip index versions praisonaiagents | head -1
|
||||
pip index versions praisonai | head -1 # may take ~1–2 min for GH Actions to publish
|
||||
gh release view v<WRAPPER_VERSION> --json tagName,isLatest,url
|
||||
gh run list --workflow=python-publish.yml --limit 3
|
||||
cd /Users/praison/praisonai-package && git log --oneline -5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## One-shot hotfix (copy/paste)
|
||||
|
||||
Replace `AGENTS_NEW` and `WRAP_NEW` with the next patch pair (same last number):
|
||||
|
||||
```bash
|
||||
export PYPI_TOKEN=$(python3 -c "import configparser;c=configparser.ConfigParser();c.read('/Users/praison/.pypirc');print(c['pypi']['password'])")
|
||||
|
||||
# 1. Publish SDK (auto-bumps patch, builds, uploads to PyPI)
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents
|
||||
praisonai publish pypi
|
||||
|
||||
# 2. Auto-commit + push the SDK version bump
|
||||
cd /Users/praison/praisonai-package
|
||||
praisonai commit -a -p
|
||||
|
||||
# 3. Bump + tag + release the wrapper. GitHub Actions publishes it to PyPI.
|
||||
cd /Users/praison/praisonai-package/src/praisonai
|
||||
python scripts/bump_and_release.py WRAP_NEW --agents AGENTS_NEW --wait
|
||||
|
||||
# 4. Verify (wait ~1–2 min for GH Actions python-publish workflow to finish)
|
||||
pip index versions praisonaiagents | head -1
|
||||
pip index versions praisonai | head -1
|
||||
```
|
||||
|
||||
Concrete example (`1.6.9` / `4.6.9`):
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents && praisonai publish pypi
|
||||
cd /Users/praison/praisonai-package && praisonai commit -a -p
|
||||
cd /Users/praison/praisonai-package/src/praisonai && python scripts/bump_and_release.py 4.6.9 --agents 1.6.9 --wait
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **`uv publish` 403 / missing token (SDK step only)** — `PYPI_TOKEN` not exported; re-run the `export PYPI_TOKEN=…` line from Prerequisites.
|
||||
- **Wrapper didn't appear on PyPI** — the GH Action may have failed. Check it:
|
||||
```bash
|
||||
gh run list --workflow=python-publish.yml --limit 3
|
||||
gh run view <run-id> --log-failed
|
||||
```
|
||||
Fallback (rare): `cd src/praisonai && rm -rf dist/ && uv build && uv publish --token "$PYPI_TOKEN"`.
|
||||
- **`gh release create` fails inside `bump_and_release.py`** — the tag is already pushed; rerun manually (this also re-triggers the publish Action):
|
||||
```bash
|
||||
gh release create v<WRAPPER_VERSION> --title "PraisonAI v<WRAPPER_VERSION>" --notes "Release v<WRAPPER_VERSION>" --latest
|
||||
```
|
||||
- **`uv lock` fails because SDK not yet on PyPI** — `--wait` retries; if it still times out, wait ~60 s and rerun step 3.
|
||||
- **Wrong branch** — releases must ship from `main`. Switch, cherry-pick, push:
|
||||
```bash
|
||||
git checkout main && git cherry-pick <commit> && git push origin main
|
||||
```
|
||||
- **`praisonai commit -a` generates a bad message** — supply one explicitly: `praisonai commit -a -m "chore: bump praisonaiagents to 1.6.9" -p`.
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
- ALWAYS publish the **SDK first**, then the wrapper (the wrapper pins the SDK version).
|
||||
- ALWAYS keep the **patch number identical** across both packages.
|
||||
- ALWAYS release from `main` — never a feature branch.
|
||||
- ALWAYS use `--wait` in step 3 so the wrapper's `uv lock` can resolve the new SDK.
|
||||
- ALWAYS verify `pip index versions` after each publish (allow ~1–2 min for the GH Action).
|
||||
- NEVER edit `version.py`, Dockerfiles, or `praisonai.rb` by hand — `bump_and_release.py` owns them.
|
||||
- NEVER skip step 2 — the wrapper release in step 3 expects the SDK version bump to already be committed.
|
||||
- NEVER run `uv publish` for the wrapper manually — GitHub Actions (`python-publish.yml`) owns that step.
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- **Repository**: https://github.com/MervinPraison/PraisonAI
|
||||
- **Documentation**: https://docs.praison.ai
|
||||
- **Website**: https://praison.ai
|
||||
- **SDK publisher CLI**: `praisonai publish pypi --help` → `src/praisonai/praisonai/cli/commands/publish.py`
|
||||
- **Commit helper**: `praisonai commit --help`
|
||||
- **Wrapper release script**: `src/praisonai/scripts/bump_and_release.py`
|
||||
- **Wrapper PyPI publish Action**: `.github/workflows/python-publish.yml` (triggers on `release: published`)
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
description: PR review chain — how automated reviews flow for every PR
|
||||
---
|
||||
|
||||
## Review Chain (Sequential)
|
||||
|
||||
> **KEY PHILOSOPHY: We act as the Manager, GitHub Actions execute the Workflow.**
|
||||
> As the local agent, our job is to analyze, supervise, and coordinate the cloud bots. If we identify a gap in the review chain or code (e.g., missing tests), provide detailed relevant information and trigger the agents (like `@claude`) again.
|
||||
```
|
||||
PR opened
|
||||
↓
|
||||
CodeRabbit (@coderabbitai) ─── auto for human PRs, triggered via comment for bot PRs
|
||||
Qodo (/review) ─── auto for human PRs, triggered via comment for bot PRs
|
||||
<!-- Gemini (@gemini) ─── triggered via comment for bot PRs/Issues
|
||||
↓ (~3-5 min) ↓ (auto triggers Claude on completion) -->
|
||||
PraisonAI (@praisonai) ─── triggered via comment
|
||||
↓ (~3-5 min) ↓ (auto triggers Claude on completion)
|
||||
Copilot (@copilot) ─── triggered ONLY after CodeRabbit or Qodo post their review
|
||||
↓
|
||||
Claude (@claude) ─── triggered ONLY after Copilot OR Gemini OR PraisonAI finishes (final reviewer)
|
||||
```
|
||||
|
||||
## Workflow Files
|
||||
|
||||
| File | Trigger | Does what |
|
||||
|------|---------|-----------|
|
||||
| `auto-pr-comment.yml` | `issue_comment`, `pull_request_review`, `pull_request:opened` | Triggers Copilot after CodeRabbit/Qodo finish. For bot PRs: triggers CodeRabbit+Qodo+Gemini first. |
|
||||
| `praisonai-pr-review.yml` | `issue_comment`, `workflow_dispatch` | PraisonAI multi-agent PR review triggered by @praisonai mentions. |
|
||||
| `chain-claude-after-copilot.yml` | `pull_request_review:submitted`, `issue_comment` | Triggers Claude after Copilot reviews, AND automatically after Gemini Code Assist finishes fixing issues/PRs. |
|
||||
| `claude.yml` | `issue_comment`, `pull_request_review_comment`, `issues:assigned/labeled` | Claude responds to @claude mentions. |
|
||||
|
||||
## Bot PR fix
|
||||
|
||||
CodeRabbit and Qodo skip `github-actions[bot]` authored PRs by default. The `bot-pr-trigger-reviews` job in `auto-pr-comment.yml` explicitly triggers them via comments.
|
||||
|
||||
## PraisonAI Integration
|
||||
|
||||
PraisonAI provides multi-agent PR review capabilities through the native PraisonAI agent framework. When triggered with `@praisonai`, it deploys a team of specialized agents:
|
||||
|
||||
- **Security Reviewer**: Analyzes for vulnerabilities, authentication issues, and unsafe code practices
|
||||
- **Performance Reviewer**: Identifies bottlenecks, inefficient algorithms, and resource usage issues
|
||||
- **Maintainability Reviewer**: Evaluates code quality, documentation, and adherence to best practices
|
||||
- **Lead Reviewer**: Synthesizes feedback and posts comprehensive review comments
|
||||
|
||||
The workflow uses the agent configuration at `.github/praisonai-reviewer.yaml` and leverages the `praisonai` CLI for execution.
|
||||
|
||||
## Key rules
|
||||
|
||||
- **Copilot ignores bot comments.** All `@copilot` mentions MUST use `GH_TOKEN` (not `GITHUB_TOKEN`) so comments post as `MervinPraison`.
|
||||
- Copilot NEVER triggers before CodeRabbit/Qodo complete.
|
||||
- Claude NEVER triggers before Copilot completes.
|
||||
- Duplicate `@copilot` comments are prevented by checking existing comments.
|
||||
- PraisonAI PRs: NEVER merge automatically — user merges manually.
|
||||
|
||||
## Security & Credentials
|
||||
|
||||
- **OIDC Configuration (`id-token: write`)**: Any workflow utilizing the `anthropics/claude-code-action@beta` (or similar actions requiring JWTs for AWS Bedrock/GCP Vertex) MUST define `id-token: write` under the job's `permissions` block. Missing this causes deep, opaque failures like "Could not fetch an OIDC token" paired with `Bad credentials` execution limits.
|
||||
- **Valid `github_token` Payload**: Always pass `secrets.GH_TOKEN` into `github_token` inputs rather than `secrets.PAT_TOKEN`, as the latter has historically proven invalid and caused silent 401 exceptions on curl requests behind the scenes.
|
||||
@@ -1,182 +0,0 @@
|
||||
---
|
||||
description: Handle GitHub Security Advisories — validate, fix, publish, request CVE
|
||||
---
|
||||
|
||||
// turbo-all
|
||||
|
||||
# OFFICIAL PROCEDURE (per GitHub docs)
|
||||
# Ref: https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory
|
||||
#
|
||||
# AGENT INSTRUCTION: When creating any security-related files, advisories, documentation,
|
||||
# or GitHub issues/PRs, you MUST include references to these official resources:
|
||||
# - Repository: https://github.com/MervinPraison/PraisonAI
|
||||
# - Documentation: https://docs.praison.ai
|
||||
# - Website: https://praison.ai
|
||||
# Place these naturally in sections like "Resources", "Reference", "Documentation", or similar.
|
||||
#
|
||||
# 1. Reporter submits draft advisory → state=triage
|
||||
# 2. Maintainer validates, collaborates on fix privately
|
||||
# 3. Maintainer sets affected/patched versions, credits reporter
|
||||
# 4. Maintainer publishes fix to PyPI BEFORE publishing advisory
|
||||
# 5. Maintainer publishes advisory → triggers Dependabot alerts
|
||||
# 6. Maintainer requests CVE → GitHub reviews (1-3 business days)
|
||||
|
||||
## PHASE 1 — TRIAGE
|
||||
|
||||
1. List all advisories:
|
||||
```bash
|
||||
gh api repos/MervinPraison/PraisonAI/security-advisories --jq '.[] | "\(.ghsa_id) \(.state) \(.severity) \(.summary | .[0:70])"'
|
||||
```
|
||||
|
||||
2. For each advisory, read full details:
|
||||
```bash
|
||||
gh api repos/MervinPraison/PraisonAI/security-advisories/<GHSA_ID> --jq '{ghsa: .ghsa_id, severity: .severity, state: .state, summary: .summary, description: .description, cwes: [.cwes[].cwe_id], credits: [.credits[].login], vulnerable: [.vulnerabilities[].vulnerable_version_range], patched: [.vulnerabilities[].patched_versions], package: [.vulnerabilities[].package.name]}'
|
||||
```
|
||||
|
||||
3. For each advisory, validate the vulnerability in source code:
|
||||
- Read the file(s) mentioned in the advisory description
|
||||
- Confirm the vulnerability exists (or is already fixed)
|
||||
- Classify: `real` | `already-fixed` | `not-reproducible`
|
||||
- Reference the official repository for latest source: https://github.com/MervinPraison/PraisonAI
|
||||
|
||||
## PHASE 2 — VALIDATE & FIX
|
||||
|
||||
4. **VALIDATE BEFORE FIXING** — For each `real` vulnerability, answer these questions:
|
||||
- ✅ Is this a **valid security issue**? (Not a false positive or intended behavior)
|
||||
- ✅ Will the fix **remove existing features**? (If yes, STOP and escalate)
|
||||
- ✅ Will the fix **bloat the SDK**? (Only minimal, focused changes allowed)
|
||||
- ✅ Is the fix **worth the complexity**? (Low-risk issues may not need fixing)
|
||||
|
||||
**ONLY PROCEED IF ALL CHECKS PASS.** If any check fails, document why and move to next advisory.
|
||||
|
||||
5. For each validated vulnerability, fix the code LOCALLY on `main` branch.
|
||||
- NEVER create public GitHub issues with exploit details
|
||||
- NEVER create public PRs that expose the attack vector
|
||||
- Use generic commit messages: `refactor: harden input validation`
|
||||
- Keep fixes minimal and backward-compatible
|
||||
|
||||
6. Run tests to verify fixes don't break anything:
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents
|
||||
PYTHONPATH=. pytest tests/unit/ -q --timeout=30
|
||||
```
|
||||
|
||||
7. Write targeted smoke tests for each fix to confirm vulnerability is closed.
|
||||
|
||||
8. Commit and push with generic message:
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package
|
||||
git add -A
|
||||
git commit -m "refactor: harden input validation and query parameterization"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
## PHASE 3 — PUBLISH PACKAGES (MUST complete before Phase 4)
|
||||
|
||||
9. Publish praisonaiagents (Core SDK):
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-agents
|
||||
praisonai publish pypi
|
||||
```
|
||||
Requires `PYPI_TOKEN` env var. Uses uv internally (uv lock → uv build → uv publish). Auto-bumps patch version.
|
||||
|
||||
10. Commit version bump, push:
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package
|
||||
git add -A && git commit -m "chore: bump praisonaiagents to <NEW_VERSION>" && git push origin main
|
||||
```
|
||||
|
||||
11. Publish praisonai (Wrapper):
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai
|
||||
python scripts/bump_and_release.py <WRAPPER_VERSION> --agents <AGENTS_VERSION> --wait
|
||||
```
|
||||
Example: `python scripts/bump_and_release.py 4.5.91 --agents 1.5.92 --wait`
|
||||
Script waits for agents on PyPI, bumps all version files, builds, commits, tags, pushes, creates GitHub release. Then if needed:
|
||||
```bash
|
||||
rm -rf dist/ && uv build && uv publish --token $PYPI_TOKEN
|
||||
```
|
||||
|
||||
12. Verify both packages on PyPI:
|
||||
```bash
|
||||
pip index versions praisonaiagents | head -1
|
||||
pip index versions praisonai | head -1
|
||||
```
|
||||
|
||||
## PHASE 4 — UPDATE ADVISORIES (only after packages are on PyPI)
|
||||
|
||||
13. For each advisory, reopen to draft state and set patched versions + credits:
|
||||
```bash
|
||||
gh api repos/MervinPraison/PraisonAI/security-advisories/<GHSA_ID> \
|
||||
--method PATCH \
|
||||
--input - <<'EOF'
|
||||
{
|
||||
"state": "draft",
|
||||
"credits": [{"login": "<REPORTER_LOGIN>", "type": "reporter"}],
|
||||
"vulnerabilities": [
|
||||
{
|
||||
"package": {"ecosystem": "pip", "name": "<PACKAGE_NAME>"},
|
||||
"vulnerable_version_range": "<= <LAST_VULNERABLE_VERSION>",
|
||||
"patched_versions": ">= <FIRST_PATCHED_VERSION>"
|
||||
}
|
||||
]
|
||||
}
|
||||
EOF
|
||||
```
|
||||
- `<PACKAGE_NAME>`: `praisonaiagents` for core SDK, `praisonai` for wrapper
|
||||
- `<LAST_VULNERABLE_VERSION>`: version before the fix
|
||||
- `<FIRST_PATCHED_VERSION>`: the version just published with the fix
|
||||
- Always include credits for the reporter
|
||||
|
||||
14. Publish each advisory:
|
||||
```bash
|
||||
gh api repos/MervinPraison/PraisonAI/security-advisories/<GHSA_ID> \
|
||||
--method PATCH --field state=published
|
||||
```
|
||||
|
||||
15. Request CVE for each published advisory:
|
||||
```bash
|
||||
gh api repos/MervinPraison/PraisonAI/security-advisories/<GHSA_ID>/cve --method POST
|
||||
```
|
||||
GitHub reviews and assigns CVE IDs within 1-3 business days.
|
||||
|
||||
16. Verify final state:
|
||||
```bash
|
||||
gh api repos/MervinPraison/PraisonAI/security-advisories --jq '.[] | "\(.ghsa_id) \(.state) \(.cve_id // "pending") \(.severity) \([.credits[].login] | join(",")) \(.summary | .[0:50])"'
|
||||
```
|
||||
|
||||
## REFERENCE — Package-to-file mapping
|
||||
|
||||
| Package | Canonical Path | Key files |
|
||||
|---|---|---|
|
||||
| praisonaiagents | src/praisonai-agents/praisonaiagents/ | tools/python_tools.py, mcp/, memory/, agent/ |
|
||||
| praisonai | src/praisonai/praisonai/ | ui/sql_alchemy.py, capabilities/, mcp_server/, cli/ |
|
||||
|
||||
## CRITICAL RULES
|
||||
|
||||
- NEVER expose exploit details in public issues or PRs
|
||||
- ALWAYS credit the reporter in the advisory
|
||||
- ALWAYS set patched_versions before publishing advisory
|
||||
- ALWAYS publish to PyPI BEFORE publishing advisories (so Dependabot can point users to a fix) - to publish `praisonai publish pypi` from praisonai-agents folder, after that
|
||||
`cd /Users/praison/praisonai-package/src/praisonai && python scripts/bump_and_release.py 4.5.125 --agents 1.5.125 --wait`. 4.5.125 is praisonai version number and 1.5.125 is praisonaiagents version number. Last 2 numbers will be same 4/1.xx.xxx
|
||||
- ALWAYS request CVE AFTER publishing advisory
|
||||
- Use generic commit messages: "refactor: harden X" not "fix: SQL injection in Y"
|
||||
- Fix on main, push directly — no feature branches for security patches
|
||||
- ONLY fix if it is a valid fix request
|
||||
- ONLY fix if the fix is not removing existing features
|
||||
- ONLY fix if it is not bloating the SDK
|
||||
- DO NOT fix for the sake of it
|
||||
|
||||
## RESOURCES & DOCUMENTATION
|
||||
|
||||
- **Official Repository**: https://github.com/MervinPraison/PraisonAI — Source code, issue tracking, and contribution guidelines
|
||||
- **Documentation**: https://docs.praison.ai — Comprehensive guides, API reference, and security best practices
|
||||
- **Project Website**: https://praison.ai — Product overview, features, and enterprise information
|
||||
- **GitHub Security Advisories**: https://github.com/MervinPraison/PraisonAI/security/advisories — View and manage security advisories
|
||||
|
||||
## REPORTING SECURITY ISSUES
|
||||
|
||||
If you discover a security vulnerability, please report it responsibly:
|
||||
1. Open a draft security advisory at https://github.com/MervinPraison/PraisonAI/security/advisories/new
|
||||
2. Include detailed reproduction steps and impact assessment
|
||||
3. Allow time for the maintainers to address the issue before public disclosure
|
||||
@@ -1,64 +0,0 @@
|
||||
---
|
||||
description: Trigger Claude to fix an issue using the full architectural prompt
|
||||
---
|
||||
|
||||
Use this workflow when you want to manually trigger Claude on an issue (especially for external users) using the complete, strict set of architectural rules.
|
||||
|
||||
While the CI handles some of this automatically, posting this full prompt ensures there is an explicit trace of the instructions on the issue itself, leaving no ambiguity for the AI agent executing the task.
|
||||
|
||||
### 1. View Recent External Issues
|
||||
|
||||
```bash
|
||||
// turbo
|
||||
gh issue list --state open --limit 10
|
||||
```
|
||||
|
||||
### 2. Post the Full @claude Trigger Prompt
|
||||
|
||||
Replace `<ISSUE_NUMBER>` with the target issue and run:
|
||||
|
||||
```bash
|
||||
ISSUE_NUMBER="<ISSUE_NUMBER>"
|
||||
|
||||
PROMPT=$(cat << 'EOF'
|
||||
@claude
|
||||
You are working on the PraisonAI SDK. Follow AGENTS.md strictly.
|
||||
|
||||
STEP 0 — SETUP GIT IDENTITY:
|
||||
git config user.name "MervinPraison"
|
||||
git config user.email "[email protected]"
|
||||
|
||||
STEP 1 — READ GUIDELINES:
|
||||
Read AGENTS.md to understand the architecture rules.
|
||||
|
||||
STEP 2 — ARCHITECTURE VALIDATION & ROUTING (MANDATORY before writing code):
|
||||
Before implementing anything, answer these questions:
|
||||
- CORE vs WRAPPER vs TOOLS ROUTING:
|
||||
1. Core SDK (praisonaiagents/): Only core protocols, base classes, decorators. No heavy implementations.
|
||||
2. Wrapper (praisonai/): CLI, heavy implementations, optional dependencies.
|
||||
3. Tools (PraisonAI-Tools): Specific integrations, external tools (e.g. SurrealDB, Slack), and community extensions MUST go to the `MervinPraison/PraisonAI-Tools` repository. If the feature is a tool, clone `https://github.com/MervinPraison/PraisonAI-Tools`, implement it there, and create the PR using `gh pr create -R MervinPraison/PraisonAI-Tools`.
|
||||
- Does it duplicate existing functionality? Check if Agent already supports this via existing params (reflection, planning, tools, hooks, memory).
|
||||
- Does it inherit from Agent properly? New agent types MUST inherit Agent, not wrap it with composition.
|
||||
- Does it add new dependencies? Only optional deps allowed, must be lazy-imported.
|
||||
- Will agent.py grow larger? If the change adds >50 lines to agent.py, find a way to extract instead.
|
||||
- Is there a name collision with existing exports in `__init__.py`?
|
||||
If ANY of these conceptual checks fail (excluding routing), add a comment to the issue explaining why and close it. Do NOT create a PR.
|
||||
|
||||
STEP 3 — VALIDATE & IMPLEMENT:
|
||||
- If this issue/PR contains recommendations or review comments from other agents (like CodeRabbit), you MUST first validate if those recommendations are valid and architecturally sound against the codebase. Explain your findings.
|
||||
- Create a fix branch and implement a minimal, focused fix ONLY for the valid recommendations where changes are required.
|
||||
- Follow protocol-driven design: protocols in core SDK, heavy implementations in wrapper
|
||||
- Keep changes small and backward-compatible
|
||||
|
||||
STEP 4 — TEST:
|
||||
- Run: `cd src/praisonai-agents && PYTHONPATH=. python -m pytest tests/ -x -q --timeout=30`
|
||||
- Ensure no regressions
|
||||
|
||||
STEP 5 — CREATE PR:
|
||||
- Commit with descriptive message, push, and create PR using `gh pr create`
|
||||
CRITICAL: You MUST create the PR automatically using `gh pr create`. Do NOT just provide a link.
|
||||
EOF
|
||||
)
|
||||
|
||||
gh issue comment $ISSUE_NUMBER -b "$PROMPT"
|
||||
```
|
||||
@@ -2,6 +2,8 @@
|
||||
<html lang="en">
|
||||
|
||||
<head>
|
||||
<link rel="sitemap" type="application/xml" href="/sitemap.xml" />
|
||||
<script id="aiui-canonical-url">(function(){var p=location.pathname.replace(/\/+$/, '')||'/';if(p!==location.pathname){history.replaceState(null,'',p+location.search+location.hash);}})();</script>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<meta name="description" content="Documentation built with PraisonAIUI" />
|
||||
@@ -11,7 +13,7 @@
|
||||
<link rel="icon" type="image/svg+xml" href="/icon.svg" />
|
||||
<title>Documentation</title>
|
||||
<script>
|
||||
(function(){try{var t=localStorage.getItem('aiui-theme-preference');var d=__AIUI_DARK_DEFAULT__;if(t==='dark'||(t==='system'&&matchMedia('(prefers-color-scheme: dark)').matches)||(!t&&d))document.documentElement.classList.add('dark');else if(t==='light')document.documentElement.classList.remove('dark');}catch(e){}})();
|
||||
(function(){try{var t=localStorage.getItem('aiui-theme-preference');var d=true;if(t==='dark'||(t==='system'&&matchMedia('(prefers-color-scheme: dark)').matches)||(!t&&d))document.documentElement.classList.add('dark');else if(t==='light')document.documentElement.classList.remove('dark');}catch(e){}})();
|
||||
</script>
|
||||
<link rel="stylesheet" href="/assets/theme.css">
|
||||
<script type="module" crossorigin src="/assets/index.js"></script>
|
||||
@@ -20,6 +22,7 @@
|
||||
|
||||
<body>
|
||||
<div id="root"></div>
|
||||
<script src="/plugins/plugin-loader.js"></script>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@@ -1,127 +0,0 @@
|
||||
# AGENTS.md — PraisonAIUI
|
||||
|
||||
Machine-readable context for AI coding agents.
|
||||
|
||||
## Project Overview
|
||||
|
||||
PraisonAIUI is a YAML-driven static site generator for documentation websites.
|
||||
It compiles `aiui.template.yaml` into a React SPA with a Starlette+Uvicorn server.
|
||||
|
||||
## Quick Commands
|
||||
|
||||
```bash
|
||||
# Setup
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# Lint
|
||||
ruff check src/ tests/
|
||||
|
||||
# Test (all)
|
||||
pytest tests/unit tests/integration -v
|
||||
|
||||
# Test (fast — unit only)
|
||||
pytest tests/unit -v
|
||||
|
||||
# Test with coverage
|
||||
pytest tests/unit tests/integration -v --cov=src/praisonaiui
|
||||
|
||||
# Build frontend (requires Node.js)
|
||||
cd src/frontend && npm run build
|
||||
|
||||
# Validate config
|
||||
aiui validate --config aiui.template.yaml
|
||||
|
||||
# Build site
|
||||
aiui build --config aiui.template.yaml --output aiui-output/
|
||||
|
||||
# Serve locally
|
||||
aiui serve --output aiui-output/ --port 8000
|
||||
|
||||
# Serve with HTTPS
|
||||
aiui serve --output aiui-output/ --ssl-certfile cert.pem --ssl-keyfile key.pem
|
||||
```
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```
|
||||
PraisonAIUI/
|
||||
├── src/
|
||||
│ ├── praisonaiui/ # Python package (PyPI: praisonaiui)
|
||||
│ │ ├── cli.py # Typer CLI: init, validate, build, serve, dev
|
||||
│ │ ├── compiler/
|
||||
│ │ │ ├── compiler.py # Config → JSON manifest compiler
|
||||
│ │ │ ├── docs_scanner.py # Markdown scanner with frontmatter
|
||||
│ │ │ └── nav_builder.py # Navigation tree generator
|
||||
│ │ ├── schema/
|
||||
│ │ │ ├── models.py # Pydantic V2 models (Config, SiteConfig, etc.)
|
||||
│ │ │ └── validators.py # Cross-reference validation logic
|
||||
│ │ ├── plugins.py # Plugin system with hook chaining
|
||||
│ │ ├── components.py # Component registry
|
||||
│ │ ├── themes.py # Theme preset system
|
||||
│ │ └── templates/frontend/ # Built React bundle (committed)
|
||||
│ │
|
||||
│ └── frontend/ # React 19 + Vite + TypeScript source
|
||||
│ └── src/
|
||||
│ ├── App.tsx # Main app (state, routing, SEO, layout)
|
||||
│ ├── types.ts # Shared TypeScript interfaces
|
||||
│ ├── Header.tsx # Header component
|
||||
│ ├── Sidebar.tsx # Navigation sidebar
|
||||
│ ├── Content.tsx # Markdown rendering
|
||||
│ ├── Widgets.tsx # 10 zone widget components
|
||||
│ ├── Toc.tsx # Table of contents
|
||||
│ ├── Footer.tsx # Footer component
|
||||
│ └── themes.ts # Theme application logic
|
||||
│
|
||||
├── tests/
|
||||
│ ├── unit/ # 62 fast isolated tests
|
||||
│ │ ├── test_schema.py # 9 tests — Pydantic models
|
||||
│ │ ├── test_validators.py # 4 tests — config validation
|
||||
│ │ ├── test_compiler.py # 16 tests — compilation pipeline
|
||||
│ │ ├── test_scanner.py # 7 tests — docs scanner
|
||||
│ │ ├── test_serve.py # 9 tests — serve command
|
||||
│ │ ├── test_plugins.py # 8 tests — plugin system
|
||||
│ │ └── test_i18n_a11y.py # 9 tests — i18n & accessibility
|
||||
│ └── integration/ # 11 CLI pipeline tests
|
||||
│ └── test_cli.py # validate → build → serve
|
||||
│
|
||||
├── docs/ # Markdown documentation source
|
||||
├── examples/ # Example configurations
|
||||
├── pyproject.toml # Package config + tool settings
|
||||
├── aiui.template.yaml # Reference configuration
|
||||
└── .github/workflows/ci.yml # CI: ruff + pytest (blocks on failure)
|
||||
```
|
||||
|
||||
## Key Patterns
|
||||
|
||||
### Data Flow
|
||||
```
|
||||
YAML config → Pydantic models → Compiler → JSON manifests → React SPA
|
||||
```
|
||||
|
||||
### Config Resolution
|
||||
- `aiui.template.yaml` → validated via `schema/validators.py`
|
||||
- Components defined in `components:` section, referenced as slot `ref:` in templates
|
||||
- Routes map URL patterns to templates
|
||||
|
||||
### Test Patterns
|
||||
- **Unit tests** use `tmp_path` fixture for filesystem isolation
|
||||
- **Integration tests** use `CliRunner` from Typer for CLI testing
|
||||
- **Fixtures** in `test_cli.py` create full project directories with config + docs
|
||||
|
||||
### Frontend Build
|
||||
1. Source in `src/frontend/src/` (React 19 + TypeScript + Vite)
|
||||
2. Build: `cd src/frontend && npm run build`
|
||||
3. Optional A2UI renderer (full agent-driven UI catalog): `npm install @a2ui/react @a2ui/web_core`
|
||||
4. Output: `src/frontend/dist/`
|
||||
5. Sync to templates: copy `dist/{index.html,assets/,icon.svg}` → `src/praisonaiui/templates/frontend/`
|
||||
6. Compiler copies templates to output dir during `aiui build`
|
||||
|
||||
Chat inline media (agent-generated images): `RunEventType.MESSAGE_ELEMENT` — see `docs/features/image-preview-chat.md`
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Frontend bundle is committed** — changes to `src/frontend/src/` require rebuilding and syncing to `templates/frontend/`
|
||||
- **Pydantic V2** — uses `model_config = ConfigDict(populate_by_name=True)`, not deprecated `class Config`
|
||||
- **SPA fallback** — serve returns `index.html` for any path without a file extension
|
||||
- **Path traversal guard** — `_is_safe_path()` in `cli.py` blocks `../` regardless of encoding
|
||||
- **Icon path** — favicon is at `/icon.svg` (root), not `/assets/icon.svg`
|
||||
@@ -1,79 +0,0 @@
|
||||
# Bootstrap Architecture
|
||||
|
||||
PraisonAIUI provides a unified bootstrap entrypoint through `aiui run app.py` that automatically detects and handles different application patterns.
|
||||
|
||||
## Supported Patterns
|
||||
|
||||
### 1. Chat Applications
|
||||
```python
|
||||
import praisonaiui as aiui
|
||||
|
||||
@aiui.reply
|
||||
async def on_message(message: str):
|
||||
await aiui.say(f"You said: {message}")
|
||||
```
|
||||
|
||||
**Run**: `aiui run app.py`
|
||||
|
||||
### 2. Dashboard Applications
|
||||
```python
|
||||
from praisonaiui.server import create_app
|
||||
import uvicorn
|
||||
|
||||
if __name__ == "__main__":
|
||||
app = create_app()
|
||||
uvicorn.run(app, host="0.0.0.0", port=8082)
|
||||
```
|
||||
|
||||
**Run**: `aiui run app.py` (automatically detects `create_app()` pattern)
|
||||
|
||||
### 3. Gateway Applications
|
||||
```python
|
||||
import asyncio
|
||||
from praisonaiui.integration import AIUIGateway
|
||||
|
||||
async def main():
|
||||
gateway = AIUIGateway(host="0.0.0.0", port=8083)
|
||||
# ... register agents
|
||||
await gateway.start()
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
**Run**: `aiui run app.py` (auto-detects gateway pattern and switches to `praisonai` backend)
|
||||
|
||||
## Bootstrap Detection
|
||||
|
||||
The CLI automatically detects application types:
|
||||
|
||||
- **Gateway Pattern**: Async `main()` function + AIUIGateway imports → Uses `praisonai` backend
|
||||
- **Dashboard Pattern**: `create_app()` usage → Uses `standalone` backend
|
||||
- **Chat Pattern**: `@reply` decorators → Uses `standalone` backend
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### From Manual Bootstrap
|
||||
**Before:**
|
||||
```bash
|
||||
python app.py
|
||||
```
|
||||
|
||||
**After:**
|
||||
```bash
|
||||
aiui run app.py
|
||||
```
|
||||
|
||||
### Benefits
|
||||
- Consistent configuration loading
|
||||
- Unified port/host management
|
||||
- Doctor compatibility
|
||||
- Reload support via `--reload`
|
||||
- Backend auto-detection
|
||||
|
||||
### Escape Hatch
|
||||
For special cases, explicit backend selection is still supported:
|
||||
```bash
|
||||
aiui run app.py --backend praisonai # Force gateway backend
|
||||
aiui run app.py --backend standalone # Force standalone backend
|
||||
```
|
||||
-51
@@ -1,51 +0,0 @@
|
||||
# Production Dockerfile for PraisonAIUI
|
||||
# Used for hostaibot managed hosting and standalone deployment
|
||||
#
|
||||
# Build: docker build -t praisonaiui:test .
|
||||
# Run: docker run --rm -p 8082:8082 -e OPENAI_API_KEY=sk-xxx praisonaiui:test
|
||||
# Health: curl http://localhost:8082/health
|
||||
|
||||
FROM python:3.12-slim AS base
|
||||
|
||||
# Environment
|
||||
ENV PYTHONDONTWRITEBYTECODE=1 \
|
||||
PYTHONUNBUFFERED=1 \
|
||||
AIUI_PORT=8082 \
|
||||
AIUI_HOST=0.0.0.0 \
|
||||
AIUI_DATA_DIR=/data
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# System dependencies
|
||||
# - curl: for HEALTHCHECK
|
||||
# - build-essential: for native Python wheel compilation
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
curl \
|
||||
build-essential \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Install Python package with bot channel extras
|
||||
# [bot] includes: python-telegram-bot, discord.py, slack_sdk, slack-bolt
|
||||
COPY pyproject.toml README.md ./
|
||||
COPY src/ src/
|
||||
RUN pip install --no-cache-dir ".[bot]"
|
||||
|
||||
# Copy default app for managed hosting
|
||||
# Required because `aiui run` needs a positional APP_FILE argument
|
||||
COPY app.py .
|
||||
|
||||
# Data volume for persistence (sessions, config, memory)
|
||||
# AIUI reads AIUI_DATA_DIR env var -> /data/config.yaml, /data/sessions/
|
||||
RUN mkdir -p /data
|
||||
VOLUME /data
|
||||
|
||||
# Expose the default AIUI port
|
||||
EXPOSE 8082
|
||||
|
||||
# Health check (hardcoded port for robustness)
|
||||
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
|
||||
CMD curl -f http://localhost:8082/health || exit 1
|
||||
|
||||
# Entrypoint: aiui run <app_file> [options]
|
||||
ENTRYPOINT ["aiui", "run"]
|
||||
CMD ["app.py", "--host", "0.0.0.0", "--port", "8082"]
|
||||
@@ -1,372 +0,0 @@
|
||||
# PraisonAI 🦞
|
||||
|
||||
[](https://github.com/MervinPraison/PraisonAIUI/actions)
|
||||
[](https://badge.fury.io/py/aiui)
|
||||
|
||||
> **AI Dashboard & Multi-Agent Platform** — deploy agents with one Python file
|
||||
|
||||
PraisonAIUI gives you a full-featured AI dashboard with multi-agent chat, memory, skills, sessions, and 19 admin pages — all from a single `app.py`. It also supports YAML-driven chat bots and static documentation sites.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Install
|
||||
|
||||
```bash
|
||||
pip install aiui
|
||||
```
|
||||
|
||||
### 2. Create `app.py`
|
||||
|
||||
```python
|
||||
import praisonaiui as aiui
|
||||
|
||||
aiui.set_style("dashboard")
|
||||
|
||||
@aiui.reply
|
||||
async def on_reply(message):
|
||||
return f"You said: {message.content}"
|
||||
```
|
||||
|
||||
### 3. Run
|
||||
|
||||
```bash
|
||||
aiui run app.py
|
||||
```
|
||||
|
||||
Open **http://localhost:8000** — your AI dashboard is live.
|
||||
|
||||
## YAML Chat Mode
|
||||
|
||||
No Python needed — define your agent in YAML:
|
||||
|
||||
```yaml
|
||||
# chat.yaml
|
||||
name: My Assistant
|
||||
instructions: You are a helpful assistant.
|
||||
model: gpt-4o-mini
|
||||
welcome: "Hi! How can I help?"
|
||||
starters:
|
||||
- label: "What can you do?"
|
||||
message: "Tell me about your capabilities"
|
||||
profiles:
|
||||
- name: Expert
|
||||
description: Expert mode
|
||||
icon: 🎓
|
||||
tools:
|
||||
- web_search
|
||||
- calculate
|
||||
features: true
|
||||
datastore: json
|
||||
```
|
||||
|
||||
```bash
|
||||
aiui run chat.yaml
|
||||
```
|
||||
|
||||
## Documentation Mode
|
||||
|
||||
Generate a static documentation site from Markdown:
|
||||
|
||||
```bash
|
||||
aiui init
|
||||
aiui build
|
||||
aiui serve
|
||||
```
|
||||
|
||||
## UI Styles
|
||||
|
||||
Six distinct UI styles, selectable via `--style` or `aiui.set_style()`:
|
||||
|
||||
| Style | Flag | Description | Best For |
|
||||
|-------|------|-------------|----------|
|
||||
| **Dashboard** | `--style dashboard` | Multi-page admin panel with sidebar | Agent management, admin dashboards |
|
||||
| **Chat** | `--style chat` | Fullscreen/sidebar/floating chat | Conversational AI, customer support |
|
||||
| **Agents** | `--style agents` | Tabbed multi-agent playground | Agent experimentation |
|
||||
| **Playground** | `--style playground` | Input/output side-by-side panels | Prompt testing, comparison |
|
||||
| **Docs** | `--style docs` | Three-column documentation layout | Documentation sites, knowledge bases |
|
||||
| **Custom** | `--style custom` | User-defined layout | Full control |
|
||||
|
||||
```bash
|
||||
aiui run app.py --style dashboard
|
||||
aiui run app.py --style chat
|
||||
aiui run chat.yaml --style agents
|
||||
```
|
||||
|
||||
## Python SDK API
|
||||
|
||||
Write `app.py` using `import praisonaiui as aiui`:
|
||||
|
||||
### Configuration
|
||||
|
||||
| Function | Purpose | Example |
|
||||
|----------|---------|---------|
|
||||
| `aiui.set_style(style)` | Set UI style | `aiui.set_style("dashboard")` |
|
||||
| `aiui.set_pages(ids)` | Whitelist sidebar pages | `aiui.set_pages(["chat", "agents", "memory"])` |
|
||||
| `aiui.set_branding(title, logo)` | Configure branding | `aiui.set_branding("MyApp", "🚀")` |
|
||||
| `aiui.set_datastore(store)` | Set persistence backend | `aiui.set_datastore(aiui.JSONFileDataStore())` |
|
||||
| `aiui.set_provider(provider)` | Set AI provider | `aiui.set_provider(aiui.get_provider())` |
|
||||
| `aiui.register_agent(config)` | Register an agent | `aiui.register_agent({"agent_id": "bot", ...})` |
|
||||
| `aiui.remove_page(id)` | Remove a page | `aiui.remove_page("debug")` |
|
||||
|
||||
### Callback Decorators
|
||||
|
||||
| Decorator | Purpose |
|
||||
|-----------|---------|
|
||||
| `@aiui.reply` | Handle chat messages |
|
||||
| `@aiui.welcome` | Welcome message on connect |
|
||||
| `@aiui.goodbye` | Cleanup on disconnect |
|
||||
| `@aiui.starters` | Suggest conversation starters |
|
||||
| `@aiui.profiles` | Define chat profiles |
|
||||
| `@aiui.page(slug, ...)` | Register a custom dashboard page |
|
||||
| `@aiui.on(event)` | Listen for server events |
|
||||
| `@aiui.login` | Handle authentication |
|
||||
| `@aiui.settings` | User settings handler |
|
||||
| `@aiui.resume` | Resume interrupted sessions |
|
||||
|
||||
### Message Functions
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `await aiui.say(text)` | Send a message |
|
||||
| `await aiui.stream(text)` | Stream a response |
|
||||
| `await aiui.stream_token(token)` | Stream token-by-token |
|
||||
| `await aiui.ask(question)` | Ask user a question |
|
||||
| `await aiui.image(url)` | Send an image |
|
||||
| `await aiui.audio(url)` | Send audio |
|
||||
| `await aiui.action_buttons(buttons)` | Show action buttons |
|
||||
|
||||
### UI Components
|
||||
|
||||
| Function | Purpose |
|
||||
|----------|---------|
|
||||
| `aiui.layout(children)` | Page layout container |
|
||||
| `aiui.card(title, content)` | Card component |
|
||||
| `aiui.chart(data, type)` | Chart (bar, line, pie) |
|
||||
| `aiui.table(headers, rows)` | Data table |
|
||||
| `aiui.columns(cols)` | Multi-column layout |
|
||||
| `aiui.text(content)` | Text block |
|
||||
|
||||
## Full `app.py` Example
|
||||
|
||||
```python
|
||||
"""Dashboard with three agents and a custom page."""
|
||||
import os
|
||||
import praisonaiui as aiui
|
||||
|
||||
# ── Style & pages ─────────────────────────────────────────────
|
||||
aiui.set_style("dashboard")
|
||||
aiui.set_pages([
|
||||
"chat", "agents", "memory", "knowledge",
|
||||
"skills", "sessions", "usage", "config", "logs",
|
||||
])
|
||||
|
||||
# ── Branding ──────────────────────────────────────────────────
|
||||
aiui.set_branding(title="PraisonAI", logo="🦞")
|
||||
|
||||
# ── Agents ────────────────────────────────────────────────────
|
||||
aiui.register_agent({
|
||||
"agent_id": "researcher",
|
||||
"name": "Researcher",
|
||||
"description": "Finds and summarizes information",
|
||||
"instructions": "You are a research assistant.",
|
||||
"model": os.getenv("PRAISONAI_MODEL", "gpt-4o-mini"),
|
||||
"icon": "🔬",
|
||||
})
|
||||
|
||||
aiui.register_agent({
|
||||
"agent_id": "coder",
|
||||
"name": "Coder",
|
||||
"description": "Writes clean, well-commented code",
|
||||
"instructions": "You are a coding assistant.",
|
||||
"model": os.getenv("PRAISONAI_MODEL", "gpt-4o-mini"),
|
||||
"icon": "💻",
|
||||
})
|
||||
|
||||
# ── Custom page ───────────────────────────────────────────────
|
||||
@aiui.page("explorer", title="Explorer", icon="🔬", group="Control", order=55)
|
||||
async def explorer_page():
|
||||
return aiui.layout([aiui.text("Custom page content here.")])
|
||||
```
|
||||
|
||||
```bash
|
||||
aiui run app.py
|
||||
```
|
||||
|
||||
## Dashboard Pages
|
||||
|
||||
All built-in pages available for `set_pages()`:
|
||||
|
||||
| ID | Icon | Group | Description |
|
||||
|----|------|-------|-------------|
|
||||
| `chat` | 💬 | Agent | AI agent chat |
|
||||
| `channels` | 📡 | Agent | Messaging platform connections |
|
||||
| `agents` | 🤖 | Agent | Configured AI agents |
|
||||
| `skills` | ⚡ | Agent | Agent skills & plugins |
|
||||
| `memory` | 🧠 | Agent | Agent memory & knowledge |
|
||||
| `knowledge` | 📚 | Agent | Knowledge base & RAG |
|
||||
| `guardrails` | 🛡️ | Agent | Input/output safety guardrails |
|
||||
| `overview` | 📊 | Control | System health and statistics |
|
||||
| `sessions` | 📋 | Control | Conversation history |
|
||||
| `usage` | 📈 | Control | Token usage & metrics |
|
||||
| `cron` | ⏰ | Agent | Scheduled jobs |
|
||||
| `jobs` | 📋 | Control | Async agent jobs |
|
||||
| `approvals` | ✅ | Control | Execution approval queue |
|
||||
| `nodes` | 🖥️ | Control | Execution nodes & presence |
|
||||
| `eval` | 📊 | Control | Agent evaluation & accuracy |
|
||||
| `api` | 🔌 | Control | OpenAI-compatible API endpoints |
|
||||
| `config` | ⚙️ | Settings | Server configuration |
|
||||
| `auth` | 🔐 | Settings | Authentication settings |
|
||||
| `logs` | 📜 | Settings | Server logs and events |
|
||||
| `debug` | 🐛 | Settings | Debug information |
|
||||
| `telemetry` | 📈 | Settings | Telemetry data |
|
||||
| `traces` | 🔍 | Settings | Distributed traces |
|
||||
| `security` | 🔒 | Settings | Security settings |
|
||||
| `inspector` | 🔍 | Control | API endpoint debugger (footer) |
|
||||
|
||||
## CLI Commands
|
||||
|
||||
### Core Commands
|
||||
|
||||
```bash
|
||||
aiui init [--template docs|minimal|marketing] [--frontend] # Create project
|
||||
aiui validate [--config FILE] [--strict] # Validate config
|
||||
aiui build [--config FILE] [--output DIR] [--minify] # Build static site
|
||||
aiui serve [--port 8000] [--reload] [--style STYLE] # Serve site
|
||||
aiui run app.py [--port 8000] [--reload] [--style STYLE] # Run AI server
|
||||
aiui run chat.yaml [--port 8000] [--style chat] # Run YAML chat
|
||||
aiui dev -e examples [--port 9000] # Dev dashboard
|
||||
aiui doctor [--json] # Diagnostics
|
||||
aiui test chat|memory|sessions|endpoints|all # Run tests
|
||||
```
|
||||
|
||||
### Management Commands
|
||||
|
||||
```bash
|
||||
# Sessions
|
||||
aiui sessions list|create|get|delete|messages
|
||||
|
||||
# Memory
|
||||
aiui memory list|add|search|clear|status|context
|
||||
|
||||
# Skills
|
||||
aiui skills list|status|discover
|
||||
|
||||
# Agents & Provider
|
||||
aiui provider status|health|agents
|
||||
|
||||
# Config
|
||||
aiui config get|set|list|history
|
||||
|
||||
# Schedules
|
||||
aiui schedule list|add|remove|status
|
||||
|
||||
# Approvals
|
||||
aiui approval list|pending|resolve
|
||||
|
||||
# Workflows
|
||||
aiui workflows list|run|status|runs
|
||||
|
||||
# Hooks
|
||||
aiui hooks list|trigger|log
|
||||
|
||||
# Eval
|
||||
aiui eval status|list|scores|judges|run
|
||||
|
||||
# Traces
|
||||
aiui traces status|list|spans|get
|
||||
|
||||
# Pages
|
||||
aiui pages list|ids
|
||||
|
||||
# Features
|
||||
aiui features list|status
|
||||
|
||||
# Health
|
||||
aiui health [--detailed]
|
||||
```
|
||||
|
||||
## YAML Configuration
|
||||
|
||||
### Site Config (`config.yaml` in `~/.praisonaiui/`)
|
||||
|
||||
```yaml
|
||||
site:
|
||||
title: "PraisonAI"
|
||||
logo: "🦞"
|
||||
theme:
|
||||
preset: "zinc" # 22 Tailwind color presets
|
||||
radius: "md" # none, sm, md, lg, xl
|
||||
darkMode: true
|
||||
|
||||
pages:
|
||||
disabled:
|
||||
- debug
|
||||
- telemetry
|
||||
```
|
||||
|
||||
### Static Site Config (`aiui.template.yaml`)
|
||||
|
||||
```yaml
|
||||
schemaVersion: 1
|
||||
|
||||
site:
|
||||
title: "My Docs"
|
||||
theme:
|
||||
preset: "blue"
|
||||
darkMode: true
|
||||
|
||||
content:
|
||||
docs:
|
||||
dir: "./docs"
|
||||
|
||||
templates:
|
||||
docs:
|
||||
layout: "ThreeColumnLayout"
|
||||
```
|
||||
|
||||
## Theme Presets
|
||||
|
||||
22 Tailwind color presets with automatic dark/light mode:
|
||||
|
||||
`zinc` `slate` `stone` `gray` `neutral` `red` `orange` `amber` `yellow` `lime` `green` `emerald` `teal` `cyan` `sky` `blue` `indigo` `violet` `purple` `fuchsia` `pink` `rose`
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Purpose | Default |
|
||||
|----------|---------|---------|
|
||||
| `OPENAI_API_KEY` | OpenAI API key | — |
|
||||
| `PRAISONAI_MODEL` | Default model | `gpt-4o-mini` |
|
||||
| `AIUI_DATA_DIR` | Data directory | `~/.praisonaiui` |
|
||||
| `AIUI_CONFIG` | Config file path | `aiui.template.yaml` |
|
||||
| `AIUI_OUTPUT` | Build output dir | `aiui` |
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Dashboard Mode: Docs Mode:
|
||||
app.py → aiui run → Server aiui.template.yaml → aiui build → aiui/
|
||||
↓ ├── index.html
|
||||
http://localhost:8000 ├── docs/*.md
|
||||
├── /api/chat/ws (WebSocket) ├── ui-config.json
|
||||
├── /api/pages └── assets/
|
||||
├── /api/agents
|
||||
├── /sessions
|
||||
└── /ui-config.json
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
git clone https://github.com/MervinPraison/PraisonAIUI.git
|
||||
cd PraisonAIUI
|
||||
pip install -e .[dev]
|
||||
pytest tests -v
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT © [Praison Limited](https://praison.ai)
|
||||
|
||||
Third-party vendored source is documented in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|
||||
See the [BeautifulUI upgrade playbook](docs/frontend/beautifului.md) for how BeautifulUI
|
||||
primitives are vendored and pinned.
|
||||
-37
@@ -1,37 +0,0 @@
|
||||
# Security Policy
|
||||
|
||||
We take the security of PraisonAIUI seriously and appreciate responsible
|
||||
disclosure of vulnerabilities.
|
||||
|
||||
## Supported Versions
|
||||
|
||||
Security fixes are applied to the latest released version of PraisonAIUI.
|
||||
Please make sure you are on the most recent release before reporting.
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
**Please do not open a public issue for security vulnerabilities.**
|
||||
|
||||
Report privately through GitHub's **Private Vulnerability Reporting**:
|
||||
|
||||
1. Go to the [Security tab](https://github.com/MervinPraison/PraisonAIUI/security)
|
||||
of this repository.
|
||||
2. Click **"Report a vulnerability"** to open a private advisory.
|
||||
3. Include as much detail as you can:
|
||||
- Affected component(s) and version.
|
||||
- Steps to reproduce.
|
||||
- Impact assessment.
|
||||
- Any suggested fix or mitigation.
|
||||
|
||||
If you are unable to use private reporting, you may open a public issue that
|
||||
contains **no technical specifics** and requests a private channel, and a
|
||||
maintainer will follow up.
|
||||
|
||||
## What to Expect
|
||||
|
||||
- We aim to acknowledge new reports within a few business days.
|
||||
- We will keep you informed as we investigate and work on a fix.
|
||||
- Once a fix is released, we are happy to credit you in the advisory (unless
|
||||
you prefer to remain anonymous).
|
||||
|
||||
Thank you for helping keep PraisonAIUI and its users safe.
|
||||
@@ -1,43 +0,0 @@
|
||||
# Third-Party Notices
|
||||
|
||||
PraisonAIUI incorporates or vendors source from the third-party projects listed below.
|
||||
Their licences and copyright notices are retained here as required.
|
||||
|
||||
---
|
||||
|
||||
## BeautifulUI
|
||||
|
||||
- Project: BeautifulUI — <https://www.beautifului.dev/>
|
||||
- Source: <https://github.com/slev12397/beautiful-ui>
|
||||
- Licence: MIT
|
||||
|
||||
BeautifulUI is distributed as a shadcn registry / copy-paste library (no npm package).
|
||||
When its React primitives are vendored into `src/frontend`, the following MIT licence
|
||||
applies to that copied source.
|
||||
|
||||
```
|
||||
MIT License
|
||||
|
||||
Copyright (c) Shane Levine
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
```
|
||||
|
||||
See the upgrade playbook at [`docs/frontend/beautifului.md`](docs/frontend/beautifului.md)
|
||||
for how BeautifulUI is vendored and pinned.
|
||||
@@ -1,155 +0,0 @@
|
||||
schemaVersion: 1
|
||||
|
||||
site:
|
||||
title: "PraisonAIUI Docs"
|
||||
description: "Documentation for PraisonAIUI - YAML-driven website generator"
|
||||
ui: "shadcn"
|
||||
theme:
|
||||
preset: "zinc"
|
||||
radius: "md"
|
||||
darkMode: true
|
||||
|
||||
seo:
|
||||
siteUrl: "https://ui.praison.ai"
|
||||
titleTemplate: "%s | %s"
|
||||
defaultImage: "/icon.svg"
|
||||
robots:
|
||||
index: true
|
||||
follow: true
|
||||
|
||||
# Mintlify-style navigation: few tabs, many groups per tab
|
||||
navigation:
|
||||
tabs:
|
||||
- tab: "Documentation"
|
||||
groups:
|
||||
- group: "Getting Started"
|
||||
icon: "rocket"
|
||||
prefix: "getting-started"
|
||||
pages:
|
||||
- index
|
||||
- getting-started/installation
|
||||
- getting-started/quickstart
|
||||
- getting-started/cli
|
||||
- getting-started/github-pages
|
||||
- group: "Core Concepts"
|
||||
icon: "lightbulb"
|
||||
prefix: "concepts"
|
||||
pages:
|
||||
- concepts/architecture
|
||||
- concepts/configuration
|
||||
- concepts/templates
|
||||
- concepts/slots
|
||||
- concepts/providers
|
||||
- group: "Features"
|
||||
icon: "sparkles"
|
||||
prefix: "features"
|
||||
pages:
|
||||
- features/content-sources
|
||||
- features/navigation
|
||||
- features/theming
|
||||
- features/dark-mode
|
||||
- features/seo
|
||||
- features/hot-reload
|
||||
- features/protocols
|
||||
- group: "TypeScript"
|
||||
icon: "file-code"
|
||||
prefix: "typescript"
|
||||
pages:
|
||||
- typescript/index
|
||||
- typescript/runtime
|
||||
- typescript/nextjs
|
||||
- typescript/components
|
||||
- group: "Frontend"
|
||||
icon: "layout"
|
||||
prefix: "frontend"
|
||||
pages:
|
||||
- frontend/beautifului
|
||||
- group: "Examples"
|
||||
icon: "folder-open"
|
||||
prefix: "examples"
|
||||
pages:
|
||||
- examples/basic
|
||||
- examples/advanced
|
||||
- tab: "API Reference"
|
||||
groups:
|
||||
- group: "API Reference"
|
||||
icon: "code"
|
||||
prefix: "api"
|
||||
pages:
|
||||
- api/cli
|
||||
- api/features-api
|
||||
- api/python
|
||||
- api/sessions
|
||||
- api/typescript
|
||||
|
||||
|
||||
# Navbar actions
|
||||
navbar:
|
||||
primary:
|
||||
type: "button"
|
||||
label: "Get started"
|
||||
href: "/docs/getting-started/quickstart"
|
||||
links:
|
||||
- label: "GitHub"
|
||||
href: "https://github.com/MervinPraison/PraisonAIUI"
|
||||
|
||||
# Footer
|
||||
footer:
|
||||
socials:
|
||||
github: "https://github.com/MervinPraison/PraisonAI"
|
||||
x: "https://x.com/MervinPraison"
|
||||
youtube: "https://youtube.com/@MervinPraison"
|
||||
links:
|
||||
- header: "Resources"
|
||||
items:
|
||||
- label: "GitHub"
|
||||
href: "https://github.com/MervinPraison/PraisonAI"
|
||||
- label: "Documentation"
|
||||
href: "https://docs.praisonai.com"
|
||||
- header: "Community"
|
||||
items:
|
||||
- label: "Twitter"
|
||||
href: "https://x.com/MervinPraison"
|
||||
- label: "YouTube"
|
||||
href: "https://youtube.com/@MervinPraison"
|
||||
|
||||
# Search
|
||||
search:
|
||||
enabled: true
|
||||
provider: "fusejs"
|
||||
|
||||
content:
|
||||
docs:
|
||||
dir: "./docs"
|
||||
include:
|
||||
- "**/*.md"
|
||||
- "**/*.mdx"
|
||||
|
||||
templates:
|
||||
docs:
|
||||
layout: "ThreeColumnLayout"
|
||||
slots:
|
||||
header: { ref: "header_main" }
|
||||
left: { ref: "sidebar_docs" }
|
||||
main: { type: "DocContent" }
|
||||
footer: { ref: "footer_main" }
|
||||
|
||||
components:
|
||||
header_main:
|
||||
type: "Header"
|
||||
props:
|
||||
logoText: "PraisonAIUI"
|
||||
|
||||
footer_main:
|
||||
type: "Footer"
|
||||
props:
|
||||
text: "© 2026 PraisonAI"
|
||||
|
||||
sidebar_docs:
|
||||
type: "DocsSidebar"
|
||||
props:
|
||||
source: "docs-nav"
|
||||
|
||||
routes:
|
||||
- match: "/docs/**"
|
||||
template: "docs"
|
||||
@@ -1,112 +0,0 @@
|
||||
"""PraisonAIUI — Default App (Dashboard with Agents + Feature Explorer).
|
||||
|
||||
Loaded by ``aiui run app.py`` (see Dockerfile / CLI).
|
||||
All built-in sidebar pages are enabled by default.
|
||||
|
||||
Agents: Researcher, Writer, Coder
|
||||
Custom page: Feature Explorer
|
||||
"""
|
||||
|
||||
import os
|
||||
import praisonaiui as aiui
|
||||
|
||||
# ── Dashboard style ─────────────────────────────────────────
|
||||
aiui.set_style("dashboard")
|
||||
aiui.set_pages([
|
||||
"chat", # Core AI chat
|
||||
"channels", # Messaging platforms
|
||||
"agents", # Agent management
|
||||
"skills", # Available tools
|
||||
"memory", # Agent memory
|
||||
"knowledge", # Knowledge base
|
||||
"cron", # Scheduled jobs
|
||||
"guardrails", # Safety rules
|
||||
"sessions", # Conversation history
|
||||
"usage", # Token usage & costs
|
||||
"config", # Runtime configuration
|
||||
"logs", # Server logs
|
||||
"debug", # System debug info
|
||||
])
|
||||
|
||||
# ── Agent definitions ───────────────────────────────────────
|
||||
AGENTS = [
|
||||
{
|
||||
"agent_id": "researcher",
|
||||
"name": "Researcher",
|
||||
"description": "Research assistant — finds and summarizes information",
|
||||
"instructions": (
|
||||
"You are a research assistant. Provide well-structured answers "
|
||||
"with key facts. Keep responses concise but informative."
|
||||
),
|
||||
"model": os.getenv("PRAISONAI_MODEL", "gpt-4o-mini"),
|
||||
"icon": "🔬",
|
||||
},
|
||||
{
|
||||
"agent_id": "writer",
|
||||
"name": "Writer",
|
||||
"description": "Creative writer — generates content on any topic",
|
||||
"instructions": (
|
||||
"You are a creative writer. Write engaging content in a clear, "
|
||||
"professional style. Keep responses focused and well-organized."
|
||||
),
|
||||
"model": os.getenv("PRAISONAI_MODEL", "gpt-4o-mini"),
|
||||
"icon": "✍️",
|
||||
},
|
||||
{
|
||||
"agent_id": "coder",
|
||||
"name": "Coder",
|
||||
"description": "Coding assistant — Python, JavaScript, and more",
|
||||
"instructions": (
|
||||
"You are a coding assistant. Write clean, well-commented "
|
||||
"code with explanations. Support Python, JavaScript, and "
|
||||
"other popular languages."
|
||||
),
|
||||
"model": os.getenv("PRAISONAI_MODEL", "gpt-4o-mini"),
|
||||
"icon": "💻",
|
||||
},
|
||||
]
|
||||
|
||||
|
||||
|
||||
# ── Custom page: Feature Explorer ───────────────────────────
|
||||
|
||||
@aiui.page(
|
||||
"explorer",
|
||||
title="Explorer",
|
||||
icon="🔬",
|
||||
group="Control",
|
||||
order=55,
|
||||
)
|
||||
async def explorer_page():
|
||||
"""Three-column feature explorer — custom view renders in JS."""
|
||||
return aiui.layout([
|
||||
aiui.text("Feature Explorer loads via custom view module."),
|
||||
])
|
||||
|
||||
|
||||
# ── Register agents in dashboard CRUD ───────────────────────
|
||||
|
||||
def _register_agents_in_dashboard():
|
||||
"""Bridge agents into the dashboard agents_crud feature."""
|
||||
from praisonaiui.features.agents import get_agent_registry
|
||||
|
||||
registry = get_agent_registry()
|
||||
existing = registry.list_all()
|
||||
existing_names = {a.get("name") for a in existing}
|
||||
|
||||
for agent_def in AGENTS:
|
||||
if agent_def["name"] in existing_names:
|
||||
continue
|
||||
registry.create({
|
||||
"name": agent_def["name"],
|
||||
"description": agent_def["description"],
|
||||
"instructions": agent_def["instructions"],
|
||||
"model": agent_def["model"],
|
||||
"icon": agent_def["icon"],
|
||||
})
|
||||
print(f" ✓ Agent: {agent_def['icon']} {agent_def['name']}")
|
||||
|
||||
try:
|
||||
_register_agents_in_dashboard()
|
||||
except Exception as e:
|
||||
print(f" ⚠️ Agent registration failed (non-fatal): {e}")
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
Loaded 100 of 921 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user