mirror of
https://github.com/MervinPraison/PraisonAI.git
synced 2026-11-07 12:47:55 -10:00
docs: align AGENTS.md with praisonai-ts review and triage routing
Document TypeScript SDK ownership in the monorepo, add PR review checklists, and point issue triage at src/praisonai-ts/AGENTS.md so agents review TS changes correctly. Co-authored-by: Cursor <[email protected]>
This commit is contained in:
MervinPraisonandCursor committed
1 parent
527552d2db
commit
b3b4a49d3a
4 files changed
+61
-4
No files matched your search
@@ -33,13 +33,14 @@ steps:
|
||||
Second, read the issue: execute_command 'cat .github/triage-context.md'. Do NOT pass cwd.
|
||||
|
||||
Third, read architecture guidelines: execute_command 'cat src/praisonai-agents/AGENTS.md'.
|
||||
If the issue is TypeScript/JavaScript SDK, also execute_command 'cat src/praisonai-ts/AGENTS.md'.
|
||||
|
||||
Fourth, decide routing before planning:
|
||||
- TypeScript/JavaScript SDK → src/praisonai-ts/ in this monorepo (read src/praisonai-ts/AGENTS.md).
|
||||
- Tools → PraisonAI-Tools: agent-callable integrations at runtime (Composio, Slack, APIs).
|
||||
- Plugins → PraisonAI-Plugins: lifecycle extensions (tracing, logging, hooks, guardrails).
|
||||
- Sandbox backends → PraisonAI-Plugins via `praisonai.sandbox` entry point.
|
||||
Core SDK/wrapper only for protocols and CLI — external repos for TS SDK/Tools/Plugins.
|
||||
Core SDK/wrapper for Python protocols and CLI; external repos for Tools/Plugins/Docs only.
|
||||
|
||||
Fifth, decide if this issue requires code changes:
|
||||
- If YES: identify the exact files and lines that must change. Output a concrete file-level plan.
|
||||
|
||||
@@ -7,10 +7,22 @@ You are working on the PraisonAI project.
|
||||
- Be concise and helpful in responses
|
||||
- Test implementation thoroughly
|
||||
- Ensure backward compatibility with existing APIs
|
||||
- Follow protocol-driven design across the nine packages: core protocols in `praisonaiagents/`, agentic terminal CLI in `praisonai-code/`, bots/gateway in `praisonai-bot/`, LLM fine-tuning + agent training in `praisonai-train/`, browser automation in `praisonai-browser/`, MCP server host in `praisonai-mcp/`, sandbox backends in `praisonai-sandbox/`, deployment in `praisonai-deploy/`, integrations/serve/dashboard in the `praisonai/` wrapper
|
||||
- The TypeScript/JavaScript SDK is canonical in `src/praisonai-ts/` here — TS fixes land in this monorepo, not in `MervinPraison/praisonai-js`, which is only the npm mirror written to by `src/praisonai-ts/` (direction: monorepo → praisonai-js, via `gh workflow run "Sync to praisonai-js" --repo MervinPraison/PraisonAI`). See `src/praisonai-ts/AGENTS.md` §2.1.1.
|
||||
- Follow protocol-driven design across the nine Python PyPI packages plus the TypeScript SDK: core protocols in `praisonaiagents/`, agentic terminal CLI in `praisonai-code/`, bots/gateway in `praisonai-bot/`, LLM fine-tuning + agent training in `praisonai-train/`, browser automation in `praisonai-browser/`, MCP server host in `praisonai-mcp/`, sandbox backends in `praisonai-sandbox/`, deployment in `praisonai-deploy/`, integrations/serve/dashboard in the `praisonai/` wrapper, TypeScript/JavaScript SDK in `src/praisonai-ts/` (`npm: praisonai`)
|
||||
- **TypeScript review routing:** For TS/JS issues and PRs, read [`src/praisonai-ts/AGENTS.md`](src/praisonai-ts/AGENTS.md) (not just this file). Canonical source is `src/praisonai-ts/` in this monorepo; [MervinPraison/praisonai-js](https://github.com/MervinPraison/praisonai-js) is the npm mirror only (sync: monorepo → praisonai-js via workflow **Sync to praisonai-js**). Do not implement TS fixes in praisonai-js for PraisonAI issues.
|
||||
- Preserve old `praisonai.*` import paths via shims when moving code between packages (see §2.3 in `src/praisonai-agents/AGENTS.md`; shim helpers in `src/praisonai/praisonai/cli/_shim.py`)
|
||||
- Package boundaries and dependency rules: `ARCHITECTURE.md` §2 (Tier 2 packages must never PyPI-depend on the wrapper; cross-tier access goes through lazy `_*_bridge` modules)
|
||||
- Boundary manifests: `src/praisonai/tests/PRAISONAI_BOT_MANIFEST.md` (C9), `src/praisonai/tests/PRAISONAI_TRAIN_MANIFEST.md` (C10), `src/praisonai/tests/PRAISONAI_BROWSER_MANIFEST.md` (C11), `src/praisonai/tests/PRAISONAI_MCP_MANIFEST.md` (C12), `src/praisonai/tests/PRAISONAI_SANDBOX_MANIFEST.md` (C13), `src/praisonai/tests/PRAISONAI_DEPLOY_MANIFEST.md` (C14)
|
||||
- When reviewing a PR or an issue, evaluate whether the change addresses a framework concern or a user goal, and design its surface (params, naming, defaults) accordingly
|
||||
- The aim of this package is to stay **lightweight and powerful**. Do a critical review at each stage — when triaging an issue, when planning a fix, and when reviewing/implementing a PR. Reject scope creep for the sake of adding features: if a capability already exists (e.g. via existing Agent params like `instructions`/`backstory`/`tools`/`hooks`/`memory`), prefer it over a new API surface. A change must genuinely strengthen the SDK (simpler, more robust, more user-friendly) — do not add knobs, params, modules, or exports that have no live consumer or that merely duplicate existing behaviour.
|
||||
- The aim of this package is to stay **lightweight and powerful**. Do a critical review at each stage — when triaging an issue, when planning a fix, and when reviewing/implementing a PR. Reject scope creep for the sake of adding features: if a capability already exists (e.g. via existing Agent params like `instructions`/`backstory`/`tools`/`hooks`/`memory`), prefer it over a new API surface. A change must genuinely strengthen the SDK (simpler, more robust, more user-friendly) — do not add knobs, params, modules, or exports that have no live consumer or that merely duplicate existing behaviour.
|
||||
|
||||
## Issue and PR routing
|
||||
|
||||
| Area | Where to implement | AGENTS.md to read | Tests |
|
||||
|------|-------------------|-------------------|-------|
|
||||
| Python core SDK | `src/praisonai-agents/praisonaiagents/` | `src/praisonai-agents/AGENTS.md` | `pytest` in `src/praisonai-agents/tests/` |
|
||||
| Python wrapper / CLI | `src/praisonai/`, `src/praisonai-code/`, etc. | `src/praisonai-agents/AGENTS.md` | `pytest` under `src/praisonai/tests/` |
|
||||
| **TypeScript / JavaScript SDK** | **`src/praisonai-ts/`** | **`src/praisonai-ts/AGENTS.md`** | `cd src/praisonai-ts && npm run build && npm test` |
|
||||
| Agent-callable tools | [PraisonAI-Tools](https://github.com/MervinPraison/PraisonAI-Tools) | — | repo tests |
|
||||
| Lifecycle plugins | [PraisonAI-Plugins](https://github.com/MervinPraison/PraisonAI-Plugins) | — | repo tests |
|
||||
| Documentation | [PraisonAIDocs](https://github.com/MervinPraison/PraisonAIDocs) | — | `nav-check` |
|
||||
| npm mirror (read-only for fixes) | [praisonai-js](https://github.com/MervinPraison/praisonai-js) | mirror of `src/praisonai-ts/AGENTS.md` | CI on praisonai-js |
|
||||
@@ -207,6 +207,7 @@ and features (capabilities, bots, framework adapters) — use
|
||||
| 2b | `praisonai-bot` | Bots, gateway, channel CLI, OS daemon |
|
||||
| 2c | `praisonai-train` | LLM fine-tuning (Unsloth), agent training, `train` CLI |
|
||||
| 3 | `praisonai` | `framework_adapters/`, capabilities, serve orchestration, dashboard |
|
||||
| 1-TS | `praisonai-ts` | TypeScript/JavaScript SDK (`npm: praisonai`); canonical path `src/praisonai-ts/` |
|
||||
|
||||
**Cross-tier rule:** `praisonai-code` must not declare a PyPI dependency on `praisonai`. Use
|
||||
[`praisonai_code._wrapper_bridge`](../praisonai-code/praisonai_code/_wrapper_bridge.py) for lazy wrapper access.
|
||||
@@ -222,6 +223,17 @@ from `praisonai_train.cli.commands.*` (`train`, C10); `_WRAPPER_RESIDENT_COMMAND
|
||||
|
||||
Full boundary doc: [`src/praisonai/tests/C7.1_BOUNDARIES.md`](../praisonai/tests/C7.1_BOUNDARIES.md).
|
||||
|
||||
### 2.5 TypeScript SDK (`praisonai-ts`)
|
||||
|
||||
Python guidelines in this file do **not** replace the TypeScript SDK guide. For any issue, PR, or review touching `src/praisonai-ts/`:
|
||||
|
||||
1. Read [`src/praisonai-ts/AGENTS.md`](../praisonai-ts/AGENTS.md) — architecture, parity, triage, and PR review rules.
|
||||
2. Implement fixes in **`src/praisonai-ts/`** in this monorepo (not in `praisonaiagents/`).
|
||||
3. Verify with `cd src/praisonai-ts && npm install && npm run build && npm test`.
|
||||
4. After merge, maintainers sync the npm mirror: `gh workflow run "Sync to praisonai-js" --repo MervinPraison/PraisonAI`.
|
||||
|
||||
[MervinPraison/praisonai-js](https://github.com/MervinPraison/praisonai-js) is the public npm checkout; direction is **monorepo → praisonai-js** only. Claude merge gate and `@claude` review TS changes under `src/praisonai-ts/` using the TS AGENTS.md criteria (lightweight, type-safe, Python parity where applicable).
|
||||
|
||||
---
|
||||
|
||||
## 3. Core SDK Architecture (praisonaiagents)
|
||||
@@ -876,6 +888,8 @@ from praisonaiagents import Workflow, Route, Parallel, Loop
|
||||
| CLI backends | `praisonai_code/cli_backends/` |
|
||||
| Back-compat shims | `praisonai/cli/_shim.py`, `praisonai/cli/main.py` |
|
||||
| C5 regression tests | `praisonai/tests/unit/test_c5_backward_compat.py` |
|
||||
| TypeScript SDK | `src/praisonai-ts/` — see `src/praisonai-ts/AGENTS.md` |
|
||||
| npm mirror (sync only) | [MervinPraison/praisonai-js](https://github.com/MervinPraison/praisonai-js) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -71,6 +71,36 @@ gh workflow run "Sync to praisonai-js" --repo MervinPraison/PraisonAI
|
||||
|
||||
Direction is **monorepo → praisonai-js** only. Do not implement TS fixes in praisonai-js for PraisonAI issues.
|
||||
|
||||
### 2.1.2 Issue triage and PR review
|
||||
|
||||
Use this section when triaging GitHub issues or reviewing PRs that touch `src/praisonai-ts/`. Root [`AGENTS.md`](../../AGENTS.md) and [`.github/workflows/claude.yml`](../../.github/workflows/claude.yml) point here for TypeScript scope.
|
||||
|
||||
**Triage**
|
||||
|
||||
| Step | Action |
|
||||
|------|--------|
|
||||
| 1 | Confirm the issue is TypeScript/JavaScript (`npm install praisonai`), not Python-only |
|
||||
| 2 | Read this file and §25 (Python parity) before planning |
|
||||
| 3 | Route agent-callable tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins; docs → PraisonAIDocs |
|
||||
| 4 | Plan changes under `src/praisonai-ts/src/` — never in `praisonaiagents/` |
|
||||
|
||||
**PR review checklist** (same bar as Python SDK: lightweight and powerful)
|
||||
|
||||
- [ ] **Scope:** Fix belongs in TS SDK, not duplicate of Python-only logic in the wrong package
|
||||
- [ ] **API surface:** Prefer existing `Agent` options; reject knobs with no consumer or that duplicate behaviour
|
||||
- [ ] **Types:** Full TypeScript types; no `any` without justification
|
||||
- [ ] **Parity:** If the change mirrors Python, check §25 and update parity trackers when needed
|
||||
- [ ] **Tests:** `npm run build && npm test` pass; new behaviour has unit tests in `tests/`
|
||||
- [ ] **Deps:** Optional deps only; lazy import heavy modules
|
||||
- [ ] **Backward compatible:** Public API breaks require deprecation path
|
||||
- [ ] **Mirror:** Do not merge direct fixes to praisonai-js — sync workflow publishes after monorepo merge
|
||||
|
||||
**Commands for reviewers and CI**
|
||||
|
||||
```bash
|
||||
cd src/praisonai-ts && npm install && npm run build && npm test
|
||||
```
|
||||
|
||||
### 2.2 TypeScript SDK Source Structure
|
||||
|
||||
```
|
||||
|
||||
Reference in new issue
Block a user