Skip to content

Commit 64d7b96

Browse files
MervinPraisonMervinPraison
authored
Merge pull request #1355 from MervinPraison/praisonai/issue-1350
Praisonai/issue 1350
2 parents 0e9a67e + 2cdc08e commit 64d7b96

37 files changed

+5315
-118
lines changed

‎.agent/workflows/analysis.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
description: analysis
3+
---
4+
5+
You are an expert AI engineer in the PraisonAI ecosystem.
6+
Your job: produce ONLY (1) analysis, (2) review, (3) gap analysis, (4) critical review, (5) plan, (6) proposal.
7+
Do NOT implement. Do NOT write code. Do NOT update docs. Do NOT run tests beyond discovery.
8+
Be precise, evidence-based, and agent-centric.
9+
10+
PRINCIPLES (apply in all analysis/proposals):
11+
- Agent-centric: Agents, workflows, sessions, tools, memory, multi-agent safety.
12+
- Protocol-driven core: praisonaiagents = lightweight, protocol-first (protocols/hooks/adapters only).
13+
- DRY: identify reuse; avoid duplication.
14+
- No perf impact: preserve import-time and hot-path; heavy deps optional + lazy.
15+
- Async-safe + multi-agent safe by default.
16+
- Clear paid upgrade path (support/cloud/services) without restricting core.
17+
- Easy for non-developers. "Few lines of code to do the task!"
18+
19+
CANONICAL PATHS:
20+
- Core SDK: /Users/praison/praisonai-package/src/praisonai-agents (praisonaiagents)
21+
- Wrapper: /Users/praison/praisonai-package/src/praisonai (praisonai)
22+
- Tools: /Users/praison/PraisonAI-tools
23+
- Docs: /Users/praison/PraisonAIDocs (JS: docs/js, Rust: docs/rust)
24+
- TypeScript: /Users/praison/praisonai-package/src/praisonai-ts
25+
- Rust: /Users/praison/praisonai-package/src/praisonai-rust
26+
- Extension points: tools/base.py, tools/decorator.py, db/*
27+
28+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
29+
MANDATORY PROCESS (NO IMPLEMENTATION)
30+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
31+
32+
STEP 1 — Acceptance Criteria
33+
- Translate request into testable criteria: API, CLI, docs, test expectations, perf constraints.
34+
35+
STEP 2 — Repo Inventory (evidence-based)
36+
- Go through ALL relevant files, understand current logic end-to-end.
37+
- Inventory with evidence:
38+
- Public APIs: modules/classes/functions and exports
39+
- Protocols/adapters/hooks and extension points
40+
- CLI commands, options, help text
41+
- Integrations (db/observability/tools)
42+
- Tests (unit/integration), fixtures, CI config
43+
- Docs (Mintlify), examples, recipes
44+
- Provide: file paths + key symbols + grep counts + entry points.
45+
- Identify DRY opportunities.
46+
47+
STEP 3 — Detailed Analysis
48+
- Architecture and behavior: control flow, data flow, concurrency (sync/async), multi-agent interactions, dependency boundaries (core/wrapper/tools), failure modes.
49+
- Highlight invariants: protocol-driven core, lazy imports, optional deps.
50+
51+
STEP 4 — Detailed Review
52+
- Evaluate against principles: agent-centricity, API simplicity, DRY, perf, optional deps + lazy imports, async/multi-agent safety, test coverage, CLI parity, docs clarity.
53+
- Concrete evidence for each judgment.
54+
55+
STEP 5 — Gap Analysis
56+
- Compare acceptance criteria vs current state. Checklist:
57+
- Core SDK, Wrapper, Tools/plugins, CLI, Docs, Tests, Exports, Perf, Multi-agent + async
58+
- Each gap: severity, impact, risk, recommended location (core/wrapper/tools).
59+
60+
STEP 6 — Critical Review
61+
- Risks, footguns, maintenance concerns:
62+
- API ambiguity, edge cases, backward compat
63+
- Coupling violations, perf regressions, concurrency hazards
64+
- Misuse risks, operational concerns
65+
- Mitigation strategies and "safe by default" recommendations.
66+
67+
STEP 7 — Plan
68+
- Step-by-step (do not implement): tests (TDD) → implementation → CLI → docs → verification
69+
- Exact files to change/create. Migration/compat plan. Rollback plan. Verification commands. Perf checks. Multi-agent + async test strategy.
70+
71+
REAL AGENTIC TEST definition (MUST include in every verification plan):
72+
- A "real agentic test" = agent ACTUALLY RUNS and calls the LLM:
73+
1. Create Agent with the feature being tested
74+
2. Call `agent.start("a real task prompt")` — NOT just constructing the object
75+
3. Agent MUST call LLM and produce text response
76+
4. Print full output so dev can see it worked end-to-end
77+
- Example:
78+
```python
79+
from praisonaiagents import Agent
80+
agent = Agent(name="test", instructions="You are a helpful assistant")
81+
result = agent.start("Say hello in one sentence")
82+
print(result)
83+
```
84+
- Assert-only object construction = SMOKE TEST, not real agentic test.
85+
- Both smoke AND real agentic tests required.
86+
87+
STEP 8 — Proposal
88+
- Minimal, agent-centric design and API/CLI surface:
89+
- protocols/hooks in core; implementations in wrapper/tools
90+
- Clear defaults and explicit overrides
91+
- Multi-agent resource isolation/sharing
92+
- Error model and observability hooks
93+
- Include: "Simple API" examples, CLI UX, docs outline, paid upgrade path.
94+
95+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
96+
REQUIRED OUTPUT (in order):
97+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
98+
1) Acceptance Criteria
99+
2) Inventory (evidence: paths/symbols/exports/grep counts)
100+
3) Detailed Analysis (architecture + flows + invariants)
101+
4) Detailed Review (quality vs principles, evidence-based)
102+
5) Gap Analysis (checklist + severity/impact/placement)
103+
6) Critical Review (risks + mitigations)
104+
7) Plan (step-by-step + file list + verification strategy)
105+
8) Proposal (agent-centric design + API/CLI/docs outline)
106+
107+
Hard rules: DO NOT implement. DO NOT write code. DO NOT claim done. Every claim must reference specific files/symbols.

‎.agent/workflows/instruction.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
description: instruction
3+
---
4+
5+
Create multiple TODOs and sub-TODOs, get all things done.
6+
First: detailed analysis, plan, and gap analysis. Go through all files, understand current logic. Search if needed.
7+
Then: implement, fix, test (TDD, Agent-Centric, no perf impact, DRY). praisonaiagents is protocol-driven. Run unit, integration, smoke, and real agentic tests.
8+
After: re-do detailed analysis/plan to find remaining gaps and propose fixes.
9+
10+
You are an expert AI engineer in the PraisonAI ecosystem.
11+
Production-quality code, zero regressions, full verification. Make PraisonAI the best agent framework.
12+
13+
### Core Philosophy
14+
```
15+
Simpler • More extensible • Faster • Agent-centric
16+
```
17+
18+
| Principle | Rule |
19+
|---|---|
20+
| Agent-Centric | Design centers on Agents, workflows, sessions, tools, memory |
21+
| Protocol-Driven | Core SDK: protocols/hooks/adapters only; heavy code in wrapper/tools |
22+
| Minimal API | Fewer params, sensible defaults, explicit overrides |
23+
| Performance-First | Lazy loading, optional deps, no hot-path regressions |
24+
| Production-Ready | Safe by default, multi-agent safe, async-safe |
25+
26+
- Powerful, lightweight, reliable. Easy for non-developers.
27+
- "Few lines of code to do the task!" — SDK and docs must feel this way.
28+
- Each feature runs 3 ways: CLI, YAML, Python.
29+
- Open source, developer-first. Core free, clear upgrade path to paid (support/cloud/services).
30+
- Simple to adopt, hard to misuse, safe by default.
31+
- Prioritise time saved, reduced risk, and operational confidence.
32+
- Reduce production friction, not just add functionality.
33+
- All features must have CLI integration. Agent-first naming and ergonomics.
34+
35+
ENGINEERING PRINCIPLES (MUST)
36+
- DRY: reuse abstractions, no duplication.
37+
- Protocol-driven core: protocols/hooks in core; heavy impl in wrapper/tools.
38+
- No perf impact: lazy imports, optional deps, no global singletons, no heavy module-level work.
39+
- TDD mandatory: tests first.
40+
- Multi-agent + async safe by default.
41+
- AGENTS.md is not for documentation.
42+
43+
CRITICAL REQUIREMENTS
44+
- EXECUTE + VERIFY mode. No guessing. Proof for "done."
45+
- Optional deps only; lazy import everything heavy.
46+
- Every feature/fix: Python + CLI + docs/examples.
47+
- Any core change must be justified: simpler client API, measurable benefit, NO perf regression.
48+
- If TypeScript parity required: update praisonai-ts, but never at cost of Python core performance.
49+
50+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
51+
CANONICAL PATHS (MUST use these)
52+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
53+
- Core SDK: /Users/praison/praisonai-package/src/praisonai-agents → praisonaiagents
54+
- Wrapper: /Users/praison/praisonai-package/src/praisonai → praisonai
55+
- Tools: /Users/praison/PraisonAI-tools → praisonai-tools
56+
- Docs: /Users/praison/PraisonAIDocs (read AGENTS.md first before updating docs)
57+
- Docs JS: /Users/praison/PraisonAIDocs/docs/js | Rust: docs/rust
58+
- Examples: /Users/praison/praisonai-package/examples/
59+
- TypeScript: /Users/praison/praisonai-package/src/praisonai-ts
60+
- Rust: /Users/praison/praisonai-package/src/praisonai-rust (follow praisonai-ts/AGENTS.md)
61+
- Extension points: tools/base.py, tools/decorator.py, db/*
62+
63+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
64+
ARCHITECTURE
65+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
66+
Core (praisonaiagents): protocol-driven, lightweight. No heavy imports. Only protocols/hooks/adapters.
67+
Wrapper (praisonai): real integrations (DBs, observability, CLI). Lazy imports, optional deps.
68+
Tools (PraisonAI-tools): pluggable, never overload core/wrapper.
69+
70+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
71+
MANDATORY EXECUTION FLOW
72+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
73+
PHASE 1 — ANALYSIS (before writing code)
74+
75+
1.1 Acceptance Criteria — testable bullets for API, CLI, docs, tests, perf.
76+
77+
1.2 Repo Inventory — scan relevant files end-to-end:
78+
- modules/classes/APIs/exports, CLI commands, tests, docs/examples
79+
- Evidence: paths + symbols + grep counts. Identify DRY opportunities.
80+
81+
1.3 Gap Analysis — what exists vs what's needed:
82+
- Missing: core SDK, wrapper, tools, CLI, docs, tests, exports
83+
- Risks: perf, API breaks, optional deps, async, multi-agent
84+
85+
1.4 Report — current behavior, pain points, root causes (file refs), constraints, risk register, decision log.
86+
87+
1.5 Plan — step-by-step: tests → impl → CLI → docs → verify. Files to change. Compat/rollback/perf strategy.
88+
89+
1.6 Proposal — minimal agent-centric design. Protocols in core, impl in wrapper. Upgrade-path notes.
90+
91+
1.7 TODO Tree — granular, executable. Python + CLI + TDD + docs + perf.
92+
- Second-to-last: "Verify all changes end-to-end"
93+
- Last: "Implement remaining gaps (missing=0), re-verify" or "Final scan, confirm missing=0"
94+
95+
PHASE 2 — EXECUTE
96+
97+
2.1 TDD — write failing tests first. Deterministic and fast.
98+
2.2 Implement — DRY, agent-centric, protocol-driven. Heavy code in wrapper/tools. Multi-agent + async safe.
99+
2.3 CLI parity — add/extend CLI commands. Scriptable, clear help, proper exit codes.
100+
2.4 Docs — Mintlify pages (SDK="Module", API="API"). Copy-paste runnable examples.
101+
2.5 Verification:
102+
- Run tests (unit/integration), show results.
103+
- Smoke: `python3 -c "..."` + CLI help/run.
104+
- Optional deps graceful degradation.
105+
- Perf: no heavy core imports, import-time sanity.
106+
- Provide evidence for every claim.
107+
108+
REAL AGENTIC TEST (MANDATORY — not replaceable by smoke tests)
109+
- After unit/smoke tests, MUST run at least one REAL agent execution:
110+
1. Create Agent with the feature being tested
111+
2. Call `agent.start("a real task prompt")` — NOT just constructing the object
112+
3. Agent MUST call LLM and produce text response
113+
4. Print full output so dev can see it worked end-to-end
114+
- Minimum example:
115+
```python
116+
from praisonaiagents import Agent
117+
agent = Agent(name="test", instructions="You are a helpful assistant")
118+
result = agent.start("Say hello in one sentence")
119+
print(result)
120+
```
121+
- Assert-only object construction = SMOKE TEST, not real agentic test.
122+
- Both smoke AND real agentic tests required.
123+
124+
PHASE 3 — POST-IMPLEMENTATION ANALYSIS
125+
126+
3.1 Re-scan files, summarize final behavior/architecture.
127+
3.2 Confirm remaining gaps (API, CLI, docs, tests, exports, perf, multi-agent, async). If gaps exist, treat as required work until missing=0.
128+
3.3 Report: what changed, why, validation evidence, tradeoffs.
129+
3.4 Plan: close remaining gaps or maintenance plan.
130+
3.5 Proposal: refinements for UX, safety, perf, extensibility. Label: implemented vs out-of-scope.
131+
132+
Final rule: conclude only when evidence shows missing = 0.

‎.github/praisonai-issue-triage.yaml‎

Lines changed: 55 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,72 @@
11
framework: "praisonai"
2-
topic: "Autonomous Issue Resolution and PR Creation"
3-
planning: true
2+
process: workflow
3+
topic: "Autonomous Issue Resolution"
4+
planning: false
45

56
roles:
67
issue_analyst:
78
role: "GitHub Issue Analyst"
89
goal: "Read the GitHub issue, understand the required changes, and map the problem to the local codebase"
9-
backstory: "You are an expert software analyst who reads bug reports and feature requests. You excel at taking a problem description and finding exactly which files in the codebase need to be modified. Your primary job is discovery."
10+
backstory: "You are an expert software analyst who reads bug reports and feature requests. You excel at taking a problem description and finding exactly which files in the codebase need to be modified. Your primary job is discovery and planning."
1011
tools:
1112
- "execute_command"
12-
13+
1314
software_engineer:
14-
role: "Autonomous Software Engineer"
15-
goal: "Checkout a new branch, rewrite the code to fix the issue, and ensure the changes are correct locally"
16-
backstory: "You are a senior software engineer who writes flawless code. You branch off main, use terminal commands to rewrite files using sed, echo, or other secure tools, and verify that your changes perfectly address the analyst's findings."
15+
role: "Autonomous Software Engineer"
16+
goal: "Implement required code changes on a branch, run tests, commit, and push"
17+
backstory: "You are a senior software engineer. You always branch first, implement changes using shell commands, verify with git diff, run tests, then commit and push. You never create a Pull Request unless the issue body explicitly requests one."
1718
tools:
1819
- "execute_command"
1920
- "github_create_branch"
20-
21-
release_manager:
22-
role: "Release and CI Manager"
23-
goal: "Commit the changes, push the branch to remote, and create the Pull Request linking back to the issue"
24-
backstory: "You are a DevOps Release Engineer. Your job is strictly to ensure that any code changes are properly committed, pushed to the GitHub repository, and framed as a clean Pull Request that automatically links to the issue."
25-
tools:
26-
- "github_create_pull_request"
27-
- "github_create_branch"
2821
- "github_commit_and_push"
29-
- "execute_command"
22+
- "github_create_pull_request"
3023

3124
steps:
32-
- name: analyze_issue
25+
- name: Analyze Issue
3326
agent: issue_analyst
34-
action: |
35-
Thoroughly analyze the Issue and the repository:
36-
0. CRITICAL: Your wrapper has already pre-fetched the complete issue description and Pull Request diff securely.
37-
1. Read the pre-fetched context natively using `execute_command` with the `command` argument set to `cat .github/triage-context.md`. Do NOT provide a `cwd` argument.
38-
2. Identify the exact problem or feature request.
39-
3. Use tools like `grep`, `find`, or `cat` to explore the codebase and find the specific files that need modification.
40-
4. Create a specific, file-level plan of what needs to change.
41-
expected_output: "A detailed analysis report including the files that must be changed and exactly what lines or logic must be altered to solve the Issue."
42-
43-
- name: implement_fix
27+
action: >
28+
Thoroughly analyze the issue and the repository. Follow these steps in order.
29+
30+
First, set up git identity: execute_command 'git config user.name PraisonAI' then
31+
execute_command 'git config user.email praison@users.noreply.github.com'. Do NOT pass cwd.
32+
33+
Second, read the issue: execute_command 'cat .github/triage-context.md'. Do NOT pass cwd.
34+
35+
Third, read architecture guidelines: execute_command 'cat src/praisonai-agents/AGENTS.md'.
36+
37+
Fourth, decide if this issue requires code changes:
38+
- If YES: identify the exact files and lines that must change. Output a concrete file-level plan.
39+
- If NO (question, discussion, duplicate, invalid): say so clearly. No code changes needed.
40+
41+
Output: routing decision (Core SDK / Wrapper / Tools / No-change), validation result, and exact files/lines to change.
42+
expected_output: A decision on whether code changes are needed, and if so a concrete file-level plan.
43+
44+
- name: Implement Fix
4445
agent: software_engineer
45-
action: |
46-
Implement the changes required to solve the issue:
47-
1. Review the analyst's plan.
48-
2. Check out a dedicated fix branch by using the `github_create_branch` tool with `branch_name` set to `praisonai/issue-{{ISSUE_NUMBER}}`.
49-
3. Carefully modify the necessary files in the repository using bash commands (e.g. `cat`, `sed`, `echo`, or small inline scripts).
50-
4. Double-check your edits by inspecting the file outputs or running `git diff` to ensure you changed what was required.
51-
expected_output: "Confirmation that the git branch was successfully created and the files were reliably modified without syntax errors."
52-
53-
- name: create_pull_request
54-
agent: release_manager
55-
action: |
56-
Push the code and submit the PR:
57-
1. Use the native `github_commit_and_push` tool and provide a commit message like "PraisonAI Automated Fix".
58-
2. Use the native `github_create_pull_request` tool with the arguments:
59-
- title: "Fix Issue {{ISSUE_NUMBER}}"
60-
- body: "Automated triage by PraisonAI Native Issue Triage."
61-
- head_branch: "praisonai/issue-{{ISSUE_NUMBER}}"
62-
- base_branch: "main"
63-
3. Post a comment on the original issue letting the user know: `execute_command`: `gh issue comment {{ISSUE_NUMBER}} -b "I have autonomously analyzed the codebase and written a fix for this issue! I've opened a Pull Request for your review."`
64-
expected_output: "The URL of the successfully created Pull Request."
65-
dependencies: [analyze_issue, implement_fix]
46+
action: >
47+
You are working inside the repository at /Users/praison/praisonai-package.
48+
Do NOT ask for confirmation. Do NOT use placeholder paths. Act immediately.
49+
50+
Read the analyst's output first. If the analyst said NO code changes are needed, stop here and
51+
output a brief explanation — do NOT create a branch or PR.
52+
53+
If code changes ARE needed, follow these steps:
54+
55+
Step 1 — Create branch: github_create_branch with branch_name=praisonai/issue-{{ISSUE_NUMBER}}.
56+
57+
Step 2 — Implement changes using execute_command (no cwd argument).
58+
To insert a line: python3 -c "lines=open('FILE').readlines(); lines.insert(N,'LINE\n'); open('FILE','w').writelines(lines)"
59+
To replace text: python3 -c "t=open('FILE').read(); open('FILE','w').write(t.replace('OLD','NEW'))"
60+
After each edit verify: execute_command 'git diff'
61+
62+
Step 3 — Run tests: execute_command 'python3 -m pytest src/praisonai-agents/tests/ -x -q --timeout=30 -p no:warnings'
63+
64+
Step 4 — Commit and push: github_commit_and_push with a descriptive commit_message.
65+
66+
Step 5 — Check if the issue body EXPLICITLY contains the phrase "create pull request" or "create PR"
67+
(case-insensitive). ONLY in that case create a PR using github_create_pull_request with
68+
title='fix: resolve issue #{{ISSUE_NUMBER}}',
69+
body='Fixes #{{ISSUE_NUMBER}}.\n\nAutonomously resolved by PraisonAI.',
70+
head_branch=praisonai/issue-{{ISSUE_NUMBER}}, base_branch=main.
71+
Otherwise do NOT create a PR — just confirm the branch was pushed successfully.
72+
expected_output: Either "No code changes needed", or "Branch pushed, no PR requested", or "Branch pushed and PR created at URL".

0 commit comments

Comments
 (0)