mirror of
https://github.com/MervinPraison/PraisonAI.git
synced 2026-11-09 17:31:52 -10:00
Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 praisonai-triage-agent[bot]andMervin Praison
|
85ba558a3b |
No files matched your search
@@ -1,86 +0,0 @@
|
||||
---
|
||||
name: praisonai-js-hub-intake
|
||||
description: >-
|
||||
Explains Option B hub intake for PraisonAI TypeScript/JavaScript (npm praisonai):
|
||||
accept TS issues on MervinPraison/PraisonAI, implement fixes in MervinPraison/praisonai-js,
|
||||
sync to src/praisonai-ts/. Use when routing issues, implementing TS fixes, sync workflows,
|
||||
merge-gate TS paths, or when the user mentions praisonai-js, praisonai-ts, npm SDK, or TS hub intake.
|
||||
---
|
||||
|
||||
# praisonai-js hub intake (Option B)
|
||||
|
||||
## Model in one sentence
|
||||
|
||||
**Users file TypeScript issues on [PraisonAI](https://github.com/MervinPraison/PraisonAI); fixes land in [praisonai-js](https://github.com/MervinPraison/praisonai-js); the monorepo `src/praisonai-ts/` is a sync mirror only.**
|
||||
|
||||
Do **not** ask users to re-file on praisonai-js unless they opened a duplicate on the wrong repo.
|
||||
|
||||
## Routing table
|
||||
|
||||
| Topic | Report | Fix repo | Monorepo mirror |
|
||||
|-------|--------|----------|-----------------|
|
||||
| Python SDK / CLI | PraisonAI | `src/praisonai-agents/`, `src/praisonai/` | — |
|
||||
| TypeScript / npm `praisonai` | PraisonAI (preferred) or praisonai-js | **praisonai-js** | `src/praisonai-ts/` |
|
||||
| Cross-language parity | PraisonAI | Often both Python + praisonai-js | sync after TS merge |
|
||||
| Agent-callable tools | PraisonAI | PraisonAI-Tools | — |
|
||||
| Lifecycle plugins | PraisonAI | PraisonAI-Plugins | — |
|
||||
|
||||
## End-to-end flow
|
||||
|
||||
```
|
||||
Issue on PraisonAI
|
||||
→ issue-triage: labels javascript, praisonai-js (if TS focus)
|
||||
→ claude label → Claude STEP 3-ALT clones praisonai-js
|
||||
→ PR on praisonai-js with body: Fixes MervinPraison/PraisonAI#N
|
||||
→ merge on praisonai-js (CI + merge gate there)
|
||||
→ Sync to PraisonAI Monorepo workflow on praisonai-js
|
||||
→ PR on PraisonAI: sync: update src/praisonai-ts/...
|
||||
```
|
||||
|
||||
## Agent rules
|
||||
|
||||
1. **Never implement TS features in `src/praisonai-ts/` on PraisonAI** — edit praisonai-js instead.
|
||||
2. **External PR body** must include `Fixes MervinPraison/PraisonAI#<n>` when fixing a hub issue.
|
||||
3. **After praisonai-js merge**, run sync workflow (or tell maintainer to):
|
||||
```bash
|
||||
gh workflow run "Sync to PraisonAI Monorepo" \
|
||||
--repo MervinPraison/praisonai-js \
|
||||
-f upstream_issue=<issue_number>
|
||||
```
|
||||
4. **Merge gate on PraisonAI** blocks direct `src/praisonai-ts/` changes unless sync PR (title `sync:` or body mentions praisonai-js).
|
||||
5. **Tests for TS fixes**: `npm install && npm run build && npm test` in praisonai-js clone.
|
||||
|
||||
## TS issue detection (PraisonAI triage)
|
||||
|
||||
Labels `javascript` + `praisonai-js` when issue mentions: `praisonai-js`, `praisonai-ts`, `src/praisonai-ts`, `typescript`+`praisonai`, `npm`+`praisonai` (not pypi).
|
||||
|
||||
## Key files
|
||||
|
||||
See [reference.md](reference.md) for paths in both repos.
|
||||
|
||||
## Quick commands
|
||||
|
||||
```bash
|
||||
# Sync Claude secrets to praisonai-js (from PraisonAI hub)
|
||||
gh workflow run "Sync Claude Secrets" \
|
||||
--repo MervinPraison/PraisonAI \
|
||||
-f target_repo=MervinPraison/praisonai-js
|
||||
|
||||
# Sync code praisonai-js → monorepo mirror
|
||||
gh workflow run "Sync to PraisonAI Monorepo" \
|
||||
--repo MervinPraison/praisonai-js \
|
||||
-f upstream_issue=1234
|
||||
```
|
||||
|
||||
## Related docs
|
||||
|
||||
- Monorepo: `CONTRIBUTING.md` (hub intake table)
|
||||
- praisonai-js: `AGENTS.md` §2.1.1 Hub intake
|
||||
- Security: `SECURITY.md` (npm canonical = praisonai-js)
|
||||
|
||||
## Cursor skill locations
|
||||
|
||||
| Repo | Path |
|
||||
|------|------|
|
||||
| PraisonAI monorepo | `.cursor/skills/praisonai-js-hub-intake/` |
|
||||
| praisonai-js | `.cursor/skills/praisonai-js-hub-intake/` |
|
||||
@@ -1,72 +0,0 @@
|
||||
# praisonai-js hub intake — file reference
|
||||
|
||||
## PraisonAI monorepo (`MervinPraison/PraisonAI`)
|
||||
|
||||
| File | Role |
|
||||
|------|------|
|
||||
| `.github/workflows/claude.yml` | Issue triage labels; STEP 3-ALT to praisonai-js; npm test in external flow |
|
||||
| `.github/scripts/merge-gate.js` | `tsMirrorPathReasons()` blocks non-sync edits to `src/praisonai-ts/` |
|
||||
| `.github/workflows/claude-merge-gate.yml` | Assess checklist: TS → praisonai-js |
|
||||
| `.github/scripts/ci-failure-claude.js` | CI fix guardrails include TS routing |
|
||||
| `.github/actions/claude-code-action/action.yml` | Shared Claude routing (TS → praisonai-js) |
|
||||
| `.github/praisonai-issue-triage.yaml` | `@praisonai` triage: TS-external routing |
|
||||
| `.github/workflows/auto-issue-comment.yml` | Auto-triage comment mentions praisonai-js |
|
||||
| `.github/ISSUE_TEMPLATE/bug_report.md` | Python / TS / cross-language selector |
|
||||
| `CONTRIBUTING.md` | Hub intake table |
|
||||
| `SECURITY.md` | npm canonical source = praisonai-js |
|
||||
| `src/praisonai-ts/` | **Mirror only** — do not implement features here |
|
||||
| `.cursor/skills/praisonai-js-hub-intake/` | This skill (agent reference) |
|
||||
|
||||
### Commits (Option B rollout)
|
||||
|
||||
- `4ab1ed280` — Implement Option B hub intake for praisonai-js TypeScript issues
|
||||
|
||||
## praisonai-js (`MervinPraison/praisonai-js`)
|
||||
|
||||
| File | Role |
|
||||
|------|------|
|
||||
| `.github/workflows/sync-to-praisonai.yml` | Rsync to `src/praisonai-ts/`; optional `upstream_issue` input |
|
||||
| `.github/pull_request_template.md` | `Fixes MervinPraison/PraisonAI#N` + sync checklist |
|
||||
| `.github/ISSUE_TEMPLATE/bug_report.md` | TS bug template; link to PraisonAI for cross-stack |
|
||||
| `.github/ISSUE_TEMPLATE/config.yml` | Contact links → PraisonAI for Python/cross-stack |
|
||||
| `.github/scripts/gate-config.js` | Scope + `externalRepos` hub-intake config |
|
||||
| `.github/workflows/claude.yml` | Hub caller (Claude automation) |
|
||||
| `AGENTS.md` §2.1.1 | Hub intake for agents |
|
||||
| `README.md` | Reporting issues table |
|
||||
| `.cursor/skills/praisonai-js-hub-intake/` | This skill (agent reference) |
|
||||
|
||||
### Commits
|
||||
|
||||
- `0c8cc3f` — Complete Option B reciprocal hub intake
|
||||
- `bfc5e34` — Add praisonai-js-hub-intake Cursor skill
|
||||
|
||||
## github-automation-template
|
||||
|
||||
| Item | Role |
|
||||
|------|------|
|
||||
| `install.sh --mode hub` | Thin callers on consumer repos |
|
||||
| `stacks/claude/profiles/sdk/gate-config.js.tmpl` | Base gate config (customise per repo) |
|
||||
| `AGENTS.md` | Install / rollout guide |
|
||||
|
||||
praisonai-js uses hub mode `@v1.1.0`.
|
||||
|
||||
## Decision tree for agents
|
||||
|
||||
```
|
||||
Is the issue about npm / TypeScript / praisonai-js / src/praisonai-ts?
|
||||
├─ YES → Fix in MervinPraison/praisonai-js (STEP 3-ALT)
|
||||
│ PR: Fixes MervinPraison/PraisonAI#N
|
||||
│ After merge: Sync to PraisonAI Monorepo
|
||||
└─ NO → Is it Python praisonaiagents / praisonai CLI?
|
||||
├─ YES → Fix in this monorepo
|
||||
└─ NO → Tools / Plugins / Docs external repos (see claude.yml STEP 2)
|
||||
```
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
| Wrong | Right |
|
||||
|-------|-------|
|
||||
| Edit `src/praisonai-ts/` for a new TS feature | Edit praisonai-js, then sync |
|
||||
| Tell user to re-file on praisonai-js only | Accept on PraisonAI; route fix externally |
|
||||
| Merge gate approves direct TS mirror PR without sync metadata | Title `sync:` or body references praisonai-js |
|
||||
| Skip `Fixes MervinPraison/PraisonAI#N` on external PR | Always cross-link hub issues |
|
||||
@@ -17,7 +17,6 @@ GROQ_API_KEY=gsk_... # Groq (fast inference)
|
||||
COHERE_API_KEY=... # Cohere models
|
||||
AZURE_OPENAI_API_KEY=... # Azure OpenAI
|
||||
AZURE_OPENAI_ENDPOINT=... # Azure OpenAI endpoint
|
||||
EVOLINK_API_KEY=... # EvoLink.AI OpenAI-compatible models. Get yours at https://evolink.ai/dashboard/keys
|
||||
|
||||
# === Optional: Memory backends ===
|
||||
MEM0_API_KEY=... # Mem0 memory service
|
||||
|
||||
@@ -6,11 +6,6 @@ labels: bug
|
||||
assignees: ''
|
||||
---
|
||||
|
||||
## SDK / package
|
||||
- [ ] Python (`pip install praisonai` / `praisonaiagents`)
|
||||
- [ ] TypeScript / JavaScript (`npm install praisonai`) — fixes land in [praisonai-js](https://github.com/MervinPraison/praisonai-js); you can report here or there
|
||||
- [ ] Cross-language / parity (file here on PraisonAI)
|
||||
|
||||
## Environment
|
||||
- Provider (select one):
|
||||
- [ ] Anthropic
|
||||
@@ -19,7 +14,6 @@ assignees: ''
|
||||
- [ ] AWS Bedrock
|
||||
- [ ] Other: <!-- specify -->
|
||||
- PraisonAI version: <!-- if known -->
|
||||
- Node.js version (TS/JS only): <!-- e.g. 20.x -->
|
||||
- Operating System: <!-- e.g. macOS 14.3, Windows 11, Ubuntu 22.04 -->
|
||||
|
||||
## Full Code
|
||||
@@ -37,4 +31,4 @@ assignees: ''
|
||||
<!-- What actually happened -->
|
||||
|
||||
## Additional Context
|
||||
<!-- Add any other context about the problem here, such as screenshots, logs, etc. -->
|
||||
<!-- Add any other context about the problem here, such as screenshots, logs, etc. -->
|
||||
@@ -225,10 +225,9 @@ runs:
|
||||
- CORE vs WRAPPER vs TOOLS vs PLUGINS ROUTING:
|
||||
1. Core SDK (praisonaiagents/): Only core protocols, base classes, decorators. No heavy implementations.
|
||||
2. Wrapper (praisonai/): CLI, heavy implementations, optional dependencies.
|
||||
3. TypeScript/JavaScript SDK → MervinPraison/praisonai-js: canonical npm repo. Do NOT edit src/praisonai-ts/ here.
|
||||
4. Tools → MervinPraison/PraisonAI-Tools: agent-callable integrations at runtime (Composio, Slack, APIs). Do NOT add to praisonaiagents/.
|
||||
5. Plugins → MervinPraison/PraisonAI-Plugins: lifecycle extensions (tracing, logging, hooks, guardrails). Not agent tools.
|
||||
6. Sandbox backends → PraisonAI-Plugins via `praisonai.sandbox` entry point (core protocol only).
|
||||
3. Tools → MervinPraison/PraisonAI-Tools: agent-callable integrations at runtime (Composio, Slack, APIs). Do NOT add to praisonaiagents/.
|
||||
4. Plugins → MervinPraison/PraisonAI-Plugins: lifecycle extensions (tracing, logging, hooks, guardrails). Not agent tools.
|
||||
5. Sandbox backends → PraisonAI-Plugins via `praisonai.sandbox` entry point (core protocol only).
|
||||
- Does it duplicate existing functionality? Check if Agent already supports this via existing params (reflection, planning, tools, hooks, memory).
|
||||
- Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.
|
||||
- Does it inherit from Agent properly? New agent types MUST inherit Agent, not wrap it with composition.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
name: Install PraisonAI monorepo packages
|
||||
description: Install praisonai-agents, praisonai-code, praisonai-bot, praisonai-train, praisonai-browser, praisonai-mcp, praisonai-sandbox, praisonai-deploy, and praisonai wrapper from local paths (mirrors PyPI nine-package install order).
|
||||
description: Install praisonai-agents, praisonai-code, praisonai-bot, praisonai-train, praisonai-browser, praisonai-mcp, praisonai-sandbox, and praisonai wrapper from local paths (mirrors PyPI eight-package install order).
|
||||
|
||||
inputs:
|
||||
repo-root:
|
||||
@@ -40,7 +40,6 @@ runs:
|
||||
BROWSER_PKG="${BASE}src/praisonai-browser"
|
||||
MCP_PKG="${BASE}src/praisonai-mcp"
|
||||
SANDBOX_PKG="${BASE}src/praisonai-sandbox"
|
||||
DEPLOY_PKG="${BASE}src/praisonai-deploy"
|
||||
WRAPPER_PKG="${BASE}src/praisonai"
|
||||
|
||||
normalise_extras() {
|
||||
@@ -70,8 +69,6 @@ runs:
|
||||
uv pip install --system -e .
|
||||
cd "$SANDBOX_PKG"
|
||||
uv pip install --system -e .
|
||||
cd "$DEPLOY_PKG"
|
||||
uv pip install --system -e .
|
||||
cd "$WRAPPER_PKG"
|
||||
uv pip install --system "${WRAPPER_SUFFIX}"
|
||||
else
|
||||
@@ -89,8 +86,6 @@ runs:
|
||||
pip install -e .
|
||||
cd "$SANDBOX_PKG"
|
||||
pip install -e .
|
||||
cd "$DEPLOY_PKG"
|
||||
pip install -e .
|
||||
cd "$WRAPPER_PKG"
|
||||
pip install -e "${WRAPPER_SUFFIX}"
|
||||
fi
|
||||
@@ -35,17 +35,16 @@ steps:
|
||||
Third, read architecture guidelines: execute_command 'cat src/praisonai-agents/AGENTS.md'.
|
||||
|
||||
Fourth, decide routing before planning:
|
||||
- TypeScript/JavaScript SDK → MervinPraison/praisonai-js: canonical npm repo. Do NOT edit src/praisonai-ts/ in this monorepo. Cross-link upstream issue in external PR body: Fixes MervinPraison/PraisonAI#N.
|
||||
- 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 only for protocols and CLI — external repos for Tools/Plugins.
|
||||
|
||||
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.
|
||||
- If NO (question, discussion, duplicate, invalid): say so clearly. No code changes needed.
|
||||
|
||||
Output: routing decision (Core / Wrapper / TS-external / Tools-external / Plugins-external / No-change), validation result, and exact files/lines to change.
|
||||
Output: routing decision (Core / Wrapper / Tools-external / Plugins-external / No-change), validation result, and exact files/lines to change.
|
||||
expected_output: A decision on whether code changes are needed, and if so a concrete file-level plan.
|
||||
|
||||
- name: Implement Fix
|
||||
|
||||
@@ -157,7 +157,6 @@ function buildCiFixComment({ headSha, failedChecks, failureSummaries }) {
|
||||
'3. **Pre-existing flake or unrelated failure** — say so explicitly; prefer fixing the root cause over masking it.',
|
||||
'',
|
||||
'**SDK guardrails (AGENTS.md):**',
|
||||
'- TypeScript/JavaScript SDK → MervinPraison/praisonai-js (not src/praisonai-ts/ in this monorepo).',
|
||||
'- Agent-callable tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins; sandbox backends → PraisonAI-Plugins (`praisonai.sandbox`) — not praisonaiagents/.',
|
||||
'- Do not disturb core SDK contracts to accommodate a wrapper/feature change.',
|
||||
'- Tests must continue to guard backward compatibility and hot-path behaviour — passing CI by lowering test standards is not acceptable.',
|
||||
|
||||
@@ -74,11 +74,7 @@ function isClaudeTriggerNoise(c) {
|
||||
|
||||
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;
|
||||
if (!login.includes('praisonai-triage')) return false;
|
||||
return (c.body || '').includes('Claude finished');
|
||||
}
|
||||
|
||||
@@ -100,47 +96,15 @@ function isConflictRebaseTriggerComment(c) {
|
||||
|
||||
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;
|
||||
if (!login.includes('praisonai-triage') && !login.includes('github-actions')) 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;
|
||||
@@ -281,9 +245,6 @@ function shouldSkipStaleFinalRecovery(comments, headPushedAt, headPusherLogin =
|
||||
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,
|
||||
@@ -308,7 +269,7 @@ function finalClaudeCompletedOnSha(comments, headPushedAt) {
|
||||
}
|
||||
|
||||
const FINAL_CLAUDE_REVIEW_BODY =
|
||||
'@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify src/praisonai-rust or src/praisonai-ts in this repo — TypeScript SDK work belongs in MervinPraison/praisonai-js. 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\n4. SDK value: review in depth whether the change genuinely adds value to the SDK — never add features for the sake of adding them. It must strengthen the SDK (simpler, more user-friendly, robust, world-class, secure). If it does not clearly add value, request changes or recommend rejecting/closing rather than merging scope creep\n5. Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.\n6. Repo routing: TypeScript/JavaScript SDK → praisonai-js (not src/praisonai-ts/ here); agent-callable tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins; optional sandbox backends → PraisonAI-Plugins (`praisonai.sandbox` entry point) — request changes if wrongly added to praisonaiagents/\n\n**Phase 2: FIX Valid Issues**\n7. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n8. Also independently identify and fix any gaps or issues you find in the changed code — do not rely only on prior reviewer feedback\n9. Push all code fixes directly to THIS branch (do NOT create a new PR)\n10. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n11. If all issues are resolved, approve the PR / close the Issue\n12. If blocking issues remain, request changes / leave clear action items';
|
||||
'@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify praisonai-rust or praisonai-ts. 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\n4. SDK value: review in depth whether the change genuinely adds value to the SDK — never add features for the sake of adding them. It must strengthen the SDK (simpler, more user-friendly, robust, world-class, secure). If it does not clearly add value, request changes or recommend rejecting/closing rather than merging scope creep\n5. Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.\n6. Repo routing: agent-callable tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins; optional sandbox backends → PraisonAI-Plugins (`praisonai.sandbox` entry point) — request changes if wrongly added to praisonaiagents/\n\n**Phase 2: FIX Valid Issues**\n7. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n8. Also independently identify and fix any gaps or issues you find in the changed code — do not rely only on prior reviewer feedback\n9. Push all code fixes directly to THIS branch (do NOT create a new PR)\n10. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n11. If all issues are resolved, approve the PR / close the Issue\n12. If blocking issues remain, request changes / leave clear action items';
|
||||
|
||||
async function getMergeState(github, owner, repo, prNumber) {
|
||||
const query = `
|
||||
@@ -600,24 +561,6 @@ function hasManualOnlyLabel(labels) {
|
||||
return labels.some((l) => MANUAL_ONLY_LABELS.has(l));
|
||||
}
|
||||
|
||||
const TS_MIRROR_PREFIX = 'src/praisonai-ts/';
|
||||
|
||||
function tsMirrorPathReasons(files, pr) {
|
||||
const touchesTs = files.some((f) => f.filename.startsWith(TS_MIRROR_PREFIX));
|
||||
if (!touchesTs) return [];
|
||||
const title = (pr.title || '').toLowerCase();
|
||||
const body = (pr.body || '').toLowerCase();
|
||||
const isSyncPr =
|
||||
title.startsWith('sync:') ||
|
||||
body.includes('sync from praisonai-js') ||
|
||||
body.includes('praisonai-js') ||
|
||||
body.includes('mervinpraison/praisonai-js');
|
||||
if (isSyncPr) return [];
|
||||
return [
|
||||
'src/praisonai-ts/ changed outside praisonai-js sync — implement in MervinPraison/praisonai-js, then run Sync to PraisonAI Monorepo workflow',
|
||||
];
|
||||
}
|
||||
|
||||
function sensitivePathReasons(files, labels = []) {
|
||||
if (labels.includes(WORKFLOW_ONLY_LABEL) && isCiOnlyChange(files)) {
|
||||
return [];
|
||||
@@ -841,7 +784,6 @@ async function evaluatePipelineQuiescent(github, owner, repo, prNumber, core, op
|
||||
if (agentManual) reasons.push(agentManual);
|
||||
|
||||
reasons.push(...sensitivePathReasons(pullFiles, ctx.labels));
|
||||
reasons.push(...tsMirrorPathReasons(pullFiles, ctx.pr));
|
||||
reasons.push(...prSizeReasons(pullFiles));
|
||||
reasons.push(...secretScanReasons(pullFiles));
|
||||
|
||||
@@ -974,7 +916,6 @@ module.exports = {
|
||||
hasRecentConflictComment,
|
||||
isConflictRebaseTriggerComment,
|
||||
isConflictRebaseCompletionComment,
|
||||
needsFinalReReviewAfterConflictRebase,
|
||||
conflictRebaseQuiescent,
|
||||
hasHumanChangesRequested,
|
||||
hasAnyChangesRequested,
|
||||
@@ -1008,7 +949,6 @@ module.exports = {
|
||||
touchesSdk,
|
||||
hasManualOnlyLabel,
|
||||
sensitivePathReasons,
|
||||
tsMirrorPathReasons,
|
||||
prSizeReasons,
|
||||
missingTestsReason,
|
||||
secretScanReasons,
|
||||
|
||||
@@ -11,112 +11,47 @@ assert.ok(versions.currentCode);
|
||||
assert.ok(versions.currentWrapper);
|
||||
assert.ok(versions.targetCode);
|
||||
assert.ok(rg.PACKAGE_PATHS.includes('src/praisonai-code'));
|
||||
// Every released package must make the gate's path-change check eligible.
|
||||
for (const p of [
|
||||
'src/praisonai', 'src/praisonai-agents', 'src/praisonai-code',
|
||||
'src/praisonai-bot', 'src/praisonai-train', 'src/praisonai-browser',
|
||||
'src/praisonai-mcp', 'src/praisonai-sandbox', 'src/praisonai-deploy',
|
||||
]) {
|
||||
assert.ok(rg.PACKAGE_PATHS.includes(p), `PACKAGE_PATHS missing ${p}`);
|
||||
}
|
||||
|
||||
const noonUtc = new Date('2026-07-08T12:00:00Z');
|
||||
const dayStart = rg.utcDayStart(noonUtc);
|
||||
assert.strictEqual(dayStart.toISOString(), '2026-07-08T00:00:00.000Z');
|
||||
|
||||
function mockGithub({ runs = [], releases = [] } = {}) {
|
||||
return {
|
||||
rest: {
|
||||
actions: {
|
||||
listWorkflowRuns: async () => ({ data: { workflow_runs: runs } }),
|
||||
},
|
||||
repos: {
|
||||
listReleases: async () => ({ data: releases }),
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
(async () => {
|
||||
assert.strictEqual(await rg.pypiVersionExists('praisonaiagents', '0.0.0'), false);
|
||||
|
||||
assert.strictEqual(rg.PATCH_RELEASE_INTERVAL_DAYS, 3);
|
||||
|
||||
// Dedupe is release-based: a v* release inside the window blocks…
|
||||
const recentRelease = mockGithub({
|
||||
releases: [{ tag_name: 'v4.6.159', published_at: '2026-07-08T09:00:00Z' }],
|
||||
});
|
||||
const mockGithub = {
|
||||
rest: {
|
||||
actions: {
|
||||
listWorkflowRuns: async () => ({
|
||||
data: {
|
||||
workflow_runs: [
|
||||
{
|
||||
conclusion: 'success',
|
||||
created_at: '2026-07-08T09:00:00Z',
|
||||
status: 'completed',
|
||||
},
|
||||
],
|
||||
},
|
||||
}),
|
||||
},
|
||||
},
|
||||
};
|
||||
assert.strictEqual(
|
||||
await rg.hasSuccessfulReleaseWithinDays(recentRelease, 'o', 'r', noonUtc),
|
||||
await rg.hasSuccessfulReleaseToday(mockGithub, 'o', 'r', noonUtc),
|
||||
true
|
||||
);
|
||||
|
||||
const result = await rg.evaluateReleasePreflight(
|
||||
recentRelease, 'o', 'r',
|
||||
mockGithub, 'o', 'r',
|
||||
{ headSha: 'abc', isCiTrigger: false, bump: 'patch', now: noonUtc },
|
||||
null
|
||||
);
|
||||
assert.ok(result.reasons.some((r) => r.includes('every 3 days')));
|
||||
|
||||
// …an old release does not…
|
||||
const oldRelease = mockGithub({
|
||||
releases: [{ tag_name: 'v4.6.150', published_at: '2026-07-04T09:00:00Z' }],
|
||||
});
|
||||
assert.strictEqual(
|
||||
await rg.hasSuccessfulReleaseWithinDays(oldRelease, 'o', 'r', noonUtc),
|
||||
false
|
||||
);
|
||||
|
||||
// …and a dry-run "success" (workflow run, no release) does not consume the
|
||||
// window: only real releases count.
|
||||
const dryRunOnly = mockGithub({
|
||||
runs: [{ conclusion: 'success', created_at: '2026-07-08T09:00:00Z', status: 'completed' }],
|
||||
releases: [],
|
||||
});
|
||||
assert.strictEqual(
|
||||
await rg.hasSuccessfulReleaseWithinDays(dryRunOnly, 'o', 'r', noonUtc),
|
||||
false
|
||||
);
|
||||
|
||||
// Active-run blocking: fresh waiting run blocks…
|
||||
const freshWaiting = mockGithub({
|
||||
runs: [{ status: 'waiting', conclusion: null, created_at: '2026-07-08T11:00:00Z', html_url: 'x' }],
|
||||
});
|
||||
assert.strictEqual(
|
||||
await rg.hasActiveReleaseRun(freshWaiting, 'o', 'r', noonUtc, null),
|
||||
true
|
||||
);
|
||||
|
||||
// …a waiting run stuck longer than STALE_WAITING_HOURS no longer blocks…
|
||||
const staleWaiting = mockGithub({
|
||||
runs: [{ status: 'waiting', conclusion: null, created_at: '2026-07-08T01:00:00Z', html_url: 'x' }],
|
||||
});
|
||||
const warnings = [];
|
||||
const fakeCore = { warning: (m) => warnings.push(m), info: () => {} };
|
||||
assert.strictEqual(rg.STALE_WAITING_HOURS, 6);
|
||||
assert.strictEqual(
|
||||
await rg.hasActiveReleaseRun(staleWaiting, 'o', 'r', noonUtc, fakeCore),
|
||||
false
|
||||
);
|
||||
assert.ok(warnings.length === 1 && warnings[0].includes('approve or cancel'));
|
||||
|
||||
// …but an in_progress run always blocks regardless of age.
|
||||
const oldInProgress = mockGithub({
|
||||
runs: [{ status: 'in_progress', conclusion: null, created_at: '2026-07-07T01:00:00Z', html_url: 'x' }],
|
||||
});
|
||||
assert.strictEqual(
|
||||
await rg.hasActiveReleaseRun(oldInProgress, 'o', 'r', noonUtc, null),
|
||||
true
|
||||
);
|
||||
assert.ok(result.reasons.some((r) => r.includes('already released today')));
|
||||
|
||||
console.log('ok: bumpPatch');
|
||||
console.log('ok: readVersionsFromTree');
|
||||
console.log('ok: PACKAGE_PATHS covers all 9 released packages');
|
||||
console.log('ok: pypiVersionExists missing version');
|
||||
console.log('ok: utcDayStart');
|
||||
console.log('ok: release-based dedupe (recent blocks, old does not)');
|
||||
console.log('ok: dry-run success does not consume the release window');
|
||||
console.log('ok: 3-day dedupe blocks second release');
|
||||
console.log('ok: fresh waiting run blocks; stale waiting run ignored with warning');
|
||||
console.log('ok: in_progress always blocks');
|
||||
console.log('ok: hasSuccessfulReleaseToday');
|
||||
console.log('ok: daily dedupe blocks second release');
|
||||
})();
|
||||
+20
-105
@@ -4,31 +4,10 @@
|
||||
|
||||
const https = require('https');
|
||||
|
||||
/** Every directory whose changes should make a release eligible — all nine
|
||||
* published packages (mirrors the skip_* inputs in pypi-release.yml). */
|
||||
const PACKAGE_PATHS = [
|
||||
'src/praisonai',
|
||||
'src/praisonai-agents',
|
||||
'src/praisonai-code',
|
||||
'src/praisonai-bot',
|
||||
'src/praisonai-train',
|
||||
'src/praisonai-browser',
|
||||
'src/praisonai-mcp',
|
||||
'src/praisonai-sandbox',
|
||||
'src/praisonai-deploy',
|
||||
];
|
||||
/** Minimum days between successful patch auto-releases. */
|
||||
const PATCH_RELEASE_INTERVAL_DAYS = 3;
|
||||
const PACKAGE_PATHS = ['src/praisonai', 'src/praisonai-agents', 'src/praisonai-code'];
|
||||
const ACTIVE_RELEASE_STATUSES = new Set([
|
||||
'queued', 'in_progress', 'waiting', 'pending', 'requested',
|
||||
]);
|
||||
/** A run stuck in `waiting` (environment approval) longer than this no longer
|
||||
* blocks the gate. GitHub only auto-fails unapproved deployments after 30
|
||||
* days, so without a cutoff one forgotten manual dispatch stalls all
|
||||
* auto-releases for up to a month. The run is warned about, never cancelled —
|
||||
* if later approved, the pypi-release concurrency group serializes it and its
|
||||
* pypi_exists checks no-op anything already published. */
|
||||
const STALE_WAITING_HOURS = 6;
|
||||
|
||||
function bumpPatch(version) {
|
||||
const parts = version.split('.');
|
||||
@@ -84,65 +63,36 @@ function pypiVersionExists(packageName, version) {
|
||||
});
|
||||
}
|
||||
|
||||
async function hasActiveReleaseRun(github, owner, repo, now = new Date(), core = null) {
|
||||
async function hasActiveReleaseRun(github, owner, repo) {
|
||||
const runs = await github.rest.actions.listWorkflowRuns({
|
||||
owner,
|
||||
repo,
|
||||
workflow_id: 'pypi-release.yml',
|
||||
per_page: 20,
|
||||
});
|
||||
const staleCutoff = now.getTime() - STALE_WAITING_HOURS * 60 * 60 * 1000;
|
||||
return runs.data.workflow_runs.some((r) => {
|
||||
if (!ACTIVE_RELEASE_STATUSES.has(r.status) || r.conclusion) return false;
|
||||
if (r.status === 'waiting' && new Date(r.created_at).getTime() < staleCutoff) {
|
||||
if (core) {
|
||||
core.warning(
|
||||
`Ignoring release run waiting >${STALE_WAITING_HOURS}h for environment approval: `
|
||||
+ `${r.html_url} — approve or cancel it. It no longer blocks auto-releases.`
|
||||
);
|
||||
}
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
});
|
||||
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()));
|
||||
}
|
||||
|
||||
function releaseIntervalStart(now = new Date(), intervalDays = PATCH_RELEASE_INTERVAL_DAYS) {
|
||||
return new Date(now.getTime() - intervalDays * 24 * 60 * 60 * 1000);
|
||||
}
|
||||
|
||||
async function hasSuccessfulReleaseWithinDays(
|
||||
github,
|
||||
owner,
|
||||
repo,
|
||||
now = new Date(),
|
||||
intervalDays = PATCH_RELEASE_INTERVAL_DAYS,
|
||||
) {
|
||||
const windowStart = releaseIntervalStart(now, intervalDays);
|
||||
// Dedupe on GitHub releases (v* tags) rather than run conclusions: a
|
||||
// dry_run=true dispatch concludes 'success' without publishing anything and
|
||||
// must not consume the release window. Only a real full release creates a
|
||||
// v* GitHub release (bump_and_release.py's `gh release create`).
|
||||
const releases = await github.rest.repos.listReleases({
|
||||
async function hasSuccessfulReleaseToday(github, owner, repo, now = new Date()) {
|
||||
const dayStart = utcDayStart(now);
|
||||
const runs = await github.rest.actions.listWorkflowRuns({
|
||||
owner,
|
||||
repo,
|
||||
per_page: 10,
|
||||
workflow_id: 'pypi-release.yml',
|
||||
status: 'completed',
|
||||
per_page: 30,
|
||||
});
|
||||
return releases.data.some(
|
||||
(r) => r.tag_name && r.tag_name.startsWith('v')
|
||||
&& new Date(r.published_at || r.created_at) >= windowStart
|
||||
return runs.data.workflow_runs.some(
|
||||
(r) => r.conclusion === 'success' && new Date(r.created_at) >= dayStart
|
||||
);
|
||||
}
|
||||
|
||||
/** @deprecated Use hasSuccessfulReleaseWithinDays — kept for selftests. */
|
||||
async function hasSuccessfulReleaseToday(github, owner, repo, now = new Date()) {
|
||||
return hasSuccessfulReleaseWithinDays(github, owner, repo, now, 1);
|
||||
}
|
||||
|
||||
async function lastGreenCoreTestsSha(github, owner, repo) {
|
||||
const runs = await github.rest.actions.listWorkflowRuns({
|
||||
owner,
|
||||
@@ -179,18 +129,15 @@ async function evaluateReleasePreflight(github, owner, repo, options, core) {
|
||||
return out;
|
||||
}
|
||||
|
||||
const referenceTime = options.now instanceof Date ? options.now : new Date();
|
||||
|
||||
if (await hasActiveReleaseRun(github, owner, repo, referenceTime, core)) {
|
||||
if (await hasActiveReleaseRun(github, owner, repo)) {
|
||||
reasons.push('PyPI Release already in progress or awaiting approval');
|
||||
return out;
|
||||
}
|
||||
|
||||
if (await hasSuccessfulReleaseWithinDays(github, owner, repo, referenceTime)) {
|
||||
reasons.push(
|
||||
`already released within last ${PATCH_RELEASE_INTERVAL_DAYS} days; `
|
||||
+ `max one patch release every ${PATCH_RELEASE_INTERVAL_DAYS} days`
|
||||
);
|
||||
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;
|
||||
}
|
||||
|
||||
@@ -260,35 +207,8 @@ async function evaluateReleasePreflight(github, owner, repo, options, core) {
|
||||
out.headSha = evalSha;
|
||||
const greenSha = await lastGreenCoreTestsSha(github, owner, repo);
|
||||
if (greenSha !== evalSha) {
|
||||
// Core Tests has path filters and honors [skip ci] (the release
|
||||
// safety-net commit uses it), so the tip of main may legitimately have
|
||||
// no Core Tests run of its own — e.g. a docs-only commit, or the
|
||||
// "chore(release): … [skip ci]" commit right after a release. Accept a
|
||||
// green ancestor when nothing under the released package paths changed
|
||||
// after it; otherwise the cron path stalls until the next src/** push.
|
||||
let greenAncestorOk = false;
|
||||
if (greenSha && /^[0-9a-f]{40}$/.test(greenSha)) {
|
||||
try {
|
||||
execSync(`git merge-base --is-ancestor ${greenSha} ${evalSha}`);
|
||||
const delta = execSync(
|
||||
`git diff --name-only ${greenSha} ${evalSha} -- ${PACKAGE_PATHS.join(' ')}`,
|
||||
{ encoding: 'utf8' }
|
||||
).trim();
|
||||
greenAncestorOk = delta === '';
|
||||
} catch {
|
||||
greenAncestorOk = false;
|
||||
}
|
||||
}
|
||||
if (!greenAncestorOk) {
|
||||
reasons.push(`CI not green on HEAD (last green: ${greenSha ? greenSha.slice(0, 7) : 'none'})`);
|
||||
return out;
|
||||
}
|
||||
if (core) {
|
||||
core.info(
|
||||
`HEAD ${evalSha.slice(0, 7)} has no Core Tests run; accepting green ancestor `
|
||||
+ `${greenSha.slice(0, 7)} (no package-path changes since).`
|
||||
);
|
||||
}
|
||||
reasons.push(`CI not green on HEAD (last green: ${greenSha ? greenSha.slice(0, 7) : 'none'})`);
|
||||
return out;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -302,11 +222,6 @@ module.exports = {
|
||||
bumpPatch,
|
||||
readVersionsFromTree,
|
||||
pypiVersionExists,
|
||||
PATCH_RELEASE_INTERVAL_DAYS,
|
||||
STALE_WAITING_HOURS,
|
||||
releaseIntervalStart,
|
||||
hasActiveReleaseRun,
|
||||
hasSuccessfulReleaseWithinDays,
|
||||
hasSuccessfulReleaseToday,
|
||||
utcDayStart,
|
||||
evaluateReleasePreflight,
|
||||
|
||||
@@ -42,5 +42,5 @@ jobs:
|
||||
issue_number: context.issue.number,
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
body: '🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...\n\nClaude will:\n1. Route correctly: TypeScript/JavaScript SDK → praisonai-js; agent tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins\n2. Search codebase for root cause\n3. Implement a minimal fix following AGENTS.md\n4. Create a PR with the changes (external repo PRs link back to this issue)'
|
||||
body: '🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...\n\nClaude will:\n1. Route correctly: agent tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins\n2. Search codebase for root cause\n3. Implement a minimal fix following AGENTS.md\n4. Create a PR with the changes'
|
||||
});
|
||||
@@ -289,7 +289,7 @@ jobs:
|
||||
1. Read AGENTS.md and the PR diff on the current branch.
|
||||
2. Read all PR comments and reviews (FINAL architecture reviewer / Lead Engineer must have run).
|
||||
3. Confirm SDK value gate: change strengthens praisonaiagents (no scope creep). The aim is a LIGHTWEIGHT AND POWERFUL package — BLOCK changes that add params/modules/exports duplicating existing Agent capabilities (instructions/backstory/tools/hooks/memory), or add knobs/fields with no live consumer, i.e. scope creep for the sake of it.
|
||||
4. Repo routing: BLOCK if TypeScript/JavaScript SDK changes in src/praisonai-ts/ (→ praisonai-js + sync workflow); agent-callable tools (→ PraisonAI-Tools); lifecycle plugins (→ PraisonAI-Plugins); or optional sandbox backends (→ PraisonAI-Plugins via `praisonai.sandbox`) were added to praisonaiagents/ instead of the external repo.
|
||||
4. Repo routing: BLOCK if agent-callable tools (→ PraisonAI-Tools), lifecycle plugins (→ PraisonAI-Plugins), or optional sandbox backends (→ PraisonAI-Plugins via `praisonai.sandbox`) were added to praisonaiagents/ instead of the external repo.
|
||||
5. Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.
|
||||
6. If agent.py adds >100 lines or new Agent __init__ params, respond MERGE_GATE_VERDICT: BLOCK (manual review required).
|
||||
7. BLOCK if labels security/breaking-change/needs-manual-review/release, sensitive paths (.github/workflows, auth, pyproject.toml), secrets in diff, PR >800 lines or >30 files, or SDK changes without tests. Label `merge-gate-ci-only` exempts CI-only changes under `.github/workflows/`, `.github/actions/`, or merge-gate scripts.
|
||||
|
||||
@@ -70,21 +70,9 @@ jobs:
|
||||
if (content.includes('documentation') || content.includes('docs')) {
|
||||
labels.push('documentation');
|
||||
}
|
||||
const isPraisonaiJsFocus =
|
||||
content.includes('praisonai-js') ||
|
||||
content.includes('praisonai-ts') ||
|
||||
content.includes('src/praisonai-ts') ||
|
||||
content.includes('typescript sdk') ||
|
||||
content.includes('javascript sdk') ||
|
||||
(content.includes('typescript') && content.includes('praisonai')) ||
|
||||
(content.includes('javascript') && content.includes('praisonai')) ||
|
||||
(content.includes('npm') && content.includes('praisonai') && !content.includes('pypi'));
|
||||
if (isPraisonaiJsFocus || content.includes('typescript') || content.includes('javascript') || content.includes('npm')) {
|
||||
if (content.includes('typescript') || content.includes('javascript') || content.includes('npm')) {
|
||||
labels.push('javascript');
|
||||
}
|
||||
if (isPraisonaiJsFocus) {
|
||||
labels.push('praisonai-js');
|
||||
}
|
||||
|
||||
// Apply labels
|
||||
if (labels.length > 0) {
|
||||
@@ -112,7 +100,7 @@ jobs:
|
||||
'',
|
||||
'_Bug and enhancement reports are auto-triaged with Claude. Questions and other issues: a maintainer can comment `@claude` to trigger analysis._',
|
||||
'',
|
||||
'**Routing:** TypeScript/JavaScript SDK → [praisonai-js](https://github.com/MervinPraison/praisonai-js) (canonical; monorepo `src/praisonai-ts/` is synced from there). Agent-callable tools → [PraisonAI-Tools](https://github.com/MervinPraison/PraisonAI-Tools); lifecycle plugins (tracing/hooks/guardrails) → [PraisonAI-Plugins](https://github.com/MervinPraison/PraisonAI-Plugins).'
|
||||
'**Routing:** Agent-callable tools → [PraisonAI-Tools](https://github.com/MervinPraison/PraisonAI-Tools); lifecycle plugins (tracing/hooks/guardrails) → [PraisonAI-Plugins](https://github.com/MervinPraison/PraisonAI-Plugins).'
|
||||
].join('\n')
|
||||
});
|
||||
}
|
||||
@@ -305,7 +293,7 @@ jobs:
|
||||
|
||||
STEP 1 — READ GUIDELINES:
|
||||
Read AGENTS.md to understand the architecture rules.
|
||||
SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify praisonai-rust or src/praisonai-ts in this repo — TypeScript/JavaScript SDK work belongs in MervinPraison/praisonai-js (STEP 3-ALT).
|
||||
SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify or touch praisonai-rust or praisonai-ts packages.
|
||||
AIM: This package must stay LIGHTWEIGHT AND POWERFUL. Do a CRITICAL REVIEW at each stage (issue triage, fix planning, PR review/implementation) and reject scope creep for the sake of adding features. Prefer existing Agent capabilities (instructions/backstory/tools/hooks/memory) over new params/modules/exports. Even when fixing a raised issue, keep the fix minimal and lightweight — do NOT expand the surface area or add knobs with no live consumer.
|
||||
|
||||
STEP 2 — ARCHITECTURE VALIDATION & ROUTING (MANDATORY before writing code):
|
||||
@@ -317,8 +305,7 @@ jobs:
|
||||
4. Documentation (PraisonAIDocs): Documentation pages, guides, API references.
|
||||
5. Plugins → MervinPraison/PraisonAI-Plugins: framework lifecycle extensions (tracing, logging, metrics, hooks, guardrails). Not agent tools — use STEP 3-ALT.
|
||||
6. Sandbox backends (optional/niche, e.g. Capsule) → PraisonAI-Plugins via `praisonai.sandbox` entry point; core keeps protocol/config/manager only.
|
||||
7. TypeScript/JavaScript SDK → MervinPraison/praisonai-js: canonical npm SDK repo. Do NOT implement in src/praisonai-ts/ here — clone praisonai-js and use STEP 3-ALT. After merge there, run **Sync to PraisonAI Monorepo** workflow to update src/praisonai-ts/.
|
||||
For items routed to an EXTERNAL repository (Tools, Docs, Plugins, praisonai-js), follow STEP 3-ALT below.
|
||||
For items routed to an EXTERNAL repository (Tools, Docs, Plugins), follow STEP 3-ALT below.
|
||||
- Does it duplicate existing functionality? Check if Agent already supports this via existing params (reflection, planning, tools, hooks, memory). If it does, reject the change as scope creep and prefer the existing capability — the aim is lightweight and powerful, not more knobs.
|
||||
- Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.
|
||||
- Does it inherit from Agent properly? New agent types MUST inherit Agent, not wrap it with composition.
|
||||
@@ -331,7 +318,7 @@ jobs:
|
||||
${{ steps.check_fork.outputs.is_pr == 'true' && (steps.check_fork.outputs.is_fork != 'true' || steps.check_fork.outputs.can_push_fork == 'true') && steps.check_fork.outputs.merge_state != 'DIRTY' && format('STEP 3 — IMPLEMENT ON EXISTING PR (branch: {0}, PR #{1}{2}):\n- DO NOT create a new branch or PR\n- git checkout {0}\n- Implement minimal, focused fixes from reviewer feedback\n- Follow protocol-driven design: protocols in core SDK, heavy implementations in wrapper\n- Keep changes small and backward-compatible\n- Commit: git add -A && git commit -m "fix: <description>"\n- Push: git push origin {0}\n- Comment a summary of exact files modified and what you skipped\n', steps.check_fork.outputs.pr_branch, steps.check_fork.outputs.pr_number, steps.check_fork.outputs.can_push_fork == 'true' && format(', fork: {0}', steps.check_fork.outputs.fork_repo) || '') || '' }}
|
||||
${{ steps.check_fork.outputs.is_pr != 'true' && 'STEP 3 — IMPLEMENT (for changes in THIS repo — PraisonAI):\n- Create a fix branch: git checkout -b claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d)\n- Implement a minimal, focused fix\n- Follow protocol-driven design: protocols in core SDK, heavy implementations in wrapper\n- Keep changes small and backward-compatible\n- Commit: git add -A && git commit -m "fix: <description> (fixes #$ISSUE_NUMBER)"\n- Push: git push origin claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d)\nCRITICAL: After pushing, you MUST immediately run: gh pr create --title "fix: <title>" --body "Fixes #$ISSUE_NUMBER" --head claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d)\nDo NOT stop after pushing. Do NOT say "manually create a PR". Always create the PR automatically.\n' || '' }}
|
||||
|
||||
STEP 3-ALT — IMPLEMENT IN EXTERNAL REPO (for PraisonAI-Tools, PraisonAIDocs, PraisonAI-Plugins, praisonai-js):
|
||||
STEP 3-ALT — IMPLEMENT IN EXTERNAL REPO (for PraisonAI-Tools, PraisonAIDocs, PraisonAI-Plugins):
|
||||
When work must happen in a different repository, follow these steps EXACTLY. Do NOT attempt to use `cd`, as directory state is not preserved. Use `git -C` for all commands.
|
||||
a) Clone the repository:
|
||||
gh repo clone MervinPraison/<REPO_NAME> /tmp/<REPO_NAME>
|
||||
@@ -349,11 +336,9 @@ jobs:
|
||||
gh pr create -R MervinPraison/<REPO_NAME> --head claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d) --title "feat: <title>" --body "Fixes MervinPraison/PraisonAI#$ISSUE_NUMBER
|
||||
|
||||
<body>"
|
||||
h) Comment on THIS PraisonAI issue with the external PR URL. For praisonai-js: note that after merge, a maintainer runs **Sync to PraisonAI Monorepo** on praisonai-js (Actions → sync workflow) to update src/praisonai-ts/.
|
||||
|
||||
STEP 4 — TEST:
|
||||
- For SDK changes: cd src/praisonai-agents && PYTHONPATH=. python -m pytest tests/ -x -q --timeout=30
|
||||
- For praisonai-js: cd /tmp/praisonai-js && npm install && npm run build && npm test
|
||||
- For docs changes: verify files exist and are valid markdown/MDX
|
||||
- Ensure no regressions
|
||||
|
||||
@@ -366,8 +351,6 @@ jobs:
|
||||
Bash(conda:*)
|
||||
Bash(pytest:*)
|
||||
Bash(gh:*)
|
||||
Bash(npm:*)
|
||||
Bash(node:*)
|
||||
Bash(python -m pytest:*)
|
||||
Bash(python -m pip:*)
|
||||
Bash(poetry:*)
|
||||
|
||||
@@ -1,183 +0,0 @@
|
||||
# Build the desktop app for macOS, Windows and Linux, and attach it to the
|
||||
# release.
|
||||
#
|
||||
# Releases carried no assets at all -- v4.7.1 shipped zero -- so there was
|
||||
# nothing for anyone to download. The macOS half of this shipped first; this
|
||||
# adds the other two, which were not merely missing from CI but impossible:
|
||||
# the bundle targets were `["app", "dmg"]`, both macOS-only, so a Windows or
|
||||
# Linux build produced zero artifacts and still exited zero.
|
||||
#
|
||||
# Unsigned, deliberately, on every platform. macOS signing needs a Developer ID
|
||||
# and Windows signing now needs a hardware-backed certificate or a hosted
|
||||
# signing service -- neither is in secrets. Shipping builds people can open
|
||||
# past the warning is better than shipping none, and the release notes say so
|
||||
# rather than letting Gatekeeper and SmartScreen say it for us.
|
||||
name: Desktop release
|
||||
|
||||
on:
|
||||
release:
|
||||
types: [published]
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
tag:
|
||||
description: 'Existing release tag to attach the build to'
|
||||
required: true
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
concurrency:
|
||||
# Queue rather than cancel: a cancelled release build looks identical to a
|
||||
# release that simply never produced assets, which is the bug being fixed.
|
||||
group: desktop-release-${{ github.event.release.tag_name || inputs.tag }}
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
build:
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
# macos-15, not macos-14: that image entered deprecation on
|
||||
# 2026-07-06 and is fully unsupported from 2026-11-02, with brownout
|
||||
# periods failing jobs before then. This is the only Apple-silicon
|
||||
# leg, so losing it means no arm64 DMG at all.
|
||||
- runner: macos-15 # Apple silicon
|
||||
target: aarch64-apple-darwin
|
||||
bundles: dmg
|
||||
ext: dmg
|
||||
asset: macos-apple-silicon
|
||||
# macos-15-intel, not macos-13: that image was retired on
|
||||
# 2025-12-04, so the leg would never schedule and the verify job
|
||||
# below would correctly report a missing asset on every release,
|
||||
# forever. macos-15-intel is GitHub's named x86_64 replacement.
|
||||
- runner: macos-15-intel # Intel
|
||||
target: x86_64-apple-darwin
|
||||
bundles: dmg
|
||||
ext: dmg
|
||||
asset: macos-intel
|
||||
- runner: windows-latest
|
||||
target: x86_64-pc-windows-msvc
|
||||
bundles: nsis
|
||||
ext: exe
|
||||
asset: windows-x64-setup
|
||||
# ubuntu-22.04 rather than -latest on purpose: glibc is forward
|
||||
# compatible only, so the build host sets the *oldest* distribution
|
||||
# the .deb can run on. Building on 24.04 would produce a package that
|
||||
# refuses to start on 22.04 and Debian 12 with a "GLIBC_2.38 not
|
||||
# found" that no runtime flag can fix.
|
||||
#
|
||||
# This image begins deprecation on 2026-09-17 and is retired on
|
||||
# 2027-04-17. When it goes, move to `ubuntu-latest` with
|
||||
# `container: debian:12` rather than bumping the runner -- that keeps
|
||||
# the glibc floor decided by us instead of by GitHub's image
|
||||
# lifecycle.
|
||||
- runner: ubuntu-22.04
|
||||
target: x86_64-unknown-linux-gnu
|
||||
bundles: deb
|
||||
ext: deb
|
||||
asset: linux-x64
|
||||
runs-on: ${{ matrix.runner }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install the Linux build dependencies
|
||||
if: runner.os == 'Linux'
|
||||
run: |
|
||||
set -euo pipefail
|
||||
# Retried: a degraded mirror otherwise burns the whole job and
|
||||
# reports "cancelled", which reads as our failure rather than apt's.
|
||||
for attempt in 1 2 3; do
|
||||
sudo apt-get update && break || sleep 15
|
||||
done
|
||||
sudo apt-get install -y --no-install-recommends \
|
||||
libwebkit2gtk-4.1-dev \
|
||||
libappindicator3-dev \
|
||||
librsvg2-dev \
|
||||
libxdo-dev \
|
||||
libssl-dev \
|
||||
patchelf \
|
||||
xdg-utils
|
||||
# libappindicator3-dev, not the ayatana package: the .deb's generated
|
||||
# Depends: follows whichever one the binary linked against, so the
|
||||
# two must not be mixed between builds.
|
||||
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
targets: ${{ matrix.target }}
|
||||
|
||||
- uses: swatinem/rust-cache@v2
|
||||
with:
|
||||
workspaces: src/praisonai-desktop/src-tauri -> target
|
||||
# Saving the Windows target directory costs more minutes than the
|
||||
# rebuild it saves.
|
||||
save-if: ${{ runner.os != 'Windows' }}
|
||||
|
||||
- name: Install the Tauri CLI
|
||||
shell: bash
|
||||
# `|| true` swallowed a genuine install failure and the next step then
|
||||
# died with an unrelated "no such command: tauri". It also behaved
|
||||
# differently per leg, since Windows defaults to pwsh where `true` is
|
||||
# not a command. Skip the install if it is already there; otherwise
|
||||
# let a failure be a failure.
|
||||
run: command -v cargo-tauri >/dev/null || cargo install tauri-cli --version '^2' --locked
|
||||
|
||||
- name: Build the bundle
|
||||
working-directory: src/praisonai-desktop/src-tauri
|
||||
run: cargo tauri build --target ${{ matrix.target }} --bundles ${{ matrix.bundles }}
|
||||
|
||||
- name: Name the artifact for the platform it runs on
|
||||
id: artifact
|
||||
shell: bash
|
||||
working-directory: src/praisonai-desktop/src-tauri
|
||||
run: |
|
||||
set -euo pipefail
|
||||
tag="${{ github.event.release.tag_name || inputs.tag }}"
|
||||
root="target/${{ matrix.target }}/release/bundle"
|
||||
found="$(find "$root" -name "*.${{ matrix.ext }}" -print -quit || true)"
|
||||
# Fail loudly rather than uploading nothing: an empty release asset
|
||||
# list is exactly the state this workflow exists to fix, and a bundler
|
||||
# given a target it does not support exits zero having written none.
|
||||
if [ -z "$found" ]; then
|
||||
echo "no .${{ matrix.ext }} was produced under $root"
|
||||
find "$root" -type f -print || echo "(the bundle directory does not exist)"
|
||||
exit 1
|
||||
fi
|
||||
out="PraisonAI-${tag}-${{ matrix.asset }}.${{ matrix.ext }}"
|
||||
mv "$found" "../$out"
|
||||
echo "path=src/praisonai-desktop/$out" >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: Attach it to the release
|
||||
shell: bash
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
run: |
|
||||
gh release upload \
|
||||
"${{ github.event.release.tag_name || inputs.tag }}" \
|
||||
"${{ steps.artifact.outputs.path }}" --clobber
|
||||
|
||||
verify:
|
||||
# A release with a missing platform is worse than an obviously failed
|
||||
# build, because nobody notices. This says which one is absent.
|
||||
needs: build
|
||||
if: always()
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Check every platform produced an asset
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
TAG: ${{ github.event.release.tag_name || inputs.tag }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
assets="$(gh release view "$TAG" --repo "$GITHUB_REPOSITORY" \
|
||||
--json assets -q '.assets[].name')"
|
||||
echo "$assets"
|
||||
missing=""
|
||||
for want in macos-apple-silicon macos-intel windows-x64-setup linux-x64; do
|
||||
echo "$assets" | grep -q -- "$want" || missing="$missing $want"
|
||||
done
|
||||
if [ -n "$missing" ]; then
|
||||
echo "::error::the release is missing:$missing"
|
||||
exit 1
|
||||
fi
|
||||
echo "all four platform builds are attached"
|
||||
@@ -1,115 +0,0 @@
|
||||
# The desktop app's tests.
|
||||
#
|
||||
# These existed and ran nowhere: no workflow referenced praisonai-desktop, and
|
||||
# the frontend suite could not even be installed -- jsdom was undeclared, so it
|
||||
# ran only on machines that happened to have one further up the tree, at
|
||||
# whatever version that happened to be.
|
||||
name: desktop
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths: ['src/praisonai-desktop/**', '.github/workflows/desktop.yml',
|
||||
'.github/workflows/desktop-release.yml']
|
||||
pull_request:
|
||||
paths: ['src/praisonai-desktop/**', '.github/workflows/desktop.yml',
|
||||
'.github/workflows/desktop-release.yml']
|
||||
|
||||
concurrency:
|
||||
group: desktop-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
defaults:
|
||||
run:
|
||||
working-directory: src/praisonai-desktop
|
||||
|
||||
jobs:
|
||||
engine:
|
||||
name: engine (${{ matrix.os }})
|
||||
# The engine is the part that has to behave the same on all three, which is
|
||||
# the entire point of the portability suite -- so it is run on all three.
|
||||
runs-on: ${{ matrix.os }}
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
os: [ubuntu-22.04, macos-15, windows-latest]
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.11'
|
||||
- name: Run the engine tests
|
||||
shell: bash
|
||||
env:
|
||||
# Never touch a real keychain on a shared runner.
|
||||
PRAISONAI_KEYCHAIN_SERVICE: ai.praison.desktop.ci
|
||||
run: |
|
||||
set -euo pipefail
|
||||
failed=0
|
||||
for suite in engine/test_*.py; do
|
||||
echo "::group::$suite"
|
||||
python "$suite" -v || failed=1
|
||||
echo "::endgroup::"
|
||||
done
|
||||
exit $failed
|
||||
|
||||
frontend:
|
||||
name: frontend
|
||||
runs-on: ubuntu-22.04
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '22'
|
||||
- run: npm ci
|
||||
# `test:ci` is every suite except lifecycle, which drives real
|
||||
# conversations against a live engine and a real model -- neither of
|
||||
# which exists on a runner. It is excluded by name rather than left to
|
||||
# skip quietly, so that a skipped test here is a genuine problem.
|
||||
- name: Run the UI tests
|
||||
# A suite that skips everything still exits 0 -- that is how thirteen
|
||||
# tests came to look like a pass while proving nothing. So the skip
|
||||
# count is asserted, not just the exit status.
|
||||
run: |
|
||||
set -euo pipefail
|
||||
set -o pipefail
|
||||
npm run test:ci 2>&1 | tee "$RUNNER_TEMP/ui.log"
|
||||
skipped=$(grep -E '^. skipped ' "$RUNNER_TEMP/ui.log" | grep -oE '[0-9]+$' | head -1)
|
||||
echo "skipped: ${skipped:-unknown}"
|
||||
test "${skipped:-1}" -eq 0
|
||||
|
||||
shell:
|
||||
name: shell (${{ matrix.os }})
|
||||
runs-on: ${{ matrix.os }}
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
os: [ubuntu-22.04, macos-15, windows-latest]
|
||||
defaults:
|
||||
run:
|
||||
working-directory: src/praisonai-desktop/src-tauri
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
components: clippy
|
||||
- uses: Swatinem/rust-cache@v2
|
||||
with:
|
||||
workspaces: src/praisonai-desktop/src-tauri
|
||||
# The Windows cache is large and slow enough to cost more than it saves.
|
||||
save-if: ${{ runner.os != 'Windows' }}
|
||||
- name: Install the Linux build dependencies
|
||||
if: runner.os == 'Linux'
|
||||
working-directory: .
|
||||
run: |
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y --no-install-recommends \
|
||||
libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev \
|
||||
libxdo-dev libssl-dev patchelf
|
||||
- name: Test
|
||||
# Debug info is the bulk of a Tauri target directory and nothing here
|
||||
# reads a backtrace, so building without it keeps the runner's disk
|
||||
# from filling on the Windows leg.
|
||||
run: cargo test --config 'profile.test.debug=false' --config 'profile.dev.debug=false'
|
||||
- name: Clippy
|
||||
run: cargo clippy --all-targets -- -D warnings
|
||||
@@ -1,12 +1,12 @@
|
||||
name: Nightly Release Gate
|
||||
|
||||
# Preflight before PyPI Release (patch bump).
|
||||
# Triggers: Core Tests success on main (workflow_run) or cron every 3 days at 00:00 UTC.
|
||||
# Dedupe: max one successful patch release every 3 days (see release-gate.js).
|
||||
# Triggers: Core Tests success on main (workflow_run) or nightly cron at 00:00 UTC.
|
||||
# Dedupe: max one successful patch release per UTC day (see release-gate.js).
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: '0 0 */3 * *'
|
||||
- cron: '0 0 * * *'
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
dry_run:
|
||||
@@ -41,7 +41,7 @@ jobs:
|
||||
github.event.workflow_run.head_branch == 'main' &&
|
||||
github.event.workflow_run.event == 'push' &&
|
||||
!startsWith(github.event.workflow_run.head_commit.message, 'Release v') &&
|
||||
!startsWith(github.event.workflow_run.head_commit.message, 'chore(release):')
|
||||
!startsWith(github.event.workflow_run.head_commit.message, 'Bump praisonai')
|
||||
)
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
@@ -69,10 +69,6 @@ jobs:
|
||||
- name: Fetch main and tags
|
||||
run: git fetch --tags origin main
|
||||
|
||||
# Guards the gate logic itself — no workflow ran these selftests before.
|
||||
- name: Selftest release-gate script
|
||||
run: node .github/scripts/release-gate-selftest.js
|
||||
|
||||
- name: Preflight — path changes, CI SHA, dedupe
|
||||
id: preflight
|
||||
uses: actions/github-script@v7
|
||||
|
||||
+170
-427
@@ -61,29 +61,6 @@ on:
|
||||
required: false
|
||||
default: false
|
||||
type: boolean
|
||||
skip_deploy:
|
||||
description: 'Skip praisonai-deploy publish (recovery if already on PyPI)'
|
||||
required: false
|
||||
default: false
|
||||
type: boolean
|
||||
# NOTE: GitHub caps workflow_dispatch at 25 top-level inputs; this
|
||||
# workflow has 23. Adding a 10th package (skip_* + *_version) hits 25.
|
||||
only:
|
||||
description: 'Release ONLY this package (forces skip on all others); all = no restriction'
|
||||
required: false
|
||||
default: all
|
||||
type: choice
|
||||
options:
|
||||
- all
|
||||
- agents
|
||||
- code
|
||||
- bot
|
||||
- train
|
||||
- browser
|
||||
- mcp
|
||||
- sandbox
|
||||
- deploy
|
||||
- wrapper
|
||||
agents_version:
|
||||
description: 'Override agents version (empty = auto bump from pyproject.toml)'
|
||||
required: false
|
||||
@@ -124,11 +101,6 @@ on:
|
||||
required: false
|
||||
default: ''
|
||||
type: string
|
||||
deploy_version:
|
||||
description: 'Override praisonai-deploy version (empty = auto bump from pyproject.toml)'
|
||||
required: false
|
||||
default: ''
|
||||
type: string
|
||||
source:
|
||||
description: 'Trigger source (audit trail)'
|
||||
required: false
|
||||
@@ -162,35 +134,15 @@ jobs:
|
||||
'pypi-auto' || 'pypi'
|
||||
}}
|
||||
env:
|
||||
# PyPI API token auth: username __token__, password = pypi-… token (see pypi.org/help/#invalid-auth)
|
||||
UV_PUBLISH_USERNAME: __token__
|
||||
UV_PUBLISH_PASSWORD: ${{ secrets.PYPI_TOKEN || secrets.PYPI_API_TOKEN }}
|
||||
# GH_TOKEN is NOT set here: it is a GitHub App installation token minted in
|
||||
# "Generate GitHub App token" and exported via $GITHUB_ENV, so releases are
|
||||
# authored by praisonai-triage-agent[bot] rather than MervinPraison.
|
||||
UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN || secrets.PYPI_API_TOKEN }}
|
||||
GH_TOKEN: ${{ secrets.GH_TOKEN }}
|
||||
steps:
|
||||
- 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 }}
|
||||
# Scope to this repo only. Without it the token is minted for every
|
||||
# repository the owner has; this job never leaves PraisonAI (checkout,
|
||||
# push to origin, and gh release create all target it).
|
||||
repositories: ${{ github.event.repository.name }}
|
||||
|
||||
- name: Checkout main
|
||||
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
with:
|
||||
ref: main
|
||||
fetch-depth: 0
|
||||
token: ${{ steps.app-token.outputs.token }}
|
||||
# Do not bake the token into .git/config: an http.extraheader would
|
||||
# outrank the remote URL set in "Configure git" and pin this first
|
||||
# (1h) token, defeating the refresh before the wrapper release.
|
||||
persist-credentials: false
|
||||
token: ${{ secrets.GH_TOKEN }}
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
|
||||
@@ -201,19 +153,10 @@ jobs:
|
||||
uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
|
||||
|
||||
- name: Configure git
|
||||
env:
|
||||
APP_TOKEN: ${{ steps.app-token.outputs.token }}
|
||||
REPO: ${{ github.repository }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
git config user.name "praisonai-triage-agent[bot]"
|
||||
git config user.email "272766704+praisonai-triage-agent[bot]@users.noreply.github.com"
|
||||
# persist-credentials:false left the remote unauthenticated; push auth
|
||||
# comes from the app token embedded here (masked in logs, and the
|
||||
# token dies with the runner).
|
||||
git remote set-url origin "https://x-access-token:${APP_TOKEN}@github.com/${REPO}.git"
|
||||
echo "GH_TOKEN=${APP_TOKEN}" >> "$GITHUB_ENV"
|
||||
GH_TOKEN="${APP_TOKEN}" gh auth setup-git
|
||||
git config user.name "MervinPraison"
|
||||
git config user.email "[email protected]"
|
||||
gh auth setup-git
|
||||
|
||||
- name: Release summary
|
||||
run: |
|
||||
@@ -223,36 +166,6 @@ jobs:
|
||||
echo "Dry run: ${{ inputs.dry_run }}"
|
||||
echo "Environment: ${{ (inputs.source == 'ci' || inputs.source == 'nightly') && inputs.bump == 'patch' && 'pypi-auto' || 'pypi' }}"
|
||||
|
||||
# Single source of truth for which packages this run releases. `only`
|
||||
# inverts into the skip flags here; everything downstream (version
|
||||
# computation, PyPI detection, publish conditions) consumes these
|
||||
# outputs, so a dedicated one-package release is one input instead of
|
||||
# eight skip flags.
|
||||
- name: Resolve effective skips
|
||||
id: flags
|
||||
env:
|
||||
ONLY: ${{ inputs.only }}
|
||||
SKIP_AGENTS: ${{ inputs.skip_agents }}
|
||||
SKIP_CODE: ${{ inputs.skip_code }}
|
||||
SKIP_BOT: ${{ inputs.skip_bot }}
|
||||
SKIP_TRAIN: ${{ inputs.skip_train }}
|
||||
SKIP_BROWSER: ${{ inputs.skip_browser }}
|
||||
SKIP_MCP: ${{ inputs.skip_mcp }}
|
||||
SKIP_SANDBOX: ${{ inputs.skip_sandbox }}
|
||||
SKIP_DEPLOY: ${{ inputs.skip_deploy }}
|
||||
SKIP_WRAPPER: ${{ inputs.skip_wrapper }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
for pkg in agents code bot train browser mcp sandbox deploy wrapper; do
|
||||
var="SKIP_$(echo "$pkg" | tr '[:lower:]' '[:upper:]')"
|
||||
skip="${!var}"
|
||||
if [ -n "${ONLY}" ] && [ "${ONLY}" != "all" ] && [ "${ONLY}" != "$pkg" ]; then
|
||||
skip=true
|
||||
fi
|
||||
echo "skip_${pkg}=${skip}" >> "$GITHUB_OUTPUT"
|
||||
echo "skip_${pkg}=${skip}"
|
||||
done
|
||||
|
||||
- name: Compute release versions
|
||||
id: versions
|
||||
env:
|
||||
@@ -265,15 +178,13 @@ jobs:
|
||||
BROWSER_OVERRIDE: ${{ inputs.browser_version }}
|
||||
MCP_OVERRIDE: ${{ inputs.mcp_version }}
|
||||
SANDBOX_OVERRIDE: ${{ inputs.sandbox_version }}
|
||||
DEPLOY_OVERRIDE: ${{ inputs.deploy_version }}
|
||||
SKIP_AGENTS: ${{ steps.flags.outputs.skip_agents }}
|
||||
SKIP_CODE: ${{ steps.flags.outputs.skip_code }}
|
||||
SKIP_BOT: ${{ steps.flags.outputs.skip_bot }}
|
||||
SKIP_TRAIN: ${{ steps.flags.outputs.skip_train }}
|
||||
SKIP_BROWSER: ${{ steps.flags.outputs.skip_browser }}
|
||||
SKIP_MCP: ${{ steps.flags.outputs.skip_mcp }}
|
||||
SKIP_SANDBOX: ${{ steps.flags.outputs.skip_sandbox }}
|
||||
SKIP_DEPLOY: ${{ steps.flags.outputs.skip_deploy }}
|
||||
SKIP_AGENTS: ${{ inputs.skip_agents }}
|
||||
SKIP_CODE: ${{ inputs.skip_code }}
|
||||
SKIP_BOT: ${{ inputs.skip_bot }}
|
||||
SKIP_TRAIN: ${{ inputs.skip_train }}
|
||||
SKIP_BROWSER: ${{ inputs.skip_browser }}
|
||||
SKIP_MCP: ${{ inputs.skip_mcp }}
|
||||
SKIP_SANDBOX: ${{ inputs.skip_sandbox }}
|
||||
run: |
|
||||
python <<'PY'
|
||||
import os
|
||||
@@ -310,7 +221,6 @@ jobs:
|
||||
browser_override = os.environ.get("BROWSER_OVERRIDE", "").strip()
|
||||
mcp_override = os.environ.get("MCP_OVERRIDE", "").strip()
|
||||
sandbox_override = os.environ.get("SANDBOX_OVERRIDE", "").strip()
|
||||
deploy_override = os.environ.get("DEPLOY_OVERRIDE", "").strip()
|
||||
validate_version("agents_version", agents_override)
|
||||
validate_version("wrapper_version", wrapper_override)
|
||||
validate_version("code_version", code_override)
|
||||
@@ -319,7 +229,6 @@ jobs:
|
||||
validate_version("browser_version", browser_override)
|
||||
validate_version("mcp_version", mcp_override)
|
||||
validate_version("sandbox_version", sandbox_override)
|
||||
validate_version("deploy_version", deploy_override)
|
||||
|
||||
agents_pyproject = root / "src/praisonai-agents/pyproject.toml"
|
||||
agents_content = agents_pyproject.read_text()
|
||||
@@ -377,14 +286,6 @@ jobs:
|
||||
sys.exit(1)
|
||||
current_sandbox = sandbox_match.group(1)
|
||||
|
||||
deploy_pyproject = root / "src/praisonai-deploy/pyproject.toml"
|
||||
deploy_content = deploy_pyproject.read_text()
|
||||
deploy_match = re.search(r'^version\s*=\s*"([^"]+)"', deploy_content, re.MULTILINE)
|
||||
if not deploy_match:
|
||||
print("Could not read praisonai-deploy version from pyproject.toml", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
current_deploy = deploy_match.group(1)
|
||||
|
||||
wrapper_version_py = root / "src/praisonai/praisonai/version.py"
|
||||
wrapper_content = wrapper_version_py.read_text()
|
||||
wrapper_match = re.search(r'__version__ = "([^"]+)"', wrapper_content)
|
||||
@@ -401,7 +302,6 @@ jobs:
|
||||
("browser", current_browser),
|
||||
("mcp", current_mcp),
|
||||
("sandbox", current_sandbox),
|
||||
("deploy", current_deploy),
|
||||
("wrapper", current_wrapper),
|
||||
):
|
||||
if not SEMVER.match(value):
|
||||
@@ -415,7 +315,6 @@ jobs:
|
||||
skip_browser = os.environ.get("SKIP_BROWSER", "false").lower() == "true"
|
||||
skip_mcp = os.environ.get("SKIP_MCP", "false").lower() == "true"
|
||||
skip_sandbox = os.environ.get("SKIP_SANDBOX", "false").lower() == "true"
|
||||
skip_deploy = os.environ.get("SKIP_DEPLOY", "false").lower() == "true"
|
||||
|
||||
if agents_override:
|
||||
agents_version = agents_override
|
||||
@@ -466,13 +365,6 @@ jobs:
|
||||
else:
|
||||
sandbox_version = bump_version(current_sandbox)
|
||||
|
||||
if deploy_override:
|
||||
deploy_version = deploy_override
|
||||
elif skip_deploy:
|
||||
deploy_version = current_deploy
|
||||
else:
|
||||
deploy_version = bump_version(current_deploy)
|
||||
|
||||
if wrapper_override:
|
||||
wrapper_version = wrapper_override
|
||||
else:
|
||||
@@ -487,7 +379,6 @@ jobs:
|
||||
fh.write(f"browser_version={browser_version}\n")
|
||||
fh.write(f"mcp_version={mcp_version}\n")
|
||||
fh.write(f"sandbox_version={sandbox_version}\n")
|
||||
fh.write(f"deploy_version={deploy_version}\n")
|
||||
fh.write(f"wrapper_version={wrapper_version}\n")
|
||||
fh.write(f"current_agents={current_agents}\n")
|
||||
fh.write(f"current_code={current_code}\n")
|
||||
@@ -496,7 +387,6 @@ jobs:
|
||||
fh.write(f"current_browser={current_browser}\n")
|
||||
fh.write(f"current_mcp={current_mcp}\n")
|
||||
fh.write(f"current_sandbox={current_sandbox}\n")
|
||||
fh.write(f"current_deploy={current_deploy}\n")
|
||||
fh.write(f"current_wrapper={current_wrapper}\n")
|
||||
|
||||
print(f"Agents: {current_agents} -> {agents_version}")
|
||||
@@ -506,7 +396,6 @@ jobs:
|
||||
print(f"Browser: {current_browser} -> {browser_version}")
|
||||
print(f"MCP: {current_mcp} -> {mcp_version}")
|
||||
print(f"Sandbox: {current_sandbox} -> {sandbox_version}")
|
||||
print(f"Deploy: {current_deploy} -> {deploy_version}")
|
||||
print(f"Wrapper: {current_wrapper} -> {wrapper_version}")
|
||||
PY
|
||||
|
||||
@@ -521,17 +410,15 @@ jobs:
|
||||
BROWSER_VERSION: ${{ steps.versions.outputs.browser_version }}
|
||||
MCP_VERSION: ${{ steps.versions.outputs.mcp_version }}
|
||||
SANDBOX_VERSION: ${{ steps.versions.outputs.sandbox_version }}
|
||||
DEPLOY_VERSION: ${{ steps.versions.outputs.deploy_version }}
|
||||
WRAPPER_VERSION: ${{ steps.versions.outputs.wrapper_version }}
|
||||
INPUT_SKIP_AGENTS: ${{ steps.flags.outputs.skip_agents }}
|
||||
INPUT_SKIP_CODE: ${{ steps.flags.outputs.skip_code }}
|
||||
INPUT_SKIP_BOT: ${{ steps.flags.outputs.skip_bot }}
|
||||
INPUT_SKIP_TRAIN: ${{ steps.flags.outputs.skip_train }}
|
||||
INPUT_SKIP_BROWSER: ${{ steps.flags.outputs.skip_browser }}
|
||||
INPUT_SKIP_MCP: ${{ steps.flags.outputs.skip_mcp }}
|
||||
INPUT_SKIP_SANDBOX: ${{ steps.flags.outputs.skip_sandbox }}
|
||||
INPUT_SKIP_DEPLOY: ${{ steps.flags.outputs.skip_deploy }}
|
||||
INPUT_SKIP_WRAPPER: ${{ steps.flags.outputs.skip_wrapper }}
|
||||
INPUT_SKIP_AGENTS: ${{ inputs.skip_agents }}
|
||||
INPUT_SKIP_CODE: ${{ inputs.skip_code }}
|
||||
INPUT_SKIP_BOT: ${{ inputs.skip_bot }}
|
||||
INPUT_SKIP_TRAIN: ${{ inputs.skip_train }}
|
||||
INPUT_SKIP_BROWSER: ${{ inputs.skip_browser }}
|
||||
INPUT_SKIP_MCP: ${{ inputs.skip_mcp }}
|
||||
INPUT_SKIP_SANDBOX: ${{ inputs.skip_sandbox }}
|
||||
INPUT_SKIP_WRAPPER: ${{ inputs.skip_wrapper }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
skip_agents="${INPUT_SKIP_AGENTS}"
|
||||
@@ -541,53 +428,30 @@ jobs:
|
||||
skip_browser="${INPUT_SKIP_BROWSER}"
|
||||
skip_mcp="${INPUT_SKIP_MCP}"
|
||||
skip_sandbox="${INPUT_SKIP_SANDBOX}"
|
||||
skip_deploy="${INPUT_SKIP_DEPLOY}"
|
||||
skip_wrapper="${INPUT_SKIP_WRAPPER}"
|
||||
# Returns 0 if published, 1 if definitively absent (404). Any other
|
||||
# HTTP status (PyPI outage, 5xx, rate limit) FAILS the run: guessing
|
||||
# "not published" would lead to a duplicate-upload failure midway
|
||||
# through the release, which is strictly worse than stopping here
|
||||
# before anything has been published.
|
||||
pypi_published() { # $1=package $2=version
|
||||
local code attempt
|
||||
for attempt in 1 2 3; do
|
||||
code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 30 \
|
||||
"https://pypi.org/pypi/$1/$2/json" || echo "000")
|
||||
case "$code" in
|
||||
200) return 0 ;;
|
||||
404) return 1 ;;
|
||||
*) echo "PyPI check $1==$2 returned HTTP ${code} (attempt ${attempt}/3)"; sleep 5 ;;
|
||||
esac
|
||||
done
|
||||
echo "❌ Cannot determine PyPI state for $1==$2; refusing to guess." >&2
|
||||
exit 2
|
||||
}
|
||||
if [ "$skip_agents" != "true" ]; then
|
||||
pypi_published praisonaiagents "${AGENTS_VERSION}" && skip_agents=true || true
|
||||
curl -fsSL "https://pypi.org/pypi/praisonaiagents/${AGENTS_VERSION}/json" >/dev/null && skip_agents=true || true
|
||||
fi
|
||||
if [ "$skip_code" != "true" ]; then
|
||||
pypi_published praisonai-code "${CODE_VERSION}" && skip_code=true || true
|
||||
curl -fsSL "https://pypi.org/pypi/praisonai-code/${CODE_VERSION}/json" >/dev/null && skip_code=true || true
|
||||
fi
|
||||
if [ "$skip_bot" != "true" ]; then
|
||||
pypi_published praisonai-bot "${BOT_VERSION}" && skip_bot=true || true
|
||||
curl -fsSL "https://pypi.org/pypi/praisonai-bot/${BOT_VERSION}/json" >/dev/null && skip_bot=true || true
|
||||
fi
|
||||
if [ "$skip_train" != "true" ]; then
|
||||
pypi_published praisonai-train "${TRAIN_VERSION}" && skip_train=true || true
|
||||
curl -fsSL "https://pypi.org/pypi/praisonai-train/${TRAIN_VERSION}/json" >/dev/null && skip_train=true || true
|
||||
fi
|
||||
if [ "$skip_browser" != "true" ]; then
|
||||
pypi_published praisonai-browser "${BROWSER_VERSION}" && skip_browser=true || true
|
||||
curl -fsSL "https://pypi.org/pypi/praisonai-browser/${BROWSER_VERSION}/json" >/dev/null && skip_browser=true || true
|
||||
fi
|
||||
if [ "$skip_mcp" != "true" ]; then
|
||||
pypi_published praisonai-mcp "${MCP_VERSION}" && skip_mcp=true || true
|
||||
curl -fsSL "https://pypi.org/pypi/praisonai-mcp/${MCP_VERSION}/json" >/dev/null && skip_mcp=true || true
|
||||
fi
|
||||
if [ "$skip_sandbox" != "true" ]; then
|
||||
pypi_published praisonai-sandbox "${SANDBOX_VERSION}" && skip_sandbox=true || true
|
||||
fi
|
||||
if [ "$skip_deploy" != "true" ]; then
|
||||
pypi_published praisonai-deploy "${DEPLOY_VERSION}" && skip_deploy=true || true
|
||||
curl -fsSL "https://pypi.org/pypi/praisonai-sandbox/${SANDBOX_VERSION}/json" >/dev/null && skip_sandbox=true || true
|
||||
fi
|
||||
if [ "$skip_wrapper" != "true" ]; then
|
||||
pypi_published praisonai "${WRAPPER_VERSION}" && skip_wrapper=true || true
|
||||
curl -fsSL "https://pypi.org/pypi/praisonai/${WRAPPER_VERSION}/json" >/dev/null && skip_wrapper=true || true
|
||||
fi
|
||||
echo "skip_agents=${skip_agents}" >> "$GITHUB_OUTPUT"
|
||||
echo "skip_code=${skip_code}" >> "$GITHUB_OUTPUT"
|
||||
@@ -596,9 +460,8 @@ jobs:
|
||||
echo "skip_browser=${skip_browser}" >> "$GITHUB_OUTPUT"
|
||||
echo "skip_mcp=${skip_mcp}" >> "$GITHUB_OUTPUT"
|
||||
echo "skip_sandbox=${skip_sandbox}" >> "$GITHUB_OUTPUT"
|
||||
echo "skip_deploy=${skip_deploy}" >> "$GITHUB_OUTPUT"
|
||||
echo "skip_wrapper=${skip_wrapper}" >> "$GITHUB_OUTPUT"
|
||||
if [ "$skip_agents" = "true" ] && [ "$skip_code" = "true" ] && [ "$skip_bot" = "true" ] && [ "$skip_train" = "true" ] && [ "$skip_browser" = "true" ] && [ "$skip_mcp" = "true" ] && [ "$skip_sandbox" = "true" ] && [ "$skip_deploy" = "true" ] && [ "$skip_wrapper" = "true" ]; then
|
||||
if [ "$skip_agents" = "true" ] && [ "$skip_code" = "true" ] && [ "$skip_bot" = "true" ] && [ "$skip_train" = "true" ] && [ "$skip_browser" = "true" ] && [ "$skip_mcp" = "true" ] && [ "$skip_sandbox" = "true" ] && [ "$skip_wrapper" = "true" ]; then
|
||||
echo "All target versions already on PyPI — nothing to publish."
|
||||
fi
|
||||
|
||||
@@ -612,7 +475,6 @@ jobs:
|
||||
steps.pypi_exists.outputs.skip_browser == 'true' &&
|
||||
steps.pypi_exists.outputs.skip_mcp == 'true' &&
|
||||
steps.pypi_exists.outputs.skip_sandbox == 'true' &&
|
||||
steps.pypi_exists.outputs.skip_deploy == 'true' &&
|
||||
steps.pypi_exists.outputs.skip_wrapper == 'true'
|
||||
run: echo "Idempotent skip — target versions already on PyPI."
|
||||
|
||||
@@ -620,43 +482,34 @@ jobs:
|
||||
if: inputs.dry_run
|
||||
run: |
|
||||
echo "Dry run — no publish, commit, or push."
|
||||
echo "Only: ${{ inputs.only }}"
|
||||
echo "Agents version: ${{ steps.versions.outputs.agents_version }}"
|
||||
echo "Code version: ${{ steps.versions.outputs.code_version }}"
|
||||
echo "Bot version: ${{ steps.versions.outputs.bot_version }}"
|
||||
echo "Train version: ${{ steps.versions.outputs.train_version }}"
|
||||
echo "Browser version: ${{ steps.versions.outputs.browser_version }}"
|
||||
echo "MCP version: ${{ steps.versions.outputs.mcp_version }}"
|
||||
echo "Sandbox version: ${{ steps.versions.outputs.sandbox_version }}"
|
||||
echo "Deploy version: ${{ steps.versions.outputs.deploy_version }}"
|
||||
echo "Wrapper version: ${{ steps.versions.outputs.wrapper_version }}"
|
||||
echo ""
|
||||
if [ "${{ steps.flags.outputs.skip_agents }}" != "true" ]; then
|
||||
if [ "${{ inputs.skip_agents }}" != "true" ]; then
|
||||
echo "Would publish praisonaiagents ${{ steps.versions.outputs.agents_version }}"
|
||||
fi
|
||||
if [ "${{ steps.flags.outputs.skip_code }}" != "true" ]; then
|
||||
if [ "${{ inputs.skip_code }}" != "true" ]; then
|
||||
echo "Would publish praisonai-code ${{ steps.versions.outputs.code_version }}"
|
||||
fi
|
||||
if [ "${{ steps.flags.outputs.skip_bot }}" != "true" ]; then
|
||||
if [ "${{ inputs.skip_bot }}" != "true" ]; then
|
||||
echo "Would publish praisonai-bot ${{ steps.versions.outputs.bot_version }}"
|
||||
fi
|
||||
if [ "${{ steps.flags.outputs.skip_train }}" != "true" ]; then
|
||||
if [ "${{ inputs.skip_train }}" != "true" ]; then
|
||||
echo "Would publish praisonai-train ${{ steps.versions.outputs.train_version }}"
|
||||
fi
|
||||
if [ "${{ steps.flags.outputs.skip_browser }}" != "true" ]; then
|
||||
if [ "${{ inputs.skip_browser }}" != "true" ]; then
|
||||
echo "Would publish praisonai-browser ${{ steps.versions.outputs.browser_version }}"
|
||||
fi
|
||||
if [ "${{ steps.flags.outputs.skip_mcp }}" != "true" ]; then
|
||||
if [ "${{ inputs.skip_mcp }}" != "true" ]; then
|
||||
echo "Would publish praisonai-mcp ${{ steps.versions.outputs.mcp_version }}"
|
||||
fi
|
||||
if [ "${{ steps.flags.outputs.skip_sandbox }}" != "true" ]; then
|
||||
echo "Would publish praisonai-sandbox ${{ steps.versions.outputs.sandbox_version }}"
|
||||
fi
|
||||
if [ "${{ steps.flags.outputs.skip_deploy }}" != "true" ]; then
|
||||
echo "Would publish praisonai-deploy ${{ steps.versions.outputs.deploy_version }}"
|
||||
fi
|
||||
if [ "${{ steps.flags.outputs.skip_wrapper }}" != "true" ]; then
|
||||
echo "Would run bump_and_release.py ${{ steps.versions.outputs.wrapper_version }} --agents ${{ steps.versions.outputs.agents_version }} --code-pin ${{ steps.versions.outputs.code_version }} --bot-pin ${{ steps.versions.outputs.bot_version }} --train-pin ${{ steps.versions.outputs.train_version }} --browser-pin ${{ steps.versions.outputs.browser_version }} --mcp-pin ${{ steps.versions.outputs.mcp_version }} --sandbox-pin ${{ steps.versions.outputs.sandbox_version }} --deploy-pin ${{ steps.versions.outputs.deploy_version }}"
|
||||
if [ "${{ inputs.skip_wrapper }}" != "true" ]; then
|
||||
echo "Would run bump_and_release.py ${{ steps.versions.outputs.wrapper_version }} --agents ${{ steps.versions.outputs.agents_version }} --code-pin ${{ steps.versions.outputs.code_version }} --bot-pin ${{ steps.versions.outputs.bot_version }} --train-pin ${{ steps.versions.outputs.train_version }} --browser-pin ${{ steps.versions.outputs.browser_version }} --mcp-pin ${{ steps.versions.outputs.mcp_version }}"
|
||||
echo "Would uv publish praisonai ${{ steps.versions.outputs.wrapper_version }}"
|
||||
fi
|
||||
|
||||
@@ -684,9 +537,7 @@ jobs:
|
||||
rm -rf dist
|
||||
uv lock
|
||||
uv build
|
||||
# --check-url makes re-uploads idempotent: files already on PyPI are
|
||||
# skipped instead of failing the publish (partial-upload recovery).
|
||||
uv publish --check-url https://pypi.org/simple/
|
||||
uv publish
|
||||
|
||||
- name: Wait for praisonaiagents on PyPI
|
||||
if: >-
|
||||
@@ -715,6 +566,19 @@ jobs:
|
||||
sleep "$INTERVAL"
|
||||
done
|
||||
|
||||
- name: Commit agents version bump
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
inputs.skip_agents != true &&
|
||||
steps.pypi_exists.outputs.skip_agents != 'true'
|
||||
run: |
|
||||
set -euo pipefail
|
||||
git add src/praisonai-agents/pyproject.toml src/praisonai-agents/uv.lock
|
||||
git diff --cached --quiet && { echo "No agents files to commit"; exit 0; }
|
||||
git commit -m "Bump praisonaiagents to ${{ steps.versions.outputs.agents_version }}"
|
||||
git pull --rebase origin main
|
||||
git push origin main
|
||||
|
||||
- name: Publish praisonai-code
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
@@ -743,9 +607,7 @@ jobs:
|
||||
rm -rf dist
|
||||
uv lock
|
||||
uv build
|
||||
# --check-url makes re-uploads idempotent: files already on PyPI are
|
||||
# skipped instead of failing the publish (partial-upload recovery).
|
||||
uv publish --check-url https://pypi.org/simple/
|
||||
uv publish
|
||||
|
||||
- name: Wait for praisonai-code on PyPI
|
||||
if: >-
|
||||
@@ -774,6 +636,19 @@ jobs:
|
||||
sleep "$INTERVAL"
|
||||
done
|
||||
|
||||
- name: Commit praisonai-code version bump
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
inputs.skip_code != true &&
|
||||
steps.pypi_exists.outputs.skip_code != 'true'
|
||||
run: |
|
||||
set -euo pipefail
|
||||
git add src/praisonai-code/pyproject.toml src/praisonai-code/uv.lock src/praisonai-code/praisonai_code/__init__.py
|
||||
git diff --cached --quiet && { echo "No code files to commit"; exit 0; }
|
||||
git commit -m "Bump praisonai-code to ${{ steps.versions.outputs.code_version }}"
|
||||
git pull --rebase origin main
|
||||
git push origin main
|
||||
|
||||
- name: Publish praisonai-bot
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
@@ -802,9 +677,7 @@ jobs:
|
||||
rm -rf dist
|
||||
uv lock
|
||||
uv build
|
||||
# --check-url makes re-uploads idempotent: files already on PyPI are
|
||||
# skipped instead of failing the publish (partial-upload recovery).
|
||||
uv publish --check-url https://pypi.org/simple/
|
||||
uv publish
|
||||
|
||||
- name: Wait for praisonai-bot on PyPI
|
||||
if: >-
|
||||
@@ -833,6 +706,19 @@ jobs:
|
||||
sleep "$INTERVAL"
|
||||
done
|
||||
|
||||
- name: Commit praisonai-bot version bump
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
inputs.skip_bot != true &&
|
||||
steps.pypi_exists.outputs.skip_bot != 'true'
|
||||
run: |
|
||||
set -euo pipefail
|
||||
git add src/praisonai-bot/pyproject.toml src/praisonai-bot/uv.lock src/praisonai-bot/praisonai_bot/_version.py
|
||||
git diff --cached --quiet && { echo "No bot files to commit"; exit 0; }
|
||||
git commit -m "Bump praisonai-bot to ${{ steps.versions.outputs.bot_version }}"
|
||||
git pull --rebase origin main
|
||||
git push origin main
|
||||
|
||||
- name: Publish praisonai-train
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
@@ -861,9 +747,7 @@ jobs:
|
||||
rm -rf dist
|
||||
uv lock
|
||||
uv build
|
||||
# --check-url makes re-uploads idempotent: files already on PyPI are
|
||||
# skipped instead of failing the publish (partial-upload recovery).
|
||||
uv publish --check-url https://pypi.org/simple/
|
||||
uv publish
|
||||
|
||||
- name: Wait for praisonai-train on PyPI
|
||||
if: >-
|
||||
@@ -892,6 +776,19 @@ jobs:
|
||||
sleep "$INTERVAL"
|
||||
done
|
||||
|
||||
- name: Commit praisonai-train version bump
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
inputs.skip_train != true &&
|
||||
steps.pypi_exists.outputs.skip_train != 'true'
|
||||
run: |
|
||||
set -euo pipefail
|
||||
git add src/praisonai-train/pyproject.toml src/praisonai-train/uv.lock src/praisonai-train/praisonai_train/_version.py
|
||||
git diff --cached --quiet && { echo "No train files to commit"; exit 0; }
|
||||
git commit -m "Bump praisonai-train to ${{ steps.versions.outputs.train_version }}"
|
||||
git pull --rebase origin main
|
||||
git push origin main
|
||||
|
||||
- name: Publish praisonai-browser
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
@@ -920,9 +817,7 @@ jobs:
|
||||
rm -rf dist
|
||||
uv lock
|
||||
uv build
|
||||
# --check-url makes re-uploads idempotent: files already on PyPI are
|
||||
# skipped instead of failing the publish (partial-upload recovery).
|
||||
uv publish --check-url https://pypi.org/simple/
|
||||
uv publish
|
||||
|
||||
- name: Wait for praisonai-browser on PyPI
|
||||
if: >-
|
||||
@@ -951,6 +846,19 @@ jobs:
|
||||
sleep "$INTERVAL"
|
||||
done
|
||||
|
||||
- name: Commit praisonai-browser version bump
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
inputs.skip_browser != true &&
|
||||
steps.pypi_exists.outputs.skip_browser != 'true'
|
||||
run: |
|
||||
set -euo pipefail
|
||||
git add src/praisonai-browser/pyproject.toml src/praisonai-browser/uv.lock src/praisonai-browser/praisonai_browser/_version.py
|
||||
git diff --cached --quiet && { echo "No browser files to commit"; exit 0; }
|
||||
git commit -m "Bump praisonai-browser to ${{ steps.versions.outputs.browser_version }}"
|
||||
git pull --rebase origin main
|
||||
git push origin main
|
||||
|
||||
- name: Publish praisonai-mcp
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
@@ -979,9 +887,7 @@ jobs:
|
||||
rm -rf dist
|
||||
uv lock
|
||||
uv build
|
||||
# --check-url makes re-uploads idempotent: files already on PyPI are
|
||||
# skipped instead of failing the publish (partial-upload recovery).
|
||||
uv publish --check-url https://pypi.org/simple/
|
||||
uv publish
|
||||
|
||||
- name: Wait for praisonai-mcp on PyPI
|
||||
if: >-
|
||||
@@ -1010,6 +916,19 @@ jobs:
|
||||
sleep "$INTERVAL"
|
||||
done
|
||||
|
||||
- name: Commit praisonai-mcp version bump
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
inputs.skip_mcp != true &&
|
||||
steps.pypi_exists.outputs.skip_mcp != 'true'
|
||||
run: |
|
||||
set -euo pipefail
|
||||
git add src/praisonai-mcp/pyproject.toml src/praisonai-mcp/uv.lock src/praisonai-mcp/praisonai_mcp/_version.py
|
||||
git diff --cached --quiet && { echo "No mcp files to commit"; exit 0; }
|
||||
git commit -m "Bump praisonai-mcp to ${{ steps.versions.outputs.mcp_version }}"
|
||||
git pull --rebase origin main
|
||||
git push origin main
|
||||
|
||||
- name: Publish praisonai-sandbox
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
@@ -1038,9 +957,7 @@ jobs:
|
||||
rm -rf dist
|
||||
uv lock
|
||||
uv build
|
||||
# --check-url makes re-uploads idempotent: files already on PyPI are
|
||||
# skipped instead of failing the publish (partial-upload recovery).
|
||||
uv publish --check-url https://pypi.org/simple/
|
||||
uv publish
|
||||
|
||||
- name: Wait for praisonai-sandbox on PyPI
|
||||
if: >-
|
||||
@@ -1069,101 +986,20 @@ jobs:
|
||||
sleep "$INTERVAL"
|
||||
done
|
||||
|
||||
- name: Publish praisonai-deploy
|
||||
- name: Commit praisonai-sandbox version bump
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
inputs.skip_deploy != true &&
|
||||
steps.pypi_exists.outputs.skip_deploy != 'true'
|
||||
working-directory: src/praisonai-deploy
|
||||
env:
|
||||
NEW_VERSION: ${{ steps.versions.outputs.deploy_version }}
|
||||
CURRENT: ${{ steps.versions.outputs.current_deploy }}
|
||||
inputs.skip_sandbox != true &&
|
||||
steps.pypi_exists.outputs.skip_sandbox != 'true'
|
||||
run: |
|
||||
set -euo pipefail
|
||||
python <<'PY'
|
||||
import os
|
||||
import re
|
||||
from pathlib import Path
|
||||
new = os.environ["NEW_VERSION"]
|
||||
current = os.environ["CURRENT"]
|
||||
pyproject = Path("pyproject.toml")
|
||||
content = pyproject.read_text()
|
||||
pyproject.write_text(content.replace(f'version = "{current}"', f'version = "{new}"', 1))
|
||||
version_py = Path("praisonai_deploy/_version.py")
|
||||
version_content = version_py.read_text()
|
||||
version_py.write_text(re.sub(r'__version__ = "[^"]+"', f'__version__ = "{new}"', version_content, count=1))
|
||||
PY
|
||||
|
||||
rm -rf dist
|
||||
uv lock
|
||||
uv build
|
||||
# --check-url makes re-uploads idempotent: files already on PyPI are
|
||||
# skipped instead of failing the publish (partial-upload recovery).
|
||||
uv publish --check-url https://pypi.org/simple/
|
||||
|
||||
- name: Wait for praisonai-deploy on PyPI
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
inputs.skip_deploy != true &&
|
||||
steps.pypi_exists.outputs.skip_deploy != 'true'
|
||||
run: |
|
||||
set -euo pipefail
|
||||
PACKAGE="praisonai-deploy"
|
||||
VERSION="${{ steps.versions.outputs.deploy_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
|
||||
|
||||
# All per-package version bumps are still uncommitted at this point: the
|
||||
# wrapper release below stages every one of them (bump_and_release.py's
|
||||
# release_files list) into a SINGLE "Release v…" commit.
|
||||
|
||||
# App tokens expire after 1h and this job can exceed that (9 packages ×
|
||||
# up to a 600s PyPI wait). Re-mint so the final commit/tag/push/release
|
||||
# never runs on an expired token.
|
||||
- name: Refresh GitHub App token
|
||||
id: app-token-final
|
||||
if: ${{ !cancelled() && inputs.dry_run != true }}
|
||||
# A failed re-mint must not fail the release: the original token may
|
||||
# still be valid, and the next step only swaps tokens on success.
|
||||
continue-on-error: true
|
||||
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 }}
|
||||
repositories: ${{ github.event.repository.name }}
|
||||
|
||||
# Guarded on the refresh actually succeeding: if the re-mint failed
|
||||
# (API blip), the ORIGINAL token — still wired into the remote URL and
|
||||
# GH_TOKEN — may well be valid, and overwriting it with an empty string
|
||||
# would turn a recoverable situation into a guaranteed auth failure.
|
||||
- name: Use refreshed GitHub App token
|
||||
if: ${{ !cancelled() && inputs.dry_run != true && steps.app-token-final.outcome == 'success' }}
|
||||
env:
|
||||
APP_TOKEN: ${{ steps.app-token-final.outputs.token }}
|
||||
REPO: ${{ github.repository }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
git remote set-url origin "https://x-access-token:${APP_TOKEN}@github.com/${REPO}.git"
|
||||
echo "GH_TOKEN=${APP_TOKEN}" >> "$GITHUB_ENV"
|
||||
git add src/praisonai-sandbox/pyproject.toml src/praisonai-sandbox/uv.lock src/praisonai-sandbox/praisonai_sandbox/_version.py
|
||||
git diff --cached --quiet && { echo "No sandbox files to commit"; exit 0; }
|
||||
git commit -m "Bump praisonai-sandbox to ${{ steps.versions.outputs.sandbox_version }}"
|
||||
git pull --rebase origin main
|
||||
git push origin main
|
||||
|
||||
- name: Bump and release wrapper
|
||||
id: wrapper
|
||||
if: >-
|
||||
inputs.dry_run != true &&
|
||||
inputs.skip_wrapper != true &&
|
||||
@@ -1178,8 +1014,7 @@ jobs:
|
||||
--browser-pin "${{ steps.versions.outputs.browser_version }}" \
|
||||
--mcp-pin "${{ steps.versions.outputs.mcp_version }}" \
|
||||
--sandbox-pin "${{ steps.versions.outputs.sandbox_version }}" \
|
||||
--deploy-pin "${{ steps.versions.outputs.deploy_version }}" \
|
||||
--wait --max-wait 600 --no-add-all --force
|
||||
--wait --max-wait 600 --no-add-all
|
||||
|
||||
- name: Publish praisonai wrapper to PyPI
|
||||
if: >-
|
||||
@@ -1187,7 +1022,7 @@ jobs:
|
||||
inputs.skip_wrapper != true &&
|
||||
steps.pypi_exists.outputs.skip_wrapper != 'true'
|
||||
working-directory: src/praisonai
|
||||
run: uv publish --check-url https://pypi.org/simple/
|
||||
run: uv publish
|
||||
|
||||
- name: Wait for praisonai on PyPI
|
||||
if: >-
|
||||
@@ -1216,139 +1051,47 @@ jobs:
|
||||
sleep "$INTERVAL"
|
||||
done
|
||||
|
||||
# Actually probes PyPI — previously this step only echoed checkmarks
|
||||
# from the input flags, so it "verified" publishes that never happened.
|
||||
- name: Verify PyPI versions
|
||||
if: inputs.dry_run != true
|
||||
run: |
|
||||
set -euo pipefail
|
||||
verify() { # $1=pypi-name $2=version $3=effective-skip
|
||||
if [ "$3" = "true" ]; then
|
||||
echo "⏭️ $1 skipped"
|
||||
return 0
|
||||
fi
|
||||
if curl -fsSL --max-time 30 "https://pypi.org/pypi/$1/$2/json" >/dev/null; then
|
||||
echo "✅ $1==$2"
|
||||
else
|
||||
echo "❌ $1==$2 NOT found on PyPI"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
verify praisonaiagents "${{ steps.versions.outputs.agents_version }}" "${{ steps.flags.outputs.skip_agents }}"
|
||||
verify praisonai-code "${{ steps.versions.outputs.code_version }}" "${{ steps.flags.outputs.skip_code }}"
|
||||
verify praisonai-bot "${{ steps.versions.outputs.bot_version }}" "${{ steps.flags.outputs.skip_bot }}"
|
||||
verify praisonai-train "${{ steps.versions.outputs.train_version }}" "${{ steps.flags.outputs.skip_train }}"
|
||||
verify praisonai-browser "${{ steps.versions.outputs.browser_version }}" "${{ steps.flags.outputs.skip_browser }}"
|
||||
verify praisonai-mcp "${{ steps.versions.outputs.mcp_version }}" "${{ steps.flags.outputs.skip_mcp }}"
|
||||
verify praisonai-sandbox "${{ steps.versions.outputs.sandbox_version }}" "${{ steps.flags.outputs.skip_sandbox }}"
|
||||
verify praisonai-deploy "${{ steps.versions.outputs.deploy_version }}" "${{ steps.flags.outputs.skip_deploy }}"
|
||||
verify praisonai "${{ steps.versions.outputs.wrapper_version }}" "${{ steps.flags.outputs.skip_wrapper }}"
|
||||
AGENTS="${{ steps.versions.outputs.agents_version }}"
|
||||
CODE="${{ steps.versions.outputs.code_version }}"
|
||||
BOT="${{ steps.versions.outputs.bot_version }}"
|
||||
TRAIN="${{ steps.versions.outputs.train_version }}"
|
||||
BROWSER="${{ steps.versions.outputs.browser_version }}"
|
||||
MCP="${{ steps.versions.outputs.mcp_version }}"
|
||||
SANDBOX="${{ steps.versions.outputs.sandbox_version }}"
|
||||
WRAPPER="${{ steps.versions.outputs.wrapper_version }}"
|
||||
|
||||
# Safety net. On a clean run the wrapper's "Release v…" commit already
|
||||
# carries every bump and this is a no-op. It only fires when the single
|
||||
# commit could not happen: a package publish failed midway (those versions
|
||||
# are already live on PyPI, so the bumps must not be lost), skip_wrapper
|
||||
# was set, or the wrapper itself failed.
|
||||
- name: Persist any uncommitted version bumps
|
||||
if: ${{ !cancelled() && inputs.dry_run != true }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
# If the wrapper release did not complete, drop any uncommitted
|
||||
# wrapper-side rewrites (version.py, Dockerfiles, pins): committing
|
||||
# them would put a wrapper version on main that never reached PyPI,
|
||||
# and the next auto-bump would skip past it forever. Committed
|
||||
# changes are untouched (checkout only reverts the working tree),
|
||||
# and if the wrapper was skipped these files were never modified.
|
||||
if [ "${{ steps.wrapper.outcome }}" != "success" ]; then
|
||||
git checkout -- \
|
||||
src/praisonai/praisonai/version.py \
|
||||
src/praisonai/pyproject.toml \
|
||||
src/praisonai/uv.lock \
|
||||
src/praisonai/README.md \
|
||||
src/praisonai/praisonai.rb \
|
||||
src/praisonai-deploy/praisonai_deploy/docker.py \
|
||||
docker/ 2>/dev/null || true
|
||||
if [ "${{ inputs.skip_agents }}" != "true" ]; then
|
||||
echo "✅ praisonaiagents==${AGENTS}"
|
||||
fi
|
||||
# -u = tracked modifications only; uv build output under dist/ is
|
||||
# untracked and stays out of the commit.
|
||||
git add -u
|
||||
git diff --cached --quiet && { echo "Nothing left to commit"; exit 0; }
|
||||
# Name the packages actually staged, so a single-package release
|
||||
# (every other skip_* set) reads "bump praisonai-mcp" rather than a
|
||||
# generic message. Falls back when nothing under src/ is staged.
|
||||
PKGS="$(git diff --cached --name-only \
|
||||
| sed -n 's#^src/\([^/]*\)/.*#\1#p' | sort -u | tr '\n' ' ' | sed 's/ *$//')"
|
||||
if [ -n "$PKGS" ]; then
|
||||
MSG="chore(release): bump ${PKGS} [skip ci]"
|
||||
else
|
||||
MSG="chore(release): persist version bumps [skip ci]"
|
||||
fi
|
||||
echo "Commit message: ${MSG}"
|
||||
git commit -m "$MSG"
|
||||
# This step fires exactly when the release went sideways — i.e. when
|
||||
# main is most likely to have moved — so the rebase+push retries.
|
||||
# Losing this commit deadlocks future auto-releases: the packages
|
||||
# are on PyPI at N+1 while the repo says N, so every later run
|
||||
# detects "already published" and skips both publish and bump.
|
||||
for attempt in 1 2 3; do
|
||||
git fetch origin main
|
||||
if ! git rebase origin/main; then
|
||||
git rebase --abort || true
|
||||
# During rebase, "theirs" is the commit being replayed — the
|
||||
# version bumps — so they win any conflict.
|
||||
if ! git rebase -X theirs origin/main; then
|
||||
git rebase --abort || true
|
||||
echo "Rebase attempt ${attempt}/3 failed"
|
||||
sleep 5
|
||||
continue
|
||||
fi
|
||||
fi
|
||||
if git push origin main; then
|
||||
echo "Pushed version bumps (attempt ${attempt}/3)"
|
||||
exit 0
|
||||
fi
|
||||
echo "Push attempt ${attempt}/3 rejected; retrying..."
|
||||
sleep 5
|
||||
done
|
||||
echo "❌ Could not push version bumps after 3 attempts."
|
||||
echo " Repo is now BEHIND PyPI; commit the version files on main manually"
|
||||
echo " or future auto-releases will no-op ('already published')."
|
||||
exit 1
|
||||
|
||||
# Dedicated releases (skip_wrapper) create no "Release v…" tag — the
|
||||
# wrapper drives that — so tag each published package individually for
|
||||
# provenance. Full releases keep their single v… tag unchanged.
|
||||
- name: Tag dedicated package releases
|
||||
if: >-
|
||||
${{ !cancelled() && inputs.dry_run != true &&
|
||||
steps.flags.outputs.skip_wrapper == 'true' &&
|
||||
steps.versions.outcome == 'success' }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
tag_pkg() { # $1=effective-skip $2=pypi-name $3=version
|
||||
if [ "$1" = "true" ]; then
|
||||
return 0
|
||||
fi
|
||||
local tag="$2-v$3"
|
||||
# Only tag what is confirmed on PyPI — a package whose publish
|
||||
# failed must not get a tag claiming it shipped.
|
||||
if ! curl -fsSL --max-time 30 "https://pypi.org/pypi/$2/$3/json" >/dev/null; then
|
||||
echo "⏭️ $2==$3 not on PyPI; not tagging"
|
||||
return 0
|
||||
fi
|
||||
if git rev-parse -q --verify "refs/tags/${tag}" >/dev/null; then
|
||||
echo "tag ${tag} already exists"
|
||||
return 0
|
||||
fi
|
||||
git tag "${tag}"
|
||||
git push origin "refs/tags/${tag}"
|
||||
echo "🏷️ ${tag}"
|
||||
}
|
||||
tag_pkg "${{ steps.flags.outputs.skip_agents }}" praisonaiagents "${{ steps.versions.outputs.agents_version }}"
|
||||
tag_pkg "${{ steps.flags.outputs.skip_code }}" praisonai-code "${{ steps.versions.outputs.code_version }}"
|
||||
tag_pkg "${{ steps.flags.outputs.skip_bot }}" praisonai-bot "${{ steps.versions.outputs.bot_version }}"
|
||||
tag_pkg "${{ steps.flags.outputs.skip_train }}" praisonai-train "${{ steps.versions.outputs.train_version }}"
|
||||
tag_pkg "${{ steps.flags.outputs.skip_browser }}" praisonai-browser "${{ steps.versions.outputs.browser_version }}"
|
||||
tag_pkg "${{ steps.flags.outputs.skip_mcp }}" praisonai-mcp "${{ steps.versions.outputs.mcp_version }}"
|
||||
tag_pkg "${{ steps.flags.outputs.skip_sandbox }}" praisonai-sandbox "${{ steps.versions.outputs.sandbox_version }}"
|
||||
tag_pkg "${{ steps.flags.outputs.skip_deploy }}" praisonai-deploy "${{ steps.versions.outputs.deploy_version }}"
|
||||
if [ "${{ inputs.skip_code }}" != "true" ]; then
|
||||
echo "✅ praisonai-code==${CODE}"
|
||||
fi
|
||||
|
||||
if [ "${{ inputs.skip_bot }}" != "true" ]; then
|
||||
echo "✅ praisonai-bot==${BOT}"
|
||||
fi
|
||||
|
||||
if [ "${{ inputs.skip_train }}" != "true" ]; then
|
||||
echo "✅ praisonai-train==${TRAIN}"
|
||||
fi
|
||||
|
||||
if [ "${{ inputs.skip_browser }}" != "true" ]; then
|
||||
echo "✅ praisonai-browser==${BROWSER}"
|
||||
fi
|
||||
|
||||
if [ "${{ inputs.skip_mcp }}" != "true" ]; then
|
||||
echo "✅ praisonai-mcp==${MCP}"
|
||||
fi
|
||||
|
||||
if [ "${{ inputs.skip_sandbox }}" != "true" ]; then
|
||||
echo "✅ praisonai-sandbox==${SANDBOX}"
|
||||
fi
|
||||
|
||||
if [ "${{ inputs.skip_wrapper }}" != "true" ]; then
|
||||
echo "✅ praisonai==${WRAPPER}"
|
||||
fi
|
||||
@@ -24,7 +24,6 @@ jobs:
|
||||
CLAUDE_APP_PRIVATE_KEY: ${{ secrets.CLAUDE_APP_PRIVATE_KEY }}
|
||||
CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
|
||||
GH_TOKEN_VALUE: ${{ secrets.GH_TOKEN }}
|
||||
DOCS_GITHUB_TOKEN: ${{ secrets.SECRETS_ADMIN_PAT }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
if [ -z "${GH_TOKEN:-}" ]; then
|
||||
@@ -35,7 +34,4 @@ jobs:
|
||||
echo -n "$CLAUDE_APP_PRIVATE_KEY" | gh secret set CLAUDE_APP_PRIVATE_KEY --repo "$TARGET"
|
||||
echo -n "$CLAUDE_CODE_OAUTH_TOKEN" | gh secret set CLAUDE_CODE_OAUTH_TOKEN --repo "$TARGET"
|
||||
echo -n "$GH_TOKEN_VALUE" | gh secret set GH_TOKEN --repo "$TARGET"
|
||||
if [ -n "${DOCS_GITHUB_TOKEN:-}" ]; then
|
||||
echo -n "$DOCS_GITHUB_TOKEN" | gh secret set DOCS_GITHUB_TOKEN --repo "$TARGET"
|
||||
fi
|
||||
echo "Synced CLAUDE_APP_ID, CLAUDE_APP_PRIVATE_KEY, CLAUDE_CODE_OAUTH_TOKEN, GH_TOKEN → $TARGET"
|
||||
@@ -5,9 +5,6 @@ on:
|
||||
branches: [ main, develop ]
|
||||
paths:
|
||||
- 'src/**'
|
||||
- 'src/praisonai-deploy/infra/**'
|
||||
- 'src/praisonai-bot/infra/**'
|
||||
- 'scripts/check_helm_charts.sh'
|
||||
- 'pyproject.toml'
|
||||
- '.github/workflows/test-core.yml'
|
||||
- '.github/actions/install-monorepo-packages/**'
|
||||
@@ -15,9 +12,6 @@ on:
|
||||
branches: [ main, develop ]
|
||||
paths:
|
||||
- 'src/**'
|
||||
- 'src/praisonai-deploy/infra/**'
|
||||
- 'src/praisonai-bot/infra/**'
|
||||
- 'scripts/check_helm_charts.sh'
|
||||
- 'pyproject.toml'
|
||||
- '.github/workflows/test-core.yml'
|
||||
- '.github/actions/install-monorepo-packages/**'
|
||||
@@ -101,9 +95,8 @@ jobs:
|
||||
${{ github.workspace }}/src/praisonai-agents:${{ github.workspace }}/src/praisonai-code
|
||||
- shard: train
|
||||
workdir: src/praisonai-train
|
||||
# tests/unit/data/ (96 tests) was collected by no workflow at all.
|
||||
paths: >-
|
||||
tests/unit/train/ tests/unit/data/
|
||||
tests/unit/train/
|
||||
extra_ignore: ""
|
||||
pythonpath: >-
|
||||
${{ github.workspace }}/src/praisonai-agents:${{ github.workspace }}/src/praisonai-code
|
||||
@@ -121,17 +114,11 @@ jobs:
|
||||
extra_ignore: ""
|
||||
pythonpath: >-
|
||||
${{ github.workspace }}/src/praisonai-agents
|
||||
- shard: deploy
|
||||
workdir: src/praisonai-deploy
|
||||
paths: >-
|
||||
tests/
|
||||
extra_ignore: ""
|
||||
pythonpath: >-
|
||||
${{ github.workspace }}/src/praisonai-agents
|
||||
- shard: subdirs
|
||||
paths: >-
|
||||
tests/unit/scheduler/
|
||||
tests/unit/integrations/
|
||||
tests/unit/deploy/
|
||||
tests/unit/mcp/
|
||||
tests/unit/knowledge/
|
||||
tests/unit/llm/
|
||||
@@ -196,9 +183,6 @@ jobs:
|
||||
if [ "$WORKDIR" = "src/praisonai-sandbox" ]; then
|
||||
bash "$GITHUB_WORKSPACE/scripts/check_c13_sandbox_imports.sh"
|
||||
fi
|
||||
if [ "$WORKDIR" = "src/praisonai-deploy" ]; then
|
||||
bash "$GITHUB_WORKSPACE/scripts/check_c14_deploy_imports.sh"
|
||||
fi
|
||||
if [ "$WORKDIR" = "src/praisonai-mcp" ]; then
|
||||
bash "$GITHUB_WORKSPACE/scripts/check_c12_mcp_imports.sh"
|
||||
fi
|
||||
@@ -284,27 +268,9 @@ jobs:
|
||||
--ignore=tests/integration/test_tracker_complex_tasks.py \
|
||||
--ignore=tests/integration/test_serve_integration.py
|
||||
|
||||
helm-charts:
|
||||
name: helm-charts
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: false
|
||||
- name: Setup Helm
|
||||
uses: azure/setup-helm@v3
|
||||
with:
|
||||
version: v3.14.4
|
||||
- name: Lint and template Helm charts
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
bash "$GITHUB_WORKSPACE/scripts/check_helm_charts.sh"
|
||||
|
||||
test-core:
|
||||
name: test-core
|
||||
needs: [test-core-collect, test-core-unit, test-core-integration, helm-charts]
|
||||
needs: [test-core-collect, test-core-unit, test-core-integration]
|
||||
if: always()
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
@@ -316,9 +282,8 @@ jobs:
|
||||
collect='${{ needs.test-core-collect.result }}'
|
||||
unit='${{ needs.test-core-unit.result }}'
|
||||
integration='${{ needs.test-core-integration.result }}'
|
||||
helm='${{ needs.helm-charts.result }}'
|
||||
echo "collect=$collect unit=$unit integration=$integration helm=$helm"
|
||||
if [ "$collect" != "success" ] || [ "$unit" != "success" ] || [ "$integration" != "success" ] || [ "$helm" != "success" ]; then
|
||||
echo "collect=$collect unit=$unit integration=$integration"
|
||||
if [ "$collect" != "success" ] || [ "$unit" != "success" ] || [ "$integration" != "success" ]; then
|
||||
echo "Core Tests failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
@@ -86,7 +86,6 @@ jobs:
|
||||
tests/unit/test_c11_browser_backward_compat.py \
|
||||
tests/unit/test_c12_mcp_backward_compat.py \
|
||||
tests/unit/test_c13_sandbox_backward_compat.py \
|
||||
tests/unit/test_c14_deploy_backward_compat.py \
|
||||
-q --tb=line --timeout=30 --maxfail=5
|
||||
python -m pytest tests/unit/cli/ \
|
||||
../praisonai-bot/tests/unit/cli/test_onboard_command.py \
|
||||
@@ -98,20 +97,6 @@ jobs:
|
||||
--ignore=tests/unit/cli/test_message_queue.py \
|
||||
--maxfail=5
|
||||
|
||||
- name: Run praisonai-agents subscription-auth smoke tests
|
||||
env:
|
||||
PRAISONAI_TEST_TIER: smoke
|
||||
PRAISONAI_ALLOW_NETWORK: '0'
|
||||
OPENAI_MODEL_NAME: gpt-4o-mini
|
||||
OPENAI_API_KEY: 'test-key'
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
cd src/praisonai-agents
|
||||
python -m pytest tests/smoke/test_subscription_auth.py \
|
||||
tests/unit/auth/test_agent_auth_wiring.py \
|
||||
-q --tb=line --timeout=60 --maxfail=5
|
||||
|
||||
- name: Standalone praisonai-code import smoke
|
||||
shell: bash
|
||||
run: |
|
||||
@@ -284,26 +269,10 @@ jobs:
|
||||
bash "$GITHUB_WORKSPACE/scripts/check_c13_sandbox_imports.sh"
|
||||
python -m pytest src/praisonai-sandbox/tests -q -m "not network"
|
||||
|
||||
- name: Standalone praisonai-deploy smoke (C14)
|
||||
run: |
|
||||
set -euo pipefail
|
||||
python -m venv /tmp/praisonai-deploy-standalone
|
||||
/tmp/praisonai-deploy-standalone/bin/pip install -q -e src/praisonai-agents -e src/praisonai-deploy
|
||||
/tmp/praisonai-deploy-standalone/bin/python -c "
|
||||
from praisonai_deploy._version import __version__ as pkg_version
|
||||
import praisonai_deploy
|
||||
assert praisonai_deploy.__version__ == pkg_version
|
||||
assert 'main' not in __import__('sys').modules
|
||||
print('deploy standalone ok', praisonai_deploy.__version__)
|
||||
"
|
||||
/tmp/praisonai-deploy-standalone/bin/praisonai-deploy --help
|
||||
bash "$GITHUB_WORKSPACE/scripts/check_c14_deploy_imports.sh"
|
||||
python -m pytest src/praisonai-deploy/tests -q -m "not network"
|
||||
|
||||
- name: Audit hybrid module imports (C8 full stack)
|
||||
run: |
|
||||
set -euo pipefail
|
||||
pip install -q -e src/praisonai-agents -e src/praisonai-code -e src/praisonai-bot -e src/praisonai-train -e src/praisonai-browser -e src/praisonai-mcp -e src/praisonai-sandbox -e src/praisonai-deploy -e src/praisonai
|
||||
pip install -q -e src/praisonai-agents -e src/praisonai-code -e src/praisonai-bot -e src/praisonai-train -e src/praisonai-browser -e src/praisonai-mcp -e src/praisonai-sandbox -e src/praisonai
|
||||
python scripts/audit_hybrid_modules.py
|
||||
|
||||
- name: Smoke Test Summary
|
||||
@@ -813,9 +782,6 @@ jobs:
|
||||
tests/unit/test_decorator_simple.py
|
||||
tests/unit/test_db_adapter_tracing_init.py
|
||||
../praisonai-bot/tests/unit/test_bot_wiring.py
|
||||
../praisonai-bot/tests/unit/bots/test_enable_shell.py
|
||||
../praisonai-bot/tests/unit/gateway/test_preflight.py
|
||||
../praisonai-bot/tests/unit/gateway/test_gateway_doctor.py
|
||||
../praisonai-bot/tests/unit/test_bot_history.py
|
||||
../praisonai-bot/tests/unit/test_bot_fixes.py
|
||||
tests/unit/test_auto_lazy_loading.py
|
||||
|
||||
@@ -12,7 +12,6 @@ assets
|
||||
.DS_Store
|
||||
.pytest_cache
|
||||
praisonAI.egg-info
|
||||
src/*/build/
|
||||
flagged
|
||||
test.yaml
|
||||
db
|
||||
@@ -25,8 +24,6 @@ output
|
||||
!src/praisonai-agents/praisonaiagents/output/
|
||||
!src/praisonai-code/praisonai_code/cli/output/
|
||||
!src/praisonai-bot/praisonai_bot/cli/output/
|
||||
!src/praisonai-ts/src/db/
|
||||
!src/praisonai-ts/src/cli/output/
|
||||
|
||||
.files
|
||||
threads.db
|
||||
|
||||
@@ -7,9 +7,9 @@ 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
|
||||
- Follow protocol-driven design across the eight 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/`, integrations/serve/dashboard in the `praisonai/` wrapper
|
||||
- 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)
|
||||
- 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)
|
||||
- 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.
|
||||
+10
-29
@@ -1,6 +1,6 @@
|
||||
# PraisonAI Architecture
|
||||
|
||||
> **Last updated:** 2026-07-31 (C14 — nine-package tiered model)
|
||||
> **Last updated:** 2026-07-17 (C13 — eight-package tiered model)
|
||||
>
|
||||
> Strategic architecture document for PraisonAI — a multi-agent AI framework.
|
||||
> Covers **Python tiered package model (C7.1 + C9 + C10)**, system design, runtime
|
||||
@@ -11,7 +11,7 @@
|
||||
## Table of Contents
|
||||
|
||||
1. [Executive Summary](#1-executive-summary)
|
||||
2. [Python Tiered Package Model (C7.1 + C9 + C10 + C11 + C12 + C13 + C14)](#2-python-tiered-package-model-c71--c9--c10--c11--c12--c13--c14)
|
||||
2. [Python Tiered Package Model (C7.1 + C9 + C10 + C11 + C12 + C13)](#2-python-tiered-package-model-c71--c9--c10--c11--c12--c13)
|
||||
3. [System Overview](#3-system-overview)
|
||||
4. [Layered Architecture](#4-layered-architecture)
|
||||
5. [Core Data Contracts](#5-core-data-contracts)
|
||||
@@ -51,18 +51,17 @@ Orchestration + Observability** core to unlock adoption and trust:
|
||||
|
||||
---
|
||||
|
||||
## 2. Python Tiered Package Model (C7.1 + C9 + C10 + C11 + C12 + C13 + C14)
|
||||
## 2. Python Tiered Package Model (C7.1 + C9 + C10 + C11 + C12 + C13)
|
||||
|
||||
**Release:** v4.6.110+ · `praisonaiagents` · `praisonai-code` · `praisonai-bot` · `praisonai-train` · `praisonai-browser` · `praisonai-mcp` · `praisonai-sandbox` · `praisonai-deploy` · `praisonai`
|
||||
**Release:** v4.6.110+ · `praisonaiagents` · `praisonai-code` · `praisonai-bot` · `praisonai-train` · `praisonai-browser` · `praisonai-mcp` · `praisonai-sandbox` · `praisonai`
|
||||
|
||||
The Python monorepo publishes nine packages in three tiers with strict dependency
|
||||
The Python monorepo publishes eight packages in three tiers with strict dependency
|
||||
direction. C7 delivered a standalone agentic hot path; C7.1 formalised
|
||||
code/wrapper ownership; C9 extracted bots, gateway, and channel CLI into
|
||||
`praisonai-bot`; C10 extracted LLM fine-tuning and agent training into
|
||||
`praisonai-train`; C11 extracted browser automation into `praisonai-browser`;
|
||||
C12 extracted the heavy MCP host into `praisonai-mcp`.
|
||||
C13 extracted sandbox backends into `praisonai-sandbox`.
|
||||
C14 extracted deployment (API, Docker, cloud) into `praisonai-deploy`.
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
@@ -70,14 +69,13 @@ flowchart TB
|
||||
Agents["praisonaiagents<br/>Agent, tools, memory, hooks, protocols"]
|
||||
end
|
||||
|
||||
subgraph tier2 [Tier 2 — Terminal + Bot + Train + Browser + MCP + Sandbox + Deploy]
|
||||
subgraph tier2 [Tier 2 — Terminal + Bot + Train + Browser + MCP + Sandbox]
|
||||
Code["praisonai-code<br/>run, chat, code, Typer, runtime, LLM"]
|
||||
Bot["praisonai-bot<br/>bots, gateway, channel CLI, OS daemon"]
|
||||
Train["praisonai-train<br/>LLM fine-tuning, agent training"]
|
||||
Browser["praisonai-browser<br/>extension bridge, CDP, Playwright"]
|
||||
MCP["praisonai-mcp<br/>MCP server host, auth, capability adapters"]
|
||||
Sandbox["praisonai-sandbox<br/>Docker, E2B, Modal, Sandlock backends"]
|
||||
Deploy["praisonai-deploy<br/>API, Docker, AWS/Azure/GCP deploy"]
|
||||
end
|
||||
|
||||
subgraph tier3 [Tier 3 — Wrapper]
|
||||
@@ -90,53 +88,36 @@ flowchart TB
|
||||
Agents --> Browser
|
||||
Agents --> MCP
|
||||
Agents --> Sandbox
|
||||
Agents --> Deploy
|
||||
Agents --> Wrapper
|
||||
Code -.->|"lazy _bot_bridge"| Bot
|
||||
Code -.->|"lazy _train_bridge"| Train
|
||||
Code -.->|"lazy _browser_bridge"| Browser
|
||||
Code -.->|"lazy _mcp_bridge"| MCP
|
||||
Code -.->|"lazy _sandbox_bridge"| Sandbox
|
||||
Code -.->|"lazy _deploy_bridge"| Deploy
|
||||
Code -.->|"lazy _wrapper_bridge"| Wrapper
|
||||
Bot -.->|"lazy _code_bridge / _wrapper_bridge"| Code
|
||||
Bot -.->|"lazy _wrapper_bridge"| Wrapper
|
||||
Train -.->|"lazy _code_bridge / _wrapper_bridge"| Code
|
||||
```
|
||||
|
||||
**PyPI publish order:** `praisonaiagents` → `praisonai-code` + `praisonai-bot` + `praisonai-train` + `praisonai-browser` + `praisonai-mcp` + `praisonai-sandbox` + `praisonai-deploy` → `praisonai`
|
||||
**PyPI publish order:** `praisonaiagents` → `praisonai-code` + `praisonai-bot` + `praisonai-train` + `praisonai-browser` + `praisonai-mcp` + `praisonai-sandbox` → `praisonai`
|
||||
|
||||
**Backward compatibility:** `praisonai.bots`, `praisonai.gateway`, `praisonai.train`,
|
||||
`praisonai.browser`, `praisonai.mcp_server`, `praisonai.sandbox`, `praisonai.deploy`, and related CLI paths remain as
|
||||
`praisonai.browser`, `praisonai.mcp_server`, `praisonai.sandbox`, and related CLI paths remain as
|
||||
`alias_package` shims to `praisonai_bot.*` / `praisonai_train.*` /
|
||||
`praisonai_browser.*` / `praisonai_mcp.*` / `praisonai_sandbox.*` / `praisonai_deploy.*`.
|
||||
`praisonai_browser.*` / `praisonai_mcp.*` / `praisonai_sandbox.*`.
|
||||
|
||||
| Tier | Package | Owns | Must not depend on |
|
||||
|------|---------|------|-------------------|
|
||||
| 1 | `src/praisonai-agents/` | Agent, tools, memory, hooks, `frameworks/` protocols, sandbox protocols | `praisonai`, `praisonai-code`, `praisonai-bot`, `praisonai-train`, `praisonai-browser`, `praisonai-mcp`, `praisonai-sandbox`, `praisonai-deploy` |
|
||||
| 1 | `src/praisonai-agents/` | Agent, tools, memory, hooks, `frameworks/` protocols, sandbox protocols | `praisonai`, `praisonai-code`, `praisonai-bot`, `praisonai-train`, `praisonai-browser`, `praisonai-mcp`, `praisonai-sandbox` |
|
||||
| 2a | `src/praisonai-code/` | `run`/`chat`/`code`, Typer, runtime, LLM, tool resolution | **`praisonai` as a PyPI dependency** (optional lazy imports via `_wrapper_bridge` only) |
|
||||
| 2b | `src/praisonai-bot/` | Bots, gateway, channel CLI, OS daemon, gateway scheduler tick | **`praisonai` as a PyPI dependency** (optional lazy `_wrapper_bridge` for jobs/UI) |
|
||||
| 2c | `src/praisonai-train/` | LLM fine-tuning (Unsloth), agent training, `train` CLI, conda env setup | **`praisonai` as a PyPI dependency** (lazy `_code_bridge` for legacy dispatch) |
|
||||
| 2d | `src/praisonai-browser/` | Extension bridge, CDP/hybrid automation, `browser` CLI | **`praisonai` as a PyPI dependency** (none required; depends on `praisonaiagents` only) |
|
||||
| 2e | `src/praisonai-mcp/` | MCP server host, auth, transports, `mcp` CLI | **`praisonai` as a PyPI dependency** (lazy `_wrapper_bridge` for full capability registry) |
|
||||
| 2f | `src/praisonai-sandbox/` | Sandbox backends (Docker, E2B, Modal, Sandlock, SSH), `SandboxRegistry` | **`praisonai` as a PyPI dependency** (lazy `_code_bridge` for `PluginRegistry`) |
|
||||
| 2g | `src/praisonai-deploy/` | Deploy API/Docker/cloud, `deploy` CLI, scheduler integration | **`praisonai` as a PyPI dependency** (lazy `_plugin_registry` via `_code_bridge`) |
|
||||
| 3 | `src/praisonai/` | `framework_adapters/`, serve, dashboard, async jobs API | — |
|
||||
|
||||
### Repo infra (not PyPI)
|
||||
|
||||
Deployment packaging that stays in the git checkout, not in any tier-2 wheel:
|
||||
|
||||
| Path | Runtime owner | Orchestration |
|
||||
|------|---------------|---------------|
|
||||
| `src/praisonai-bot/infra/helm/praisonai-gateway/` | `praisonai-bot` (gateway) | C14 `deploy helm` wrapper |
|
||||
| `src/praisonai-deploy/infra/helm/praisonai-agents-api/` | Generated API from C14 | C14 cross-link |
|
||||
| `src/praisonai-deploy/infra/compose/agents-stack/` | Docker Compose | `praisonai deploy compose up/down` |
|
||||
| `src/praisonai-deploy/infra/starters/` | Starter scaffolds | `praisonai deploy create --template` |
|
||||
| `docker/` | Mixed (wrapper/bot dev stacks) | Not C14 — see bot manifest for `docker/bots/` |
|
||||
|
||||
Same boundary as C14: Helm/K8s manifests are **repo infra**, not `pip install praisonai-deploy` content.
|
||||
|
||||
**Config kernel:** Phase 0 `praisonai/common/` was skipped; shared config lives in
|
||||
`praisonai_code/cli/configuration/` and is reached by the bot tier via lazy
|
||||
`_code_bridge` (see `src/praisonai/tests/CONFIG_KERNEL.md`).
|
||||
|
||||
@@ -7,21 +7,8 @@ Thank you for your interest! Here's how to get started:
|
||||
3. Make your changes
|
||||
4. Submit a pull request
|
||||
|
||||
## Where to report issues (hub intake)
|
||||
|
||||
| Topic | Report here | Where fixes land |
|
||||
|-------|-------------|------------------|
|
||||
| Python SDK, CLI, wrapper | **This repo** ([PraisonAI](https://github.com/MervinPraison/PraisonAI)) | `src/praisonai-agents/`, `src/praisonai/` |
|
||||
| TypeScript / JavaScript SDK (`npm install praisonai`) | **This repo** (preferred) or [praisonai-js](https://github.com/MervinPraison/praisonai-js) | [praisonai-js](https://github.com/MervinPraison/praisonai-js) → synced to `src/praisonai-ts/` |
|
||||
| Cross-language parity | **This repo** | Often both Python and praisonai-js PRs |
|
||||
| Agent-callable tools | **This repo** | [PraisonAI-Tools](https://github.com/MervinPraison/PraisonAI-Tools) |
|
||||
| Lifecycle plugins (tracing, hooks, guardrails) | **This repo** | [PraisonAI-Plugins](https://github.com/MervinPraison/PraisonAI-Plugins) |
|
||||
|
||||
You do **not** need to re-file TypeScript issues on praisonai-js — report on PraisonAI and automation routes fixes to the canonical TS repo.
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Follow existing code style
|
||||
- Add tests for new features
|
||||
- Update documentation as needed
|
||||
- TypeScript changes: implement in [praisonai-js](https://github.com/MervinPraison/praisonai-js), then run **Sync to PraisonAI Monorepo** workflow to update `src/praisonai-ts/`
|
||||
@@ -41,6 +41,10 @@ curl -fsSL https://praison.ai/install.sh | bash
|
||||
<img src=".github/images/dashboard.png" alt="PraisonAI Dashboard" width="800" />
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<img src=".github/images/agentflow.gif" alt="PraisonAI AgentFlow" width="800" />
|
||||
</p>
|
||||
|
||||
```
|
||||
██████╗ ██████╗ █████╗ ██╗███████╗ ██████╗ ███╗ ██╗ █████╗ ██╗
|
||||
██╔══██╗██╔══██╗██╔══██╗██║██╔════╝██╔═══██╗████╗ ██║ ██╔══██╗██║
|
||||
@@ -52,6 +56,12 @@ curl -fsSL https://praison.ai/install.sh | bash
|
||||
pip install praisonai
|
||||
```
|
||||
|
||||
<p align="center">
|
||||
<img src=".github/images/latest_ai_news_and_crawl_each_url_to_find_info.gif" alt="PraisonAI command execution" width="800" />
|
||||
</p>
|
||||
|
||||
\* `export TAVILY_API_KEY=xxxxx`
|
||||
|
||||
<div align="center">
|
||||
<a href="https://docs.praison.ai">
|
||||
<p align="center">
|
||||
@@ -96,232 +106,6 @@ agent.start("Analyze the top 3 tech trends of 2026 and format as a markdown tabl
|
||||
|
||||
---
|
||||
|
||||
## 🧬 The Five-Layer Agent Stack
|
||||
|
||||
Most frameworks hand you one or two layers and leave the rest as homework. PraisonAI covers **all five** — plus the outer layer that decides *where* your agent actually runs.
|
||||
|
||||
Each layer wraps the one inside it. When an agent misbehaves, the layer tells you where to look.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ⬡ MANAGED AGENTS — Where does it actually run? │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 5 · GRAPH — Who runs when, and who checks whom? │ │
|
||||
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ 4 · LOOP — When do we stop? │ │ │
|
||||
│ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │
|
||||
│ │ │ │ 3 · HARNESS — Can it act, and be checked? │ │ │ │
|
||||
│ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ │
|
||||
│ │ │ │ │ 2 · CONTEXT — Is the right thing in the window? │ │ │ │ │
|
||||
│ │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ │ │
|
||||
│ │ │ │ │ │ 1 · PROMPT — Did I say it clearly? │ │ │ │ │ │
|
||||
│ │ │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ │
|
||||
│ │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │
|
||||
│ │ │ └─────────────────────────────────────────────────────┘ │ │ │
|
||||
│ │ └─────────────────────────────────────────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
| Layer | The question it answers | PraisonAI |
|
||||
|:--|:--|:--|
|
||||
| **1 · Prompt** | Did I say it clearly? | `instructions=`, `role`/`goal`/`backstory`, `output=`, `templates=` |
|
||||
| **2 · Context** | Is the right thing in the window? | `memory=`, `knowledge=`, `context=`, handoff `ContextPolicy` |
|
||||
| **3 · Harness** | Can it act, and be checked? | `tools=`, `MCP()`, `guardrails=`, `approval=`, `hooks=`, `sandbox=` |
|
||||
| **4 · Loop** | When do we stop? | `execution=ExecutionConfig(...)`, `reflection=`, `autonomy=`, doom-loop detection |
|
||||
| **5 · Graph** | Who runs when, and who checks whom? | `AgentFlow`, `route()`, `parallel()`, `loop()`, `repeat()` |
|
||||
| **⬡ Managed** | *Where does it actually run?* | `tools_run_on="docker"` — one shared sandbox for the tools, or `run_on="anthropic"` for the whole agent |
|
||||
|
||||
### Layer 1 · Prompt — *Did I say it clearly?*
|
||||
|
||||
Role, instructions, examples, output format.
|
||||
|
||||
```python
|
||||
from praisonaiagents import Agent
|
||||
|
||||
agent = Agent(
|
||||
role="Senior Data Analyst",
|
||||
goal="Turn raw numbers into decisions",
|
||||
output="verbose", # markdown-formatted output
|
||||
)
|
||||
agent.start("Summarise Q3 revenue trends")
|
||||
```
|
||||
|
||||
### Layer 2 · Context — *Is the right thing in the window?*
|
||||
|
||||
Write, select, compress, isolate — the four context operations, one parameter each.
|
||||
|
||||
```python
|
||||
from praisonaiagents import Agent
|
||||
|
||||
agent = Agent(
|
||||
instructions="You are a support engineer.",
|
||||
memory={"user_id": "u-42"}, # write — persists across runs (needs a user_id)
|
||||
knowledge=["docs/"], # select — retrieves only what's relevant
|
||||
context="summarize", # compress — auto-compacts before the limit
|
||||
)
|
||||
```
|
||||
|
||||
> **Isolate** is `handoffs=[specialist]` — a sub-agent inherits the last few messages and the intersection of your tools, not your whole transcript. [📖 Handoffs](https://docs.praison.ai/docs/concepts/handoffs)
|
||||
|
||||
### Layer 3 · Harness — *Can it act, and be checked?*
|
||||
|
||||
*Agent = Model + Harness.* Tool dispatch, plus the guides that steer before acting and the sensors that observe after.
|
||||
|
||||
```python
|
||||
from praisonaiagents import Agent, MCP, tool
|
||||
|
||||
@tool
|
||||
def deploy(env: str) -> str:
|
||||
"""Deploy the current build to an environment."""
|
||||
return f"Deployed to {env}"
|
||||
|
||||
agent = Agent(
|
||||
name="ReleaseEngineer",
|
||||
instructions="You are a release engineer.",
|
||||
tools=[deploy, MCP("npx -y @modelcontextprotocol/server-filesystem /tmp")],
|
||||
approval=True, # guide — human gate before risky tools run
|
||||
)
|
||||
agent.start("Deploy to staging, then list the files you can read")
|
||||
```
|
||||
|
||||
### Layer 4 · Loop — *When do we stop?*
|
||||
|
||||
Hard iteration caps, budget ceilings, no-progress detection and completion checks — every brake is explicit.
|
||||
|
||||
```python
|
||||
from praisonaiagents import Agent, ExecutionConfig
|
||||
|
||||
agent = Agent(
|
||||
instructions="Fix the failing tests.",
|
||||
execution=ExecutionConfig(max_iter=30, max_budget=0.50, on_budget_exceeded="stop"),
|
||||
autonomy=True, # required to drive the loop with run_autonomous()
|
||||
)
|
||||
result = agent.run_autonomous("Refactor the auth module", max_iterations=5)
|
||||
|
||||
print(result.completion_reason)
|
||||
# goal | no_tool_calls | max_iterations | timeout | doom_loop | needs_help | error
|
||||
# (with on_budget_exceeded="stop", hitting the cap raises BudgetExceededError,
|
||||
# surfaced here as completion_reason="error")
|
||||
```
|
||||
|
||||
> **Doom-loop detection is on by default.** Repeated identical tool calls and A→B→A→B oscillation get caught — while a poller whose output keeps changing does not. [📖 Doom Loop Detection](https://docs.praison.ai/docs/features/doom-loop-detection)
|
||||
|
||||
### Layer 5 · Graph — *Who runs when, and who checks whom?*
|
||||
|
||||
Topology as a versionable artifact: prompt chaining, routing, parallelisation, orchestrator-worker.
|
||||
|
||||
```python
|
||||
from praisonaiagents import AgentFlow
|
||||
from praisonaiagents.workflows import route, parallel, repeat
|
||||
|
||||
flow = AgentFlow(steps=[
|
||||
classifier,
|
||||
route({"bug": [bug_agent], "feature": [feature_agent], "default": [triage]}),
|
||||
parallel([reviewer, tester]), # fan out, join automatically
|
||||
repeat(editor, until=lambda ctx: "approved" in ctx.previous_result.lower(),
|
||||
max_iterations=3), # evaluator–optimizer
|
||||
])
|
||||
flow.run("Ticket #123: login fails on Safari")
|
||||
```
|
||||
|
||||
> The same graph is expressible in YAML with no Python at all. [📖 AgentFlow](https://docs.praison.ai/docs/concepts/agentflow)
|
||||
|
||||
### ⬡ Outside the stack: Managed Agents — *Where does it actually run?*
|
||||
|
||||
The harness is commoditising; **where** the agent executes is the next multiplier. Rather than burning your laptop's CPU, hand an agent a short-lived cloud sandbox — repo, tools and tests run there.
|
||||
|
||||
```bash
|
||||
pip install praisonai
|
||||
```
|
||||
|
||||
The simplest way in is `tools_run_on=` — one whole team or workflow shares **one** sandbox, so a file written by step 1 is there for step 2. Thinking stays on your machine:
|
||||
|
||||
```python
|
||||
from praisonaiagents import Agent, AgentFlow
|
||||
|
||||
writer = Agent(name="Writer", instructions="You write files.")
|
||||
reader = Agent(name="Reader", instructions="You read files.")
|
||||
|
||||
flow = AgentFlow(tools_run_on="docker", steps=[writer, reader]) # or e2b | modal | daytona | flyio
|
||||
flow.run("Write 'hello' to /workspace/note.txt, then read it back")
|
||||
```
|
||||
|
||||
Same thing with no Python at all:
|
||||
|
||||
```yaml
|
||||
name: remote-demo
|
||||
tools_run_on: docker # every step shares one sandbox
|
||||
agents:
|
||||
writer: {role: Writer, goal: Write files}
|
||||
reader: {role: Reader, goal: Read files}
|
||||
steps:
|
||||
- agent: writer
|
||||
action: "Write 'hello' to /workspace/note.txt"
|
||||
- agent: reader
|
||||
action: "Read /workspace/note.txt"
|
||||
```
|
||||
|
||||
For a single agent, two words cover it — and they answer different questions:
|
||||
|
||||
```python
|
||||
from praisonaiagents import Agent
|
||||
|
||||
# A. Only the TOOLS move. Thinking stays on your machine.
|
||||
agent = Agent(name="builder", instructions="You build things.",
|
||||
tools_run_on="docker") # docker | e2b | modal | daytona | flyio
|
||||
# tenki | sandlock | ssh | novita | subprocess
|
||||
|
||||
# B. The WHOLE agent moves — model calls, loop and tools
|
||||
agent = Agent(name="teacher", instructions="You teach.", run_on="anthropic") # hosted
|
||||
agent = Agent(name="builder", instructions="You build.", run_on="docker") # self-hosted
|
||||
agent.start("Write a Python script that prints the first 10 primes, then run it")
|
||||
```
|
||||
|
||||
Ask any object where it runs, and it will tell you:
|
||||
|
||||
```python
|
||||
>>> Agent(name="builder", instructions="x", tools_run_on="docker")
|
||||
Agent(name='builder', thinks_on='this machine', tools_run_on='a Docker container')
|
||||
|
||||
>>> agent.where_does_it_run()
|
||||
Thinking (the AI model calls) happens on this machine.
|
||||
Tools run on a Docker container.
|
||||
Your own tools (check_db) still run on this machine -- only shell, file and
|
||||
code tools move. They read and write this machine's files.
|
||||
```
|
||||
|
||||
Naming a place that cannot do the job is a typo, not a preference, so it says so:
|
||||
|
||||
```python
|
||||
>>> Agent(name="x", instructions="i", run_on="e2b")
|
||||
TypeError: Agent(run_on='e2b') is not valid: run_on= places the whole agent
|
||||
-- model calls, loop and tools -- on a managed runtime, and 'e2b' runs
|
||||
commands but cannot host an agent loop.
|
||||
To run only the tools there: Agent(tools_run_on='e2b')
|
||||
```
|
||||
|
||||
To run one block of code somewhere else, name the place on that call:
|
||||
|
||||
```python
|
||||
agent.execute_code_sync("print(6 * 7)", run_in="sandlock") # kernel-enforced
|
||||
```
|
||||
|
||||
See what is running and reclaim strays:
|
||||
|
||||
```bash
|
||||
praisonai managed ps # list running sandboxes
|
||||
praisonai managed stop --all # reclaim them
|
||||
```
|
||||
|
||||
Sandboxes shut themselves down when idle (`auto_shutdown`, `idle_timeout_s`), and a post-setup snapshot is reused so the next run skips the image pull and dependency install. Commit a `.praisonai/environment.yaml` and the environment travels with the repo.
|
||||
|
||||
> 📖 [20 runnable examples](examples/python/managed-agents/) · manage sessions with `praisonai managed sessions list <agent-id>` or `praisonai managed sessions resume <session-id> "<prompt>"`
|
||||
|
||||
<sub>Stack framing adapted from [The Five-Layer Agent Stack](https://mer.vin/2026/07/five-layer-agent-stack-match-bug-to-right-layer/) and [Agent Harnesses vs Orbs](https://mer.vin/2026/08/agent-harnesses-vs-orbs-why-remote-sandboxes-beat-local-agent-loops/).</sub>
|
||||
|
||||
---
|
||||
|
||||
## 🌌 The PraisonAI Ecosystem
|
||||
|
||||
Start simple with the core SDK, or expand to full visual builders and dashboards when you're ready.
|
||||
@@ -416,9 +200,9 @@ Powered by 100+ LLMs (OpenAI, Anthropic, Gemini & local models).
|
||||
| 🧠 | **Planning Mode** — plan → execute → reason | `planning=True` |
|
||||
| 🔍 | **Deep Research** — multi-step autonomous research | [Docs](https://docs.praison.ai/docs/agents/deep-research) |
|
||||
| 🤖 | **External Agents** — orchestrate Claude Code, Gemini CLI, Codex | [Docs](https://docs.praison.ai/docs/code/external-agents) |
|
||||
| 🔄 | **Agent Handoffs** — seamless conversation passing | `handoffs=[other_agent]` |
|
||||
| 🔄 | **Agent Handoffs** — seamless conversation passing | `handoff=True` |
|
||||
| 🛡️ | **Guardrails** — input/output validation | [Docs](https://docs.praison.ai/docs/concepts/guardrails) |
|
||||
| | **Web Search + Fetch** — native browsing | `web=True` |
|
||||
| | **Web Search + Fetch** — native browsing | `web_search=True` |
|
||||
| 🪞 | **Self Reflection** — agent reviews its own output | [Docs](https://docs.praison.ai/docs/concepts/reflection) |
|
||||
| 🔀 | **Workflow Patterns** — route, parallel, loop, repeat | [Docs](https://docs.praison.ai/docs/concepts/agentflow) |
|
||||
| 🧠 | **Memory (zero deps)** — works out of the box | `memory=True` |
|
||||
@@ -428,9 +212,9 @@ Powered by 100+ LLMs (OpenAI, Anthropic, Gemini & local models).
|
||||
|
||||
| | Feature | How |
|
||||
|--|---------|-----|
|
||||
| 💡 | **Prompt Caching** — reduce latency + cost | `caching=True` |
|
||||
| 💡 | **Prompt Caching** — reduce latency + cost | `prompt_caching=True` |
|
||||
| 💾 | **Sessions + Auto-Save** — persistent state across restarts | `auto_save="my-project"` |
|
||||
| 💭 | **Thinking Budgets** — control reasoning depth | `agent.thinking_budget = 1024` |
|
||||
| 💭 | **Thinking Budgets** — control reasoning depth | `thinking_budget=1024` |
|
||||
| 📚 | **RAG + Quality-Based RAG** — auto quality scoring retrieval | [Docs](https://docs.praison.ai/docs/concepts/rag) |
|
||||
| 📊 | **Model Router** — auto-routes to cheapest capable model | [Docs](https://docs.praison.ai/docs/features/model-router) |
|
||||
| 🧊 | **Shadow Git Checkpoints** — auto-rollback on failure | [Docs](https://docs.praison.ai/docs/features/checkpoints) |
|
||||
@@ -557,10 +341,8 @@ from praisonaiagents import Agent, db
|
||||
|
||||
agent = Agent(
|
||||
name="Assistant",
|
||||
memory={
|
||||
"db": db(database_url="postgresql://localhost/mydb"),
|
||||
"session_id": "my-session",
|
||||
},
|
||||
db=db(database_url="postgresql://localhost/mydb"),
|
||||
session_id="my-session"
|
||||
)
|
||||
agent.chat("Hello!") # Auto-persists messages, runs, traces
|
||||
```
|
||||
@@ -1006,16 +788,6 @@ PraisonAI is built for speed, with agent instantiation in around 14μs. This red
|
||||
|
||||
---
|
||||
|
||||
<p align="center">
|
||||
<img src=".github/images/agentflow.gif" alt="PraisonAI AgentFlow" width="800" />
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<img src=".github/images/latest_ai_news_and_crawl_each_url_to_find_info.gif" alt="PraisonAI command execution" width="800" />
|
||||
</p>
|
||||
|
||||
\* `export TAVILY_API_KEY=xxxxx`
|
||||
|
||||
## 🔍 Langfuse Tracing
|
||||
|
||||
```bash
|
||||
@@ -1119,10 +891,8 @@ from praisonaiagents import Agent, db
|
||||
|
||||
agent = Agent(
|
||||
name="Assistant",
|
||||
memory={
|
||||
"db": db(database_url="postgresql://localhost/mydb"),
|
||||
"session_id": "my-session",
|
||||
},
|
||||
db=db(database_url="postgresql://localhost/mydb"),
|
||||
session_id="my-session"
|
||||
)
|
||||
```
|
||||
|
||||
@@ -1138,8 +908,8 @@ from praisonaiagents import Agent
|
||||
|
||||
agent = Agent(
|
||||
name="Assistant",
|
||||
# Enables file-based memory (no extra deps!)
|
||||
memory={"user_id": "user123"},
|
||||
memory=True, # Enables file-based memory (no extra deps!)
|
||||
user_id="user123"
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
+2
-11
@@ -8,20 +8,11 @@ PraisonAI takes security seriously. We appreciate responsible disclosure from re
|
||||
|---------|----------|-------------|
|
||||
| `praisonaiagents` | [PyPI](https://pypi.org/project/praisonaiagents/) | `src/praisonai-agents/` |
|
||||
| `praisonai` | [PyPI](https://pypi.org/project/praisonai/) | `src/praisonai/` |
|
||||
| `praisonai` | [npm](https://www.npmjs.com/package/praisonai) | [praisonai-js](https://github.com/MervinPraison/praisonai-js) (canonical); mirrored at `src/praisonai-ts/` |
|
||||
|
||||
Report npm/TypeScript vulnerabilities on **PraisonAI** (hub intake) or [praisonai-js](https://github.com/MervinPraison/praisonai-js). Fixes land in praisonai-js first.
|
||||
| `praisonai-platform` | [PyPI](https://pypi.org/project/praisonai-platform/) | `src/praisonai-platform/` |
|
||||
| `praisonai` | [npm](https://www.npmjs.com/package/praisonai) | `src/praisonai-ts/` |
|
||||
|
||||
Report issues against the **specific package** where the vulnerability exists. A platform-only issue does not necessarily affect the core SDK, and vice versa.
|
||||
|
||||
### Packages maintained in their own repositories
|
||||
|
||||
`praisonai-platform` now lives at
|
||||
[MervinPraison/PraisonAI-Platform](https://github.com/MervinPraison/PraisonAI-Platform).
|
||||
Report platform vulnerabilities through
|
||||
[that repository's advisories](https://github.com/MervinPraison/PraisonAI-Platform/security/advisories/new),
|
||||
not here — it is versioned and released independently of the SDK.
|
||||
|
||||
## In scope
|
||||
|
||||
- Authentication, authorisation, and multi-tenant isolation (e.g. workspace boundaries)
|
||||
|
||||
@@ -7,7 +7,7 @@ Regenerate with: `praisonai docs api-md --write`
|
||||
|
||||
Types:
|
||||
```python
|
||||
from praisonaiagents import ContextPolicy, GuardrailResult, HandoffConfig, HandoffCycleError, HandoffDepthError, HandoffError, HandoffInputData, HandoffResult, HandoffTimeoutError, ReflectionOutput, StepResult, ToolResult, ToolValidationError, WorkflowContext
|
||||
from praisonaiagents import ContextPolicy, GuardrailResult, HandoffConfig, HandoffCycleError, HandoffDepthError, HandoffError, HandoffInputData, HandoffResult, HandoffTimeoutError, ReflectionOutput, StepResult, TaskOutput, ToolResult, ToolValidationError, WorkflowContext
|
||||
```
|
||||
|
||||
Methods:
|
||||
@@ -16,6 +16,8 @@ Methods:
|
||||
* <code title="class HandoffConfig">HandoffConfig.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">from_dict</a>(data: Dict[str, Any]) -> 'HandoffConfig'</code>
|
||||
* <code title="class HandoffConfig">HandoffConfig.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">to_dict</a>() -> Dict[str, Any]</code>
|
||||
* <code title="class HandoffResult">HandoffResult.<a href="./src/praisonai-agents/praisonaiagents/agent/handoff.py">from_outcome</a>(outcome: AgentRunOutcome, target_agent: Optional[str] = None, source_agent: Optional[str] = None, handoff_depth: int = 0) -> 'HandoffResult'</code>
|
||||
* <code title="class TaskOutput">TaskOutput.<a href="./src/praisonai-agents/praisonaiagents/main.py">json</a>() -> Optional[str]</code>
|
||||
* <code title="class TaskOutput">TaskOutput.<a href="./src/praisonai-agents/praisonaiagents/main.py">to_dict</a>() -> dict</code>
|
||||
* <code title="class ToolResult">ToolResult.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">is_multimodal</a>() -> bool</code>
|
||||
* <code title="class ToolResult">ToolResult.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">to_dict</a>() -> Dict[str, Any]</code>
|
||||
|
||||
@@ -23,21 +25,24 @@ Methods:
|
||||
|
||||
Types:
|
||||
```python
|
||||
from praisonaiagents import Agent, AutoAgents, AutoRagAgent, ContextAgent, DeepResearchAgent, ImageAgent, PlanningAgent, PraisonAIAgents, PromptExpanderAgent, QueryRewriterAgent, create_context_agent
|
||||
from praisonaiagents import Agent, AutoAgents, AutoRagAgent, ContextAgent, DeepResearchAgent, ImageAgent, PlanningAgent, PromptExpanderAgent, QueryRewriterAgent, create_context_agent
|
||||
```
|
||||
|
||||
Methods:
|
||||
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">aclose</a>() -> None</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">add_mcp_server</a>(name: str, mcp: Any) -> Any</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">add_verification</a>(hook: Any) -> None</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">agent_id</a>() -> str</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">analyze_prompt</a>(prompt: str) -> set</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">auto_memory</a>() -> Optional[bool]</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">auto_memory</a>(value: Optional[bool]) -> None</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">background</a>() -> Optional[bool]</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">background</a>(value: Optional[bool]) -> None</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">chat_history</a>()</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">chat_history</a>(value)</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">chat_with_context</a>(message: str, context: 'ContextPack', **kwargs) -> str</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">checkpoints</a>() -> Optional[bool]</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">checkpoints</a>(value: Optional[bool]) -> None</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">clone_for_channel</a>() -> 'Agent'</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">close</a>() -> None</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">console</a>() -> Optional[Any]</code>
|
||||
@@ -71,7 +76,6 @@ Methods:
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">redo</a>() -> bool</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">refresh_tools</a>() -> List[Any]</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">remove_mcp_server</a>(name: str) -> bool</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">remove_verification</a>(name: str) -> bool</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">retrieval_config</a>() -> Optional[Any]</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">retrieve</a>(query: str, **kwargs) -> 'ContextPack'</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">rules_manager</a>() -> Optional[Any]</code>
|
||||
@@ -79,7 +83,6 @@ Methods:
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_autonomous_async</a>(prompt: str, max_iterations: Optional[int] = None, timeout_seconds: Optional[float] = None, completion_promise: Optional[str] = None, clear_context: bool = False)</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_until</a>(prompt: str, criteria: str = '', threshold: float = 8.0, max_iterations: int = 5, mode: str = 'optimize', on_iteration: Optional[Callable[[Any], None]] = None, verbose: bool = False, goal: Optional[str] = None, goal_criteria: Optional[Any] = None, judge_model: Optional[str] = None) -> 'EvaluationLoopResult'</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">run_until_async</a>(prompt: str, criteria: str, threshold: float = 8.0, max_iterations: int = 5, mode: str = 'optimize', on_iteration: Optional[Callable[[Any], None]] = None, verbose: bool = False) -> 'EvaluationLoopResult'</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">set_snapshot_root</a>(project_path: str) -> bool</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">skill_manager</a>() -> Optional[Any]</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">store_memory</a>(content: str, memory_type: str = 'short_term', action: str = 'add', **kwargs: Any) -> None</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">stream_emitter</a>() -> Optional[Any]</code>
|
||||
@@ -88,7 +91,6 @@ Methods:
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">thinking_budget</a>(value: Optional[int]) -> None</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">total_cost</a>() -> float</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">undo</a>() -> bool</code>
|
||||
* <code title="class Agent">Agent.<a href="./src/praisonai-agents/praisonaiagents/agent/agent.py">where_does_it_run</a>() -> str</code>
|
||||
* <code title="class AutoAgents">AutoAgents.<a href="./src/praisonai-agents/praisonaiagents/agents/autoagents.py">astart</a>()</code>
|
||||
* <code title="class AutoAgents">AutoAgents.<a href="./src/praisonai-agents/praisonaiagents/agents/autoagents.py">start</a>()</code>
|
||||
* <code title="class AutoRagAgent">AutoRagAgent.<a href="./src/praisonai-agents/praisonaiagents/agents/auto_rag_agent.py">achat</a>(message: str, **kwargs) -> str</code>
|
||||
@@ -177,15 +179,14 @@ Methods:
|
||||
* <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">get_schema</a>() -> Dict[str, Any]</code>
|
||||
* <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">run</a>(**kwargs) -> Any</code>
|
||||
* <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">safe_run</a>(**kwargs) -> ToolResult</code>
|
||||
* <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">to_model_output</a>(result: Any) -> Optional[Any]</code>
|
||||
* <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">validate</a>() -> bool</code>
|
||||
* <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">validate_class</a>() -> bool</code>
|
||||
* <code title="class BaseTool">BaseTool.<a href="./src/praisonai-agents/praisonaiagents/tools/base.py">validate_schema_roundtrip</a>() -> bool</code>
|
||||
* <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">__call__</a>(*args, **kwargs) -> Any</code>
|
||||
* <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">check_availability</a>() -> tuple[bool, str]</code>
|
||||
* <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">get_schema</a>() -> Dict[str, Any]</code>
|
||||
* <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">injected_params</a>() -> Dict[str, Any]</code>
|
||||
* <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">run</a>(**kwargs) -> Any</code>
|
||||
* <code title="class FunctionTool">FunctionTool.<a href="./src/praisonai-agents/praisonaiagents/tools/decorator.py">to_model_output</a>(result: Any) -> Optional[Any]</code>
|
||||
* <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">clear</a>() -> None</code>
|
||||
* <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">discover_plugins</a>() -> int</code>
|
||||
* <code title="class ToolRegistry">ToolRegistry.<a href="./src/praisonai-agents/praisonaiagents/tools/registry.py">discover_single_file_plugins</a>() -> int</code>
|
||||
@@ -240,12 +241,10 @@ from praisonaiagents import Memory, MemoryBackend, MemoryConfig
|
||||
|
||||
Methods:
|
||||
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">acommit_memory_batch</a>(writes: List[tuple]) -> None</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">build_cache_optimized_context</a>(task_descr: str, user_id: Optional[str] = None, additional: str = '', max_items: int = 3, include_cache_boundary: bool = True, include_in_output: Optional[bool] = None) -> Dict[str, str]</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">build_context_for_task</a>(task_descr: str, user_id: Optional[str] = None, additional: str = '', max_items: int = 3, include_in_output: Optional[bool] = None) -> str</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">calculate_quality_metrics</a>(output: str, expected_output: str, llm: Optional[str] = None, custom_prompt: Optional[str] = None) -> Dict[str, float]</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">close_connections</a>()</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">commit_memory_batch</a>(writes: List[tuple]) -> None</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">compute_quality_score</a>(completeness: float, relevance: float, clarity: float, accuracy: float, weights: Dict[str, float] = None) -> float</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">delete_long_term</a>(memory_id: str) -> bool</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">delete_memories</a>(memory_ids: List[str]) -> int</code>
|
||||
@@ -253,13 +252,9 @@ Methods:
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">delete_memory</a>(memory_id: str, memory_type: Optional[str] = None) -> bool</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">delete_short_term</a>(memory_id: str) -> bool</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">finalize_task_output</a>(content: str, agent_name: str, quality_score: float, threshold: float = 0.7, metrics: Dict[str, Any] = None, task_id: str = None)</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">forget</a>(**kwargs) -> int</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">get_all_memories</a>() -> List[Dict[str, Any]]</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">get_context</a>(query: Optional[str] = None, **kwargs) -> str</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">get_learn_context</a>() -> str</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">learn</a>()</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">recall</a>(query: str, **kwargs) -> List[Dict[str, Any]]</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">remember</a>(content: str, **kwargs) -> str</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">reset_all</a>()</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">reset_entity_only</a>()</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">reset_long_term</a>()</code>
|
||||
@@ -267,8 +262,8 @@ Methods:
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">reset_user_memory</a>()</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search</a>(query: str, user_id: Optional[str] = None, agent_id: Optional[str] = None, run_id: Optional[str] = None, limit: int = 5, rerank: bool = False, **kwargs) -> List[Dict[str, Any]]</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search_entity</a>(query: str, limit: int = 5) -> List[Dict[str, Any]]</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search_long_term</a>(query: str, limit: int = 5, relevance_cutoff: float = 0.0, min_quality: float = 0.0, rerank: bool = False, metadata_filter: Optional[Dict[str, Any]] = None, user_id: Optional[str] = None, **kwargs) -> List[Dict[str, Any]]</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search_short_term</a>(query: str, limit: int = 5, min_quality: float = 0.0, relevance_cutoff: float = 0.0, rerank: bool = False, metadata_filter: Optional[Dict[str, Any]] = None, user_id: Optional[str] = None, **kwargs) -> List[Dict[str, Any]]</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search_long_term</a>(query: str, limit: int = 5, relevance_cutoff: float = 0.0, min_quality: float = 0.0, rerank: bool = False, **kwargs) -> List[Dict[str, Any]]</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search_short_term</a>(query: str, limit: int = 5, min_quality: float = 0.0, relevance_cutoff: float = 0.0, rerank: bool = False, **kwargs) -> List[Dict[str, Any]]</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search_user_memory</a>(user_id: str, query: str, limit: int = 5, rerank: bool = False, **kwargs) -> List[Dict[str, Any]]</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">search_with_quality</a>(query: str, min_quality: float = 0.0, memory_type: Literal['short', 'long'] = 'long', limit: int = 5) -> List[Dict[str, Any]]</code>
|
||||
* <code title="class Memory">Memory.<a href="./src/praisonai-agents/praisonaiagents/memory/memory.py">store_entity</a>(name: str, type_: str, desc: str, relations: str)</code>
|
||||
@@ -468,7 +463,7 @@ Methods:
|
||||
|
||||
Types:
|
||||
```python
|
||||
from praisonaiagents import SkillLoader, SkillsConfig
|
||||
from praisonaiagents import SkillLoader, SkillManager, SkillMetadata, SkillProperties, SkillsConfig
|
||||
```
|
||||
|
||||
Methods:
|
||||
@@ -480,6 +475,54 @@ Methods:
|
||||
* <code title="class SkillLoader">SkillLoader.<a href="./src/praisonai-agents/praisonaiagents/skills/loader.py">load_metadata</a>(skill_path: str) -> Optional[LoadedSkill]</code>
|
||||
* <code title="class SkillLoader">SkillLoader.<a href="./src/praisonai-agents/praisonaiagents/skills/loader.py">load_references</a>(skill: LoadedSkill) -> dict</code>
|
||||
* <code title="class SkillLoader">SkillLoader.<a href="./src/praisonai-agents/praisonaiagents/skills/loader.py">load_scripts</a>(skill: LoadedSkill) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">activate</a>(skill: LoadedSkill) -> bool</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">activate_by_name</a>(name: str) -> bool</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">add_bundle</a>(manifest: 'BundleManifest') -> None</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">add_skill</a>(skill_path: str) -> Optional[LoadedSkill]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">add_skill_by_name</a>(name: str, skill_dirs: Optional[List[str]] = None, include_defaults: bool = True) -> Optional[LoadedSkill]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">approve</a>(identifier: str) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">archive_skill</a>(name: str) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">bundle_names</a>() -> List[str]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">bundles</a>() -> List['BundleManifest']</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">clear</a>() -> None</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">create</a>(name: str, content: str, category: Optional[str] = None, propose: Optional[bool] = None) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">create_skill</a>(name: str, content: str, category: str = None, agent_created: bool = True, propose: Optional[bool] = None, base_dir: Optional[str] = None) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">delete</a>(name: str, propose: Optional[bool] = None) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">delete_skill</a>(name: str, hard: bool = False, propose: Optional[bool] = None) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">discover</a>(skill_dirs: Optional[List[str]] = None, include_defaults: bool = True) -> int</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">discover_bundles</a>(skill_dirs: Optional[List[str]] = None, include_defaults: bool = True) -> int</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">edit</a>(name: str, content: str, propose: Optional[bool] = None) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">edit_skill</a>(name: str, content: str, propose: Optional[bool] = None) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_allowed_tools</a>(name: str) -> List[str]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_available_skills</a>() -> List[SkillMetadata]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_available_skills_by_state</a>(state: SkillState) -> List[LoadedSkill]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_bundle</a>(name: str) -> Optional['BundleManifest']</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_bundle_instructions</a>() -> List[str]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_instructions</a>(name: str) -> Optional[str]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_skill</a>(name: str) -> Optional[LoadedSkill]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_skills_diagnostics</a>() -> Dict[str, ValidationResult]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">get_user_invocable_skills</a>() -> List[LoadedSkill]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">invoke</a>(name: str, raw_args: str = '', session_id: Optional[str] = None, shell_exec: bool = False) -> Optional[str]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">list_archived_skills</a>() -> List[str]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">list_pending</a>() -> List[dict]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">load_resources</a>(name: str) -> bool</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">patch</a>(name: str, old_string: str, new_string: str, file_path: Optional[str] = None, replace_all: bool = False, propose: Optional[bool] = None) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">patch_skill</a>(name: str, old_string: str, new_string: str, file_path: str = None, replace_all: bool = False, propose: Optional[bool] = None) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">reject</a>(identifier: str) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">remove_file</a>(name: str, file_path: str, propose: Optional[bool] = None) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">remove_skill_file</a>(name: str, file_path: str, propose: Optional[bool] = None) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">resolve</a>(selectors: List[str]) -> List[str]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">restore_skill</a>(name: str, skill_dir: Optional[str] = None) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">rollback_skill</a>(name: str) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">skill_names</a>() -> List[str]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">skills</a>() -> List[LoadedSkill]</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">to_prompt</a>() -> str</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">validate_skill_capabilities</a>(skill_name: str, force_refresh: bool = False) -> ValidationResult</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">write_file</a>(name: str, file_path: str, file_content: str, propose: Optional[bool] = None) -> dict</code>
|
||||
* <code title="class SkillManager">SkillManager.<a href="./src/praisonai-agents/praisonaiagents/skills/manager.py">write_skill_file</a>(name: str, file_path: str, file_content: str, propose: Optional[bool] = None) -> dict</code>
|
||||
* <code title="class SkillMetadata">SkillMetadata.<a href="./src/praisonai-agents/praisonaiagents/skills/models.py">from_properties</a>(props: SkillProperties) -> 'SkillMetadata'</code>
|
||||
* <code title="class SkillProperties">SkillProperties.<a href="./src/praisonai-agents/praisonaiagents/skills/models.py">idle_days</a>() -> Optional[float]</code>
|
||||
* <code title="class SkillProperties">SkillProperties.<a href="./src/praisonai-agents/praisonaiagents/skills/models.py">to_dict</a>() -> dict</code>
|
||||
* <code title="class SkillsConfig">SkillsConfig.<a href="./src/praisonai-agents/praisonaiagents/config/feature_configs.py">to_dict</a>() -> Dict[str, Any]</code>
|
||||
|
||||
# Session
|
||||
@@ -525,7 +568,6 @@ Methods:
|
||||
* <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">get_prompts</a>() -> List[dict]</code>
|
||||
* <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">get_resources</a>() -> List[dict]</code>
|
||||
* <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">get_tools</a>() -> List[Callable]</code>
|
||||
* <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">list_active_server_names</a>() -> set</code>
|
||||
* <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">shutdown</a>()</code>
|
||||
* <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">to_openai_tool</a>()</code>
|
||||
* <code title="class MCP">MCP.<a href="./src/praisonai-agents/praisonaiagents/mcp/mcp.py">with_tool_prefix</a>(prefix: str) -> 'MCP'</code>
|
||||
@@ -689,7 +731,7 @@ Methods:
|
||||
|
||||
Types:
|
||||
```python
|
||||
from praisonaiagents import AgentAppConfig, AgentAppProtocol, AgentFlow, AgentManager, AgentOSConfig, AgentOSProtocol, AgentTeam, AutoApproveBackend, EmbeddingResult, RetryBackoffConfig, RunOutcome, __version__, aembedding, aembeddings, embedding, embeddings, get_dimensions
|
||||
from praisonaiagents import AgentAppConfig, AgentAppProtocol, AgentFlow, AgentManager, AgentOSConfig, AgentOSProtocol, AgentTeam, AutoApproveBackend, EmbeddingResult, RetryBackoffConfig, __version__, aembedding, aembeddings, embedding, embeddings, get_dimensions
|
||||
```
|
||||
|
||||
Methods:
|
||||
@@ -712,7 +754,6 @@ Methods:
|
||||
* <code title="class AgentFlow">AgentFlow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">to_dict</a>() -> Dict[str, Any]</code>
|
||||
* <code title="class AgentFlow">AgentFlow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">verbose</a>() -> bool</code>
|
||||
* <code title="class AgentFlow">AgentFlow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">verbose</a>(value: bool)</code>
|
||||
* <code title="class AgentFlow">AgentFlow.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">where_does_it_run</a>() -> str</code>
|
||||
* <code title="class AgentOSProtocol">AgentOSProtocol.<a href="./src/praisonai-agents/praisonaiagents/app/protocols.py">get_app</a>() -> Any</code>
|
||||
* <code title="class AgentOSProtocol">AgentOSProtocol.<a href="./src/praisonai-agents/praisonaiagents/app/protocols.py">serve</a>(host: Optional[str] = None, port: Optional[int] = None, reload: bool = False, **kwargs: Any) -> None</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">aannounce_completion</a>(agent_id: str, task_id: str, result: Any, success: bool = True, error: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None) -> None</code>
|
||||
@@ -724,7 +765,6 @@ Methods:
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">arun_task</a>(task_id)</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">aspawn_sub_agent</a>(agent: Agent, task: Any, completion_callback: Optional[Callable[[SubAgentCompletionEvent], Any]] = None, metadata: Optional[Dict[str, Any]] = None) -> SpawnedSubAgent</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">astart</a>(content = None, return_dict = False, **kwargs)</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">astart_for_each</a>(inputs, **kwargs)</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">await_for_completions</a>(timeout: Optional[float] = None, agent_ids: Optional[List[str]] = None) -> List[SubAgentCompletionEvent]</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">clean_json_output</a>(output: str) -> str</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">clear_state</a>() -> None</code>
|
||||
@@ -749,28 +789,22 @@ Methods:
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">get_token_usage_summary</a>() -> Dict[str, Any]</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">has_state</a>(key: str) -> bool</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">increment_state</a>(key: str, amount: float = 1, default: float = 0) -> float</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">launch</a>(path: str = '/agents', port: int = 8000, host: str = '127.0.0.1', debug: bool = False, protocol: str = 'http')</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">launch</a>(path: str = '/agents', port: int = 8000, host: str = '0.0.0.0', debug: bool = False, protocol: str = 'http')</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">restore_session_state</a>(session_id: str) -> bool</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">run</a>(content = None, return_dict = False, **kwargs)</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">run_all_tasks</a>()</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">run_task</a>(task_id)</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">save_output_to_file</a>(task, task_output)</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">save_session_state</a>(session_id: str, include_memory: bool = True) -> bool</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">save_session_state</a>(session_id: str, include_memory: bool = True) -> None</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">set_state</a>(key: str, value: Any) -> None</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">spawn_sub_agent</a>(agent: Agent, task: Any, completion_callback: Optional[Callable[[SubAgentCompletionEvent], Any]] = None, metadata: Optional[Dict[str, Any]] = None) -> SpawnedSubAgent</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">start</a>(content = None, return_dict = False, output = None, **kwargs)</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">start_for_each</a>(inputs, **kwargs)</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">stream_emitter</a>()</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">todo_list</a>()</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">update_plan_step_status</a>(step_id: str, status: str) -> bool</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">update_state</a>(updates: Dict) -> None</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">wait_for_completions</a>(timeout: Optional[float] = None, agent_ids: Optional[List[str]] = None) -> List[SubAgentCompletionEvent]</code>
|
||||
* <code title="class AgentTeam">AgentTeam.<a href="./src/praisonai-agents/praisonaiagents/agents/agents.py">where_does_it_run</a>() -> str</code>
|
||||
* <code title="class AutoApproveBackend">AutoApproveBackend.<a href="./src/praisonai-agents/praisonaiagents/approval/backends.py">request_approval</a>(request: ApprovalRequest) -> ApprovalDecision</code>
|
||||
* <code title="class AutoApproveBackend">AutoApproveBackend.<a href="./src/praisonai-agents/praisonaiagents/approval/backends.py">request_approval_sync</a>(request: ApprovalRequest) -> ApprovalDecision</code>
|
||||
* <code title="class RunOutcome">RunOutcome.<a href="./src/praisonai-agents/praisonaiagents/agent/run_outcome.py">completed</a>(output: Optional[str] = None) -> 'RunOutcome'</code>
|
||||
* <code title="class RunOutcome">RunOutcome.<a href="./src/praisonai-agents/praisonaiagents/agent/run_outcome.py">from_exception</a>(exc: BaseException, output: Optional[str] = None) -> 'RunOutcome'</code>
|
||||
* <code title="class RunOutcome">RunOutcome.<a href="./src/praisonai-agents/praisonaiagents/agent/run_outcome.py">succeeded</a>() -> bool</code>
|
||||
* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/embedding/embed.py">aembedding</a>(input: Union[str, List[str]], model: str = 'text-embedding-3-small', dimensions: Optional[int] = None, encoding_format: str = 'float', timeout: float = 600.0, api_key: Optional[str] = None, api_base: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None, **kwargs) -> EmbeddingResult</code>
|
||||
* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/embedding/embed.py">aembeddings</a>(input: Union[str, List[str]], model: str = 'text-embedding-3-small', dimensions: Optional[int] = None, encoding_format: str = 'float', timeout: float = 600.0, api_key: Optional[str] = None, api_base: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None, **kwargs) -> EmbeddingResult</code>
|
||||
* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/embedding/dimensions.py">get_dimensions</a>(model_name: str) -> int</code>
|
||||
@@ -779,7 +813,7 @@ Methods:
|
||||
|
||||
Types:
|
||||
```python
|
||||
from praisonai import Agent, AgentApp, AgentOS, AnthropicManagedAgent, DB, HostedAgent, HostedAgentConfig, LocalAgent, LocalAgentConfig, LocalManagedAgent, LocalManagedConfig, ManagedAgent, ManagedConfig, __version__, arun, run
|
||||
from praisonai import Agent, AgentApp, AgentOS, AnthropicManagedAgent, CloudProvider, DB, Deploy, DeployConfig, DeployType, HostedAgent, HostedAgentConfig, LocalAgent, LocalAgentConfig, LocalManagedAgent, LocalManagedConfig, ManagedAgent, ManagedConfig, __version__, arun, run
|
||||
```
|
||||
|
||||
# CLI
|
||||
@@ -847,13 +881,11 @@ Methods:
|
||||
* <code title="cli">praisonai managed list <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
|
||||
* <code title="cli">praisonai managed managed-callback <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
|
||||
* <code title="cli">praisonai managed multi <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
|
||||
* <code title="cli">praisonai managed ps <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
|
||||
* <code title="cli">praisonai managed restore <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
|
||||
* <code title="cli">praisonai managed resume <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
|
||||
* <code title="cli">praisonai managed run <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
|
||||
* <code title="cli">praisonai managed save <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
|
||||
* <code title="cli">praisonai managed show <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
|
||||
* <code title="cli">praisonai managed stop <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
|
||||
* <code title="cli">praisonai managed update <a href="./src/praisonai/praisonai/cli/commands/managed.py">--help</a></code>
|
||||
* <code title="cli">praisonai n8n export <a href="./src/praisonai/praisonai/cli/commands/n8n.py">--help</a></code>
|
||||
* <code title="cli">praisonai n8n import <a href="./src/praisonai/praisonai/cli/commands/n8n.py">--help</a></code>
|
||||
@@ -883,7 +915,6 @@ Methods:
|
||||
* <code title="cli">praisonai recipe list <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
|
||||
* <code title="cli">praisonai recipe optimize <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
|
||||
* <code title="cli">praisonai recipe run <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
|
||||
* <code title="cli">praisonai recipe runs <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
|
||||
* <code title="cli">praisonai recipe serve <a href="./src/praisonai/praisonai/cli/commands/recipe.py">--help</a></code>
|
||||
* <code title="cli">praisonai replay cleanup <a href="./src/praisonai/praisonai/cli/commands/replay.py">--help</a></code>
|
||||
* <code title="cli">praisonai replay context <a href="./src/praisonai/praisonai/cli/commands/replay.py">--help</a></code>
|
||||
@@ -900,11 +931,7 @@ Methods:
|
||||
* <code title="cli">praisonai schedule describe <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai schedule list <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai schedule logs <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai schedule pause <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai schedule remove <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai schedule restart <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai schedule resume <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai schedule runs <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai schedule schedule-callback <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai schedule start <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai schedule stats <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
@@ -913,7 +940,10 @@ Methods:
|
||||
* <code title="cli">praisonai schedule suggestion-dismiss <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai schedule suggestion-propose <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai schedule suggestions <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai schedule update <a href="./src/praisonai/praisonai/cli/commands/schedule.py">--help</a></code>
|
||||
* <code title="cli">praisonai standardise check <a href="./src/praisonai/praisonai/cli/commands/standardise.py">--help</a></code>
|
||||
* <code title="cli">praisonai standardise fix <a href="./src/praisonai/praisonai/cli/commands/standardise.py">--help</a></code>
|
||||
* <code title="cli">praisonai standardise init <a href="./src/praisonai/praisonai/cli/commands/standardise.py">--help</a></code>
|
||||
* <code title="cli">praisonai standardise report <a href="./src/praisonai/praisonai/cli/commands/standardise.py">--help</a></code>
|
||||
* <code title="cli">praisonai validate check <a href="./src/praisonai/praisonai/cli/commands/validate.py">--help</a></code>
|
||||
* <code title="cli">praisonai validate schema <a href="./src/praisonai/praisonai/cli/commands/validate.py">--help</a></code>
|
||||
* <code title="cli">praisonai validate validate <a href="./src/praisonai/praisonai/cli/commands/validate.py">--help</a></code>
|
||||
|
||||
@@ -1,10 +0,0 @@
|
||||
# Deployment infra has moved
|
||||
|
||||
Deployment assets are no longer at the monorepo root.
|
||||
|
||||
| Asset | New location |
|
||||
|-------|----------------|
|
||||
| Gateway Helm chart | [`src/praisonai-bot/infra/helm/praisonai-gateway/`](../src/praisonai-bot/infra/helm/praisonai-gateway/) |
|
||||
| Agents API Helm, Compose, Starters | [`src/praisonai-deploy/infra/`](../src/praisonai-deploy/infra/) |
|
||||
|
||||
See [`src/praisonai-deploy/infra/README.md`](../src/praisonai-deploy/infra/README.md).
|
||||
@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
|
||||
# Install Python packages (using latest versions)
|
||||
RUN pip install --no-cache-dir \
|
||||
praisonai_tools \
|
||||
"praisonai>=4.7.1" \
|
||||
"praisonai>=4.6.155" \
|
||||
"praisonai[chat]" \
|
||||
"embedchain[github,youtube]"
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@ RUN mkdir -p /root/.praison
|
||||
# Install Python packages (using latest versions)
|
||||
RUN pip install --no-cache-dir \
|
||||
praisonai_tools \
|
||||
"praisonai>=4.7.1" \
|
||||
"praisonai>=4.6.155" \
|
||||
"praisonai[ui]" \
|
||||
"praisonai[chat]" \
|
||||
"praisonai[realtime]" \
|
||||
|
||||
@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
|
||||
# Install Python packages (using latest versions)
|
||||
RUN pip install --no-cache-dir \
|
||||
praisonai_tools \
|
||||
"praisonai>=4.7.1" \
|
||||
"praisonai>=4.6.155" \
|
||||
"praisonai[ui]" \
|
||||
"praisonai[crewai]"
|
||||
|
||||
|
||||
@@ -178,19 +178,19 @@ def example_url_parsing():
|
||||
print("\n=== Example 9: URL Parsing ===")
|
||||
|
||||
# Memory supports URL connection strings
|
||||
# Supported schemes: sqlite://, mongodb://, mongodb+srv://
|
||||
# Supported: postgresql://, redis://, sqlite:///, mongodb://
|
||||
agent = Agent(
|
||||
instructions="You are a database-backed assistant",
|
||||
memory="mongodb://user:password@localhost:27017/praisonai",
|
||||
memory="postgresql://postgres:password@localhost:5432/praisonai",
|
||||
)
|
||||
print("Memory URL parsed: memory enabled")
|
||||
|
||||
# Also works with presets
|
||||
agent2 = Agent(
|
||||
instructions="You are a sqlite-backed assistant",
|
||||
memory="sqlite", # Preset name
|
||||
instructions="You are a redis-backed assistant",
|
||||
memory="redis", # Preset name
|
||||
)
|
||||
print("Memory preset 'sqlite': configured")
|
||||
print("Memory preset 'redis': configured")
|
||||
|
||||
|
||||
def example_knowledge_sources():
|
||||
|
||||
@@ -8,15 +8,15 @@ agent = Agent(
|
||||
)
|
||||
|
||||
# With preset
|
||||
agent_sqlite = Agent(
|
||||
agent_redis = Agent(
|
||||
instructions="You are a helpful assistant.",
|
||||
memory="sqlite", # Uses sqlite preset
|
||||
memory="redis", # Uses redis preset
|
||||
)
|
||||
|
||||
# With URL
|
||||
agent_mongo = Agent(
|
||||
agent_postgres = Agent(
|
||||
instructions="You are a helpful assistant.",
|
||||
memory="mongodb://localhost/mydb", # URL auto-detected
|
||||
memory="postgresql://localhost/mydb", # URL auto-detected
|
||||
)
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -36,12 +36,6 @@ if __name__ == "__main__":
|
||||
print(f"Custom agent max_rpm: {agent.max_rpm}")
|
||||
print(f"Custom agent max_execution_time: {agent.max_execution_time}")
|
||||
print(f"Custom agent max_retry_limit: {agent.max_retry_limit}")
|
||||
|
||||
# max_rpm auto-creates a live RateLimiter (not just a stored number)
|
||||
assert agent_rate_limited.max_rpm == 10
|
||||
assert agent_rate_limited._rate_limiter is not None
|
||||
assert agent_rate_limited._rate_limiter.requests_per_minute == 10
|
||||
print(f"Rate-limited agent limiter: {agent_rate_limited._rate_limiter}")
|
||||
|
||||
# Test custom agent
|
||||
print("\n--- Custom Execution ---")
|
||||
|
||||
@@ -1,32 +1,5 @@
|
||||
# MCP Server Examples
|
||||
|
||||
## Install (SHA-256)
|
||||
|
||||
Pin GitHub Release **v0.6.0** and verify `SHA256SUMS`. Website `install.sh` / `install.ps1` abort on mismatch.
|
||||
|
||||
https://github.com/LinespottingOrg/GrokBuildRemote-Agents/releases/tag/v0.6.0
|
||||
https://github.com/LinespottingOrg/GrokBuildRemote-Agents/blob/main/docs/PINNED-INSTALL.md
|
||||
|
||||
```
|
||||
96cef605d3e030ccef99d27ea6240e0d3b668dd045e6b5b9e585c9fd03c6ef23 gbr-agent-darwin-amd64
|
||||
de7e065ef2cf6877b3b2cd04679a67b627f876337f529247e236204543e4062c gbr-agent-darwin-arm64
|
||||
a50a5c41993e6531a3b477eb409ccc845212bf541384dc803061c80657f86719 gbr-agent-linux-amd64
|
||||
5bfd22c7110234942c4c02ff8154b836d0af45a9422c178a4f52010187d40061 gbr-agent-linux-arm64
|
||||
f773b89fd31310172b756e0593e0f3b2382b0a3440af2a7d0a8b3073b0c23e27 gbr-agent-windows-amd64.exe
|
||||
8fb9efcbc7e2ac91c11964944bf0f45e31bb23f4356d9dcb4b305d7cb9b0fe8c gbr-agent-windows-arm64.exe
|
||||
```
|
||||
|
||||
```bash
|
||||
VER=v0.6.0
|
||||
BASE=https://github.com/LinespottingOrg/GrokBuildRemote-Agents/releases/download/$VER
|
||||
# swap darwin-arm64 for your OS/arch
|
||||
curl -fsSL -o gbr-agent-darwin-arm64 "$BASE/gbr-agent-darwin-arm64"
|
||||
curl -fsSL -o SHA256SUMS "$BASE/SHA256SUMS"
|
||||
shasum -a 256 -c SHA256SUMS --ignore-missing
|
||||
gbr-agent pair && gbr-agent run
|
||||
```
|
||||
|
||||
|
||||
Examples demonstrating the MCP Server v2 features per MCP Protocol Version 2025-11-25.
|
||||
|
||||
## Features Demonstrated
|
||||
@@ -157,19 +130,3 @@ These examples comply with MCP Protocol Version 2025-11-25:
|
||||
- `destructiveHint`: true
|
||||
- `idempotentHint`: false
|
||||
- `openWorldHint`: true
|
||||
|
||||
|
||||
## Build Remote Agent (`gbr_pair.py`)
|
||||
|
||||
Pair a phone running [Build Remote Agent](https://grokbuildremote.com/) to a PraisonAI agent via MCP stdio `gbr-mcp` (protocol `gbr/1`). Requires `gbr-agent pair && gbr-agent run`. Phone is spectator. Never put mailbox keys in the example.
|
||||
|
||||
```bash
|
||||
python gbr_pair.py
|
||||
```
|
||||
|
||||
## What the phone sees
|
||||
|
||||
**Terminal windows** on this PC (machine-wide mailbox). Not headless OpenCode / CodeNomad sidecar / Electron. `:8788` in a sidecar is Bot API JSON, not a transcript.
|
||||
|
||||
https://github.com/LinespottingOrg/GrokBuildRemote-Agents/blob/main/docs/WHAT-THE-PHONE-SEES.md
|
||||
https://grokbuildremote.com/integrations.html
|
||||
@@ -1,76 +0,0 @@
|
||||
"""
|
||||
Build Remote Agent pairing example.
|
||||
|
||||
Pair a phone (Build Remote Agent) to this PraisonAI session through the
|
||||
free MIT gbr-agent. Protocol gbr/1. Phone is spectator + veto.
|
||||
|
||||
Requirements:
|
||||
- gbr-agent v0.6.0+ (`gbr-agent pair && gbr-agent run`)
|
||||
- GrokBuildRemote-Agents cloned; `npm install` in mcp/gbr-mcp
|
||||
- pip install praisonaiagents[mcp]
|
||||
|
||||
Usage:
|
||||
python gbr_pair.py
|
||||
|
||||
Never put mailbox keys in this file. Phone Settings → Bot API is the
|
||||
only place the relay key is copied.
|
||||
|
||||
Independent product by Linespotting AB. Not affiliated with xAI or SpaceX.
|
||||
https://grokbuildremote.com/
|
||||
"""
|
||||
|
||||
from praisonaiagents import Agent, MCP
|
||||
|
||||
# Clone https://github.com/LinespottingOrg/GrokBuildRemote-Agents.git
|
||||
|
||||
## Install (SHA-256)
|
||||
|
||||
Pin GitHub Release **v0.6.0** and verify `SHA256SUMS`. Website `install.sh` / `install.ps1` abort on mismatch.
|
||||
|
||||
https://github.com/LinespottingOrg/GrokBuildRemote-Agents/releases/tag/v0.6.0
|
||||
https://github.com/LinespottingOrg/GrokBuildRemote-Agents/blob/main/docs/PINNED-INSTALL.md
|
||||
|
||||
```
|
||||
96cef605d3e030ccef99d27ea6240e0d3b668dd045e6b5b9e585c9fd03c6ef23 gbr-agent-darwin-amd64
|
||||
de7e065ef2cf6877b3b2cd04679a67b627f876337f529247e236204543e4062c gbr-agent-darwin-arm64
|
||||
a50a5c41993e6531a3b477eb409ccc845212bf541384dc803061c80657f86719 gbr-agent-linux-amd64
|
||||
5bfd22c7110234942c4c02ff8154b836d0af45a9422c178a4f52010187d40061 gbr-agent-linux-arm64
|
||||
f773b89fd31310172b756e0593e0f3b2382b0a3440af2a7d0a8b3073b0c23e27 gbr-agent-windows-amd64.exe
|
||||
8fb9efcbc7e2ac91c11964944bf0f45e31bb23f4356d9dcb4b305d7cb9b0fe8c gbr-agent-windows-arm64.exe
|
||||
```
|
||||
|
||||
```bash
|
||||
VER=v0.6.0
|
||||
BASE=https://github.com/LinespottingOrg/GrokBuildRemote-Agents/releases/download/$VER
|
||||
# swap darwin-arm64 for your OS/arch
|
||||
curl -fsSL -o gbr-agent-darwin-arm64 "$BASE/gbr-agent-darwin-arm64"
|
||||
curl -fsSL -o SHA256SUMS "$BASE/SHA256SUMS"
|
||||
shasum -a 256 -c SHA256SUMS --ignore-missing
|
||||
gbr-agent pair && gbr-agent run
|
||||
```
|
||||
|
||||
# then point args at mcp/gbr-mcp/bin/gbr-mcp.js (loopback stdio).
|
||||
gbr = Agent(
|
||||
instructions=(
|
||||
"You can attach a phone spectator via Build Remote Agent. "
|
||||
"Use GBR tools only to diagnose or attach the local Bot API "
|
||||
"at 127.0.0.1:8788. Do not request mailbox keys."
|
||||
),
|
||||
llm="gpt-4o-mini",
|
||||
tools=MCP(
|
||||
"node",
|
||||
args=["GrokBuildRemote-Agents/mcp/gbr-mcp/bin/gbr-mcp.js"],
|
||||
),
|
||||
)
|
||||
|
||||
if __name__ == "__main__":
|
||||
gbr.start(
|
||||
"Check Build Remote Agent health on 127.0.0.1:8788 and list sessions."
|
||||
)
|
||||
|
||||
## What the phone sees
|
||||
|
||||
**Terminal windows** on this PC (machine-wide mailbox). Not headless OpenCode / CodeNomad sidecar / Electron. `:8788` in a sidecar is Bot API JSON, not a transcript.
|
||||
|
||||
https://github.com/LinespottingOrg/GrokBuildRemote-Agents/blob/main/docs/WHAT-THE-PHONE-SEES.md
|
||||
https://grokbuildremote.com/integrations.html
|
||||
@@ -1,110 +0,0 @@
|
||||
"""
|
||||
HOL Guard Tool Policy Example - PraisonAI Agents
|
||||
|
||||
Demonstrates using HOL Guard (an optional, external runtime security engine)
|
||||
at the existing `wrap_tool_call` middleware boundary to inspect command-bearing
|
||||
tool calls *before* they execute.
|
||||
|
||||
HOL Guard is installed and versioned separately. Its side-effect-free CLI can
|
||||
classify a shell command before execution:
|
||||
|
||||
hol-guard command test '<command>' --json
|
||||
|
||||
Fail-closed policy: the wrapped tool only runs when Guard returns an explicit
|
||||
allow/benign classification. Review/block/unknown verdicts, malformed output,
|
||||
timeouts, or CLI failures all short-circuit the call so the tool never runs.
|
||||
|
||||
pip install hol-guard # optional, external dependency
|
||||
"""
|
||||
|
||||
import json
|
||||
import shutil
|
||||
import subprocess
|
||||
|
||||
from praisonaiagents import Agent, tool
|
||||
from praisonaiagents.hooks import wrap_tool_call, ToolRequest, ToolResponse
|
||||
|
||||
|
||||
COMMAND_BEARING_TOOLS = {"run_shell"}
|
||||
GUARD_TIMEOUT_SECONDS = 10
|
||||
|
||||
|
||||
@tool
|
||||
def run_shell(command: str) -> str:
|
||||
"""Run a shell command and return its output."""
|
||||
result = subprocess.run(
|
||||
command, shell=True, capture_output=True, text=True
|
||||
)
|
||||
return result.stdout or result.stderr
|
||||
|
||||
|
||||
def _inspect_with_hol_guard(command: str) -> bool:
|
||||
"""Return True only if HOL Guard explicitly allows the command.
|
||||
|
||||
Fails closed (returns False) on any ambiguity: missing CLI, non-zero exit,
|
||||
timeout, malformed JSON, or a non-allow verdict.
|
||||
"""
|
||||
if not shutil.which("hol-guard"):
|
||||
return False
|
||||
|
||||
try:
|
||||
completed = subprocess.run(
|
||||
["hol-guard", "command", "test", command, "--json"],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=GUARD_TIMEOUT_SECONDS,
|
||||
)
|
||||
except (subprocess.TimeoutExpired, OSError):
|
||||
return False
|
||||
|
||||
if completed.returncode != 0:
|
||||
return False
|
||||
|
||||
try:
|
||||
verdict = json.loads(completed.stdout)
|
||||
except (json.JSONDecodeError, ValueError):
|
||||
return False
|
||||
|
||||
if not isinstance(verdict, dict):
|
||||
return False
|
||||
|
||||
decision = str(verdict.get("decision", "")).lower()
|
||||
return decision in ("allow", "benign")
|
||||
|
||||
|
||||
@wrap_tool_call
|
||||
def hol_guard_tool_policy(request: ToolRequest, call_next):
|
||||
"""Gate command-bearing tools through HOL Guard before execution."""
|
||||
if request.tool_name not in COMMAND_BEARING_TOOLS:
|
||||
return call_next(request)
|
||||
|
||||
command = request.arguments.get("command", "")
|
||||
|
||||
if _inspect_with_hol_guard(command):
|
||||
return call_next(request)
|
||||
|
||||
blocked_message = "Blocked by HOL Guard: command was not explicitly allowed."
|
||||
# Surface the denial in `result` too: the agent tool executor returns
|
||||
# `ToolResponse.result` to the model and discards `error`, so a denial with
|
||||
# only `error` set would reach the model as a null result. Keeping `error`
|
||||
# populated preserves the signal for after_tool hooks and logging.
|
||||
return ToolResponse(
|
||||
tool_name=request.tool_name,
|
||||
result=blocked_message,
|
||||
error=blocked_message,
|
||||
context=request.context,
|
||||
)
|
||||
|
||||
|
||||
agent = Agent(
|
||||
name="GuardedShellBot",
|
||||
instructions="You run shell commands only when they are safe.",
|
||||
tools=[run_shell],
|
||||
hooks=[hol_guard_tool_policy],
|
||||
)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
print("HOL Guard tool policy registered on 'run_shell'.")
|
||||
print("Commands are only executed when Guard returns an explicit allow.")
|
||||
print("\n✓ HOL Guard example complete")
|
||||
+11
-12
@@ -1,18 +1,16 @@
|
||||
"""
|
||||
Chroma Knowledge Store - Agent-First Example
|
||||
Qdrant Knowledge Store - Agent-First Example
|
||||
|
||||
Demonstrates using Chroma (a shipped vector store) for knowledge-based RAG
|
||||
with an Agent.
|
||||
|
||||
To use a provider that is not shipped (e.g. Qdrant), register an adapter
|
||||
first with ``register_knowledge_adapter("qdrant", MyQdrantAdapter)`` and then
|
||||
pass ``"provider": "qdrant"``.
|
||||
Demonstrates using Qdrant for knowledge-based RAG with an Agent.
|
||||
|
||||
Requirements:
|
||||
pip install "praisonai[tools]"
|
||||
|
||||
Docker Setup:
|
||||
docker run -d --name praison-qdrant -p 6333:6333 qdrant/qdrant
|
||||
|
||||
Run:
|
||||
python knowledge_chroma.py
|
||||
python knowledge_qdrant.py
|
||||
|
||||
Expected Output:
|
||||
Agent responds using knowledge from documents
|
||||
@@ -46,16 +44,17 @@ doc_path = os.path.join(temp_dir, "guide.txt")
|
||||
with open(doc_path, "w") as f:
|
||||
f.write(sample_doc)
|
||||
|
||||
print("=== Chroma Knowledge Store Demo (Agent-First) ===")
|
||||
print("=== Qdrant Knowledge Store Demo (Agent-First) ===")
|
||||
|
||||
# Agent-first approach: use knowledge parameter with a shipped vector store
|
||||
# Agent-first approach: use knowledge parameter with Qdrant
|
||||
agent = Agent(
|
||||
name="KnowledgeAssistant",
|
||||
instructions="You are a helpful assistant with access to technical documentation.",
|
||||
knowledge={
|
||||
"sources": [doc_path],
|
||||
"vector_store": {
|
||||
"provider": "chroma",
|
||||
"provider": "qdrant",
|
||||
"url": "http://localhost:6333",
|
||||
},
|
||||
}
|
||||
)
|
||||
@@ -71,4 +70,4 @@ print("\n=== Demo Complete ===")
|
||||
|
||||
# --- Advanced: Direct Store Usage ---
|
||||
# from praisonai.persistence.factory import create_knowledge_store
|
||||
# store = create_knowledge_store("chroma")
|
||||
# store = create_knowledge_store("qdrant", url="http://localhost:6333")
|
||||
@@ -14,7 +14,7 @@ Expected Output:
|
||||
Agent responds with state persisted to Redis
|
||||
"""
|
||||
|
||||
from praisonaiagents import Agent, MemoryConfig
|
||||
from praisonaiagents import Agent
|
||||
from praisonaiagents.db import db
|
||||
|
||||
print("=== Redis State Store (Agent-First) ===")
|
||||
@@ -28,7 +28,8 @@ my_db = db(
|
||||
agent = Agent(
|
||||
name="Assistant",
|
||||
instructions="You are a helpful assistant.",
|
||||
memory=MemoryConfig(db=my_db, session_id="redis-state-example"),
|
||||
memory=my_db,
|
||||
session_id="redis-state-example"
|
||||
)
|
||||
|
||||
# Chat - state is automatically managed via Redis
|
||||
|
||||
@@ -1,111 +0,0 @@
|
||||
"""
|
||||
Human Review Between Sequential AgentTeam Tasks
|
||||
================================================
|
||||
|
||||
Demonstrates a human-in-the-loop review gate between sequential tasks using the
|
||||
existing ``on_task_complete`` hook — no new API required.
|
||||
|
||||
IMPORTANT — two different ``on_task_complete`` hooks exist, with DIFFERENT
|
||||
signatures. Do not confuse them:
|
||||
|
||||
AgentTeam(hooks=MultiAgentHooksConfig(on_task_complete=fn))
|
||||
-> fn(task, task_output) # team-level; gets the Task and its output
|
||||
|
||||
Task(on_task_complete=fn)
|
||||
-> fn(task_output) # 1 param: just the TaskOutput
|
||||
-> fn(task_output, metadata) # 2+ params: TaskOutput + metadata dict
|
||||
# NOTE: NOT (task, task_output)
|
||||
|
||||
This example uses the TEAM-level hook so we get ``(task, task_output)`` and can
|
||||
filter which tasks require review by ``task.name``.
|
||||
|
||||
Approve / reject / edit:
|
||||
- approve -> return, workflow continues
|
||||
- reject -> raise; see "stopping the workflow" note below
|
||||
- edit -> mutate ``task_output.raw``; downstream tasks that read this task via
|
||||
``context=[...]`` pick up the edited text
|
||||
|
||||
Stopping the workflow on reject
|
||||
-------------------------------
|
||||
The TEAM-level hook logs and swallows exceptions, so a bare ``raise`` inside it
|
||||
does NOT stop the sequential run today. To hard-stop on reject, use the PER-TASK
|
||||
callback path with the 1-argument signature and ``fail_on_callback_error=True``
|
||||
(see ``review_output`` / ``t1_strict`` at the bottom of this file).
|
||||
"""
|
||||
|
||||
from praisonaiagents import Agent, Task, AgentTeam
|
||||
from praisonaiagents.config.feature_configs import MultiAgentHooksConfig
|
||||
|
||||
# Only these task names trigger a human review gate.
|
||||
REVIEW_TASKS = {"research"}
|
||||
|
||||
|
||||
# --- Team-level review gate: signature is (task, task_output) ---------------
|
||||
def review_gate(task, task_output):
|
||||
if task.name not in REVIEW_TASKS:
|
||||
return
|
||||
|
||||
print(f"\n--- Review: {task.name} ---\n{task_output.raw}\n")
|
||||
choice = input("Approve (y), reject (n), edit (e)? ").strip().lower()
|
||||
|
||||
if choice == "n":
|
||||
# NOTE: team-level hook swallows this; see per-task strict path below
|
||||
# for a version that actually halts the workflow.
|
||||
raise RuntimeError(f"Human rejected task '{task.name}'")
|
||||
|
||||
if choice == "e":
|
||||
# task.result is the same object as task_output, so mutating .raw here
|
||||
# propagates to downstream tasks that use context=[this_task].
|
||||
task_output.raw = input("Edited output: ").strip()
|
||||
|
||||
|
||||
researcher = Agent(name="Researcher", role="Researcher", goal="Research", backstory="Expert")
|
||||
writer = Agent(name="Writer", role="Writer", goal="Write", backstory="Writer")
|
||||
|
||||
t1 = Task(
|
||||
name="research",
|
||||
description="List 5 facts about {{topic}}", # {{...}} is the substitution syntax
|
||||
expected_output="5 bullets",
|
||||
agent=researcher,
|
||||
)
|
||||
t2 = Task(
|
||||
name="summary",
|
||||
description="Write 3-sentence summary",
|
||||
expected_output="3 sentences",
|
||||
agent=writer,
|
||||
context=[t1], # reads the (possibly edited) output of t1
|
||||
)
|
||||
|
||||
team = AgentTeam(
|
||||
agents=[researcher, writer],
|
||||
tasks=[t1, t2],
|
||||
process="sequential",
|
||||
variables={"topic": "REST APIs"}, # substituted into {{topic}} in task descriptions
|
||||
hooks=MultiAgentHooksConfig(on_task_complete=review_gate),
|
||||
)
|
||||
|
||||
|
||||
# --- Alternative: per-task strict gate that HALTS on reject -----------------
|
||||
# Per-task Task.on_task_complete uses the 1-argument signature (task_output).
|
||||
# With fail_on_callback_error=True a raised exception re-raises and stops the run.
|
||||
def review_output(task_output):
|
||||
print(f"\n--- Review output ---\n{task_output.raw}\n")
|
||||
if input("Approve? (y/n) ").strip().lower() == "n":
|
||||
raise RuntimeError("Human rejected output")
|
||||
|
||||
|
||||
t1_strict = Task(
|
||||
name="research",
|
||||
description="List 5 facts about {{topic}}",
|
||||
expected_output="5 bullets",
|
||||
agent=researcher,
|
||||
variables={"topic": "REST APIs"},
|
||||
on_task_complete=review_output, # signature: (task_output)
|
||||
fail_on_callback_error=True, # required so reject halts the workflow
|
||||
)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
# NOTE: template values come from AgentTeam(variables=...), NOT start(inputs=...).
|
||||
# start() forwards **kwargs but does not consume an ``inputs`` argument.
|
||||
team.start()
|
||||
@@ -1,15 +1,34 @@
|
||||
import socket
|
||||
import sys
|
||||
import threading
|
||||
import time
|
||||
|
||||
from praisonaiagents import Agent
|
||||
|
||||
|
||||
def _wait_until_ready(host: str, port: int, timeout: float = 15.0) -> bool:
|
||||
"""Poll the MCP server port until it accepts connections or times out."""
|
||||
deadline = time.time() + timeout
|
||||
while time.time() < deadline:
|
||||
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
|
||||
sock.settimeout(1.0)
|
||||
if sock.connect_ex((host, port)) == 0:
|
||||
return True
|
||||
time.sleep(0.25)
|
||||
return False
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
host, port = "127.0.0.1", 8080
|
||||
agent = Agent(name="TweetAgent", instructions="Create a Tweet based on the topic provided")
|
||||
server = threading.Thread(
|
||||
target=lambda: agent.launch(port=8080, protocol="mcp", path="/mcp"),
|
||||
target=lambda: agent.launch(port=port, protocol="mcp", path="/mcp"),
|
||||
daemon=True,
|
||||
)
|
||||
server.start()
|
||||
time.sleep(2)
|
||||
print("MCP server started on http://127.0.0.1:8080/mcp")
|
||||
|
||||
if _wait_until_ready(host, port):
|
||||
print(f"MCP server started on http://{host}:{port}/mcp")
|
||||
else:
|
||||
print(f"MCP server failed to start on http://{host}:{port}/mcp", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
@@ -23,7 +23,6 @@ from praisonaiagents.hooks.verification import (
|
||||
VerificationResult,
|
||||
BaseVerificationHook,
|
||||
CommandVerificationHook,
|
||||
FileCheckHook,
|
||||
)
|
||||
|
||||
|
||||
@@ -101,19 +100,7 @@ def main():
|
||||
print(f" Name: {cmd_hook.name}")
|
||||
print(f" Command: {cmd_hook.command}")
|
||||
print(f" Timeout: {cmd_hook.timeout_seconds}s")
|
||||
|
||||
# 6. FileCheckHook: declarative, no-shell completion gate
|
||||
print("\n6. FileCheckHook (declarative completion gate):")
|
||||
file_hook = FileCheckHook(
|
||||
name="changelog", path="CHANGELOG.md", non_empty=True
|
||||
)
|
||||
file_result = file_hook.run()
|
||||
print(f" {file_hook.name}: success={file_result.success} — {file_result.output}")
|
||||
print(
|
||||
" Gate wiring: when verification_hooks are configured, the autonomous "
|
||||
"loop cannot finalise with a success outcome while a blocking hook fails."
|
||||
)
|
||||
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
print("✓ Verification hooks example completed successfully!")
|
||||
print("=" * 60)
|
||||
|
||||
@@ -86,7 +86,7 @@ def method_1_simple_loop():
|
||||
agents=[loop_agent],
|
||||
tasks=[loop_task],
|
||||
process="workflow",
|
||||
execution="balanced" # max_iter=10 preset to prevent infinite loops
|
||||
max_iter=10 # Maximum iterations to prevent infinite loops
|
||||
)
|
||||
|
||||
print(f"🚀 Starting loop processing of {csv_file}")
|
||||
|
||||
@@ -64,7 +64,7 @@ def main():
|
||||
agents=[url_agent],
|
||||
tasks=[url_task],
|
||||
process="workflow",
|
||||
execution="balanced" # max_iter=10 preset; adjust for more URLs
|
||||
max_iter=10 # Adjust based on how many URLs you have
|
||||
)
|
||||
|
||||
print(f"🚀 Processing URLs from {csv_file}")
|
||||
|
||||
@@ -7,8 +7,7 @@ multiple agents and managing real-time communication.
|
||||
|
||||
from praisonaiagents import Agent, GatewayConfig, SessionConfig
|
||||
|
||||
# Configure the gateway using the typed SDK GatewayConfig.
|
||||
# In gateway.yaml, the optional ``gateway:`` block is validated at load time (#3050).
|
||||
# Configure the gateway
|
||||
gateway_config = GatewayConfig(
|
||||
host="127.0.0.1",
|
||||
port=8765,
|
||||
|
||||
@@ -141,7 +141,7 @@ class DynamicAgentSystem:
|
||||
agents=agents,
|
||||
tasks=tasks,
|
||||
process=process,
|
||||
output="verbose" if inputs['depth'] == 'detailed' else "silent"
|
||||
verbose=inputs['depth'] == 'detailed'
|
||||
)
|
||||
|
||||
result = praison_agents.start()
|
||||
|
||||
@@ -7,12 +7,12 @@ allowed_dirs = [
|
||||
"/path/to/other/allowed/dir"
|
||||
]
|
||||
|
||||
# Pass the executable as the first token and the allowed directories as args
|
||||
# Use a single string command with allowed directories
|
||||
filesystem_agent = Agent(
|
||||
instructions="""You are a helpful assistant that can interact with the filesystem.
|
||||
Use the available tools when relevant to manage files and directories.""",
|
||||
llm="gpt-4o-mini",
|
||||
tools=MCP("npx", args=["-y", "@modelcontextprotocol/server-filesystem", *allowed_dirs])
|
||||
tools=MCP("npx -y @modelcontextprotocol/server-filesystem", args=allowed_dirs)
|
||||
)
|
||||
|
||||
filesystem_agent.start("List files in the allowed directories")
|
||||
@@ -1,34 +0,0 @@
|
||||
"""
|
||||
Basic example of using EvoLink.AI with PraisonAI.
|
||||
"""
|
||||
|
||||
import os
|
||||
|
||||
from praisonaiagents import Agent
|
||||
|
||||
api_key = os.getenv("EVOLINK_API_KEY")
|
||||
if not api_key:
|
||||
raise RuntimeError(
|
||||
"EVOLINK_API_KEY is not set. Set it before running this example: "
|
||||
"export EVOLINK_API_KEY=your_api_key"
|
||||
)
|
||||
|
||||
agent = Agent(
|
||||
instructions="You are a helpful assistant",
|
||||
llm={
|
||||
"model": "openai/gpt-5.2",
|
||||
"api_key": api_key,
|
||||
"base_url": "https://direct.evolink.ai/v1",
|
||||
},
|
||||
)
|
||||
|
||||
response = agent.start("Hello! Share one practical AI automation idea.")
|
||||
print(response)
|
||||
|
||||
coding_task = """
|
||||
Write a Python function that validates whether a string is a palindrome.
|
||||
Include a short docstring and ignore spaces and capitalization.
|
||||
"""
|
||||
|
||||
response = agent.start(coding_task)
|
||||
print(response)
|
||||
@@ -66,7 +66,7 @@ research_task1 = Task(
|
||||
agents_session1 = AgentTeam(
|
||||
agents=[research_agent],
|
||||
tasks=[research_task1],
|
||||
output="verbose"
|
||||
session=session1, output="verbose"
|
||||
)
|
||||
|
||||
# Execute first session
|
||||
@@ -105,7 +105,7 @@ analysis_task = Task(
|
||||
agents_session2 = AgentTeam(
|
||||
agents=[analysis_agent],
|
||||
tasks=[analysis_task],
|
||||
output="verbose"
|
||||
session=session2, output="verbose"
|
||||
)
|
||||
|
||||
print("Starting analysis session with previous context...")
|
||||
@@ -155,7 +155,7 @@ synthesis_task = Task(
|
||||
agents_recovery = AgentTeam(
|
||||
agents=[synthesis_agent],
|
||||
tasks=[synthesis_task],
|
||||
output="verbose"
|
||||
session=recovery_session, output="verbose"
|
||||
)
|
||||
|
||||
print("Starting recovery session with full context from previous sessions...")
|
||||
@@ -205,7 +205,7 @@ review_task = Task(
|
||||
agents_reviewer = AgentTeam(
|
||||
agents=[review_agent],
|
||||
tasks=[review_task],
|
||||
output="verbose"
|
||||
session=reviewer_session, output="verbose"
|
||||
)
|
||||
|
||||
print("Starting peer review session by different user...")
|
||||
|
||||
@@ -77,35 +77,13 @@ class TrafilaturaTools:
|
||||
except ValueError:
|
||||
# Not an IP address, continue with domain validation
|
||||
pass
|
||||
|
||||
|
||||
# Block common internal domains
|
||||
if any(hostname.endswith(domain) for domain in ['.local', '.internal', '.localdomain']):
|
||||
return False
|
||||
|
||||
|
||||
# Block metadata service endpoints
|
||||
if hostname in ['169.254.169.254', 'metadata.google.internal']:
|
||||
return False
|
||||
|
||||
# Resolve the hostname and reject if any address is internal. The
|
||||
# checks above only inspect IP *literals*, so a plain domain (or an
|
||||
# encoded form like a decimal IP or "<internal-ip>.nip.io") still
|
||||
# passes even though it resolves to an internal address. Resolving
|
||||
# here closes that SSRF bypass, mirroring the resolve-and-check
|
||||
# approach already used in praisonaiagents/tools/file_tools.py.
|
||||
import socket
|
||||
default_port = 443 if parsed.scheme == 'https' else 80
|
||||
try:
|
||||
addrinfos = socket.getaddrinfo(hostname, parsed.port or default_port)
|
||||
except socket.gaierror:
|
||||
# Hostname does not resolve; treat it as unsafe.
|
||||
return False
|
||||
for addrinfo in addrinfos:
|
||||
resolved = ipaddress.ip_address(addrinfo[4][0])
|
||||
if (resolved.is_private or resolved.is_reserved
|
||||
or resolved.is_loopback or resolved.is_link_local):
|
||||
return False
|
||||
|
||||
return True
|
||||
return hostname not in ['169.254.169.254', 'metadata.google.internal']
|
||||
|
||||
except Exception:
|
||||
return False
|
||||
@@ -279,17 +257,7 @@ class TrafilaturaTools:
|
||||
"newspaper": None,
|
||||
"spider": None
|
||||
}
|
||||
|
||||
# Validate the URL once before any fetcher runs so the newspaper and
|
||||
# requests paths below are protected against SSRF, just like the
|
||||
# trafilatura path (which validates inside extract_content).
|
||||
if not self._validate_url(url):
|
||||
error = {"error": f"Invalid or unsafe URL: {url}"}
|
||||
comparison["trafilatura"] = error
|
||||
comparison["newspaper"] = error
|
||||
comparison["spider"] = error
|
||||
return comparison
|
||||
|
||||
|
||||
# Get Trafilatura extraction
|
||||
try:
|
||||
comparison["trafilatura"] = self.extract_content(url)
|
||||
|
||||
@@ -24,7 +24,7 @@ Examples for all PraisonAI server types and the unified endpoints CLI.
|
||||
| `praisonai serve unified --port 8765` | Start unified server |
|
||||
| `praisonai serve agents --file agents.yaml --port 8000` | Start agents API |
|
||||
| `praisonai serve recipe --port 8765` | Start recipe server |
|
||||
| `praisonai mcp serve --transport http-stream --port 8080` | Start MCP server |
|
||||
| `praisonai serve mcp --transport http --port 8080` | Start MCP server |
|
||||
| `praisonai serve tools --port 8081` | Start tools MCP server |
|
||||
| `praisonai serve a2a --port 8082` | Start A2A server |
|
||||
| `praisonai serve a2u --port 8083` | Start A2U server |
|
||||
|
||||
@@ -13,7 +13,7 @@ Usage:
|
||||
python mcp_http_server.py
|
||||
|
||||
# Or use CLI:
|
||||
praisonai mcp serve --transport http-stream --port 8080
|
||||
praisonai serve mcp --transport http --port 8080
|
||||
|
||||
# Test with curl:
|
||||
curl http://localhost:8080/mcp/tools
|
||||
|
||||
@@ -14,9 +14,9 @@ datasets:
|
||||
# A small verified subset for a cheap smoke run. Verify against the registry
|
||||
# with `harbor datasets list` before editing.
|
||||
task_names:
|
||||
- terminal-bench/build-pmars
|
||||
- terminal-bench/bn-fit-modify
|
||||
- terminal-bench/break-filter-js-from-html
|
||||
- hello-world
|
||||
- fix-permissions
|
||||
- csv-to-parquet
|
||||
|
||||
agents:
|
||||
- import_path: examples.terminal_bench.praisonai_code_agent:PraisonAICodeAgent
|
||||
|
||||
@@ -13,14 +13,15 @@ Usage:
|
||||
-n 4
|
||||
|
||||
Architecture:
|
||||
Harbor Container → `praisonai code -p --output json "TASK" --dangerously-skip-approval`
|
||||
Harbor Container → `praisonai code "TASK" --dangerously-skip-approval` (headless)
|
||||
|
||||
Notes:
|
||||
- `--dangerously-skip-approval` sets PRAISON_APPROVAL_MODE=auto +
|
||||
PRAISONAI_TOOL_SAFETY=off so the assistant runs fully autonomously in the
|
||||
container (no approval hang in a non-TTY session).
|
||||
- The JSON envelope provides token, cost, session, and status metadata while
|
||||
the real exit status still surfaces install/auth/startup failures.
|
||||
- `praisonai code` normally exits 0 and Harbor grades by task verification,
|
||||
so a benchmark miss does not fail the run — but the real exit status is
|
||||
propagated so genuine install/auth/startup failures still surface.
|
||||
- The base `praisonai` package is sufficient; heavy `code` extras are not
|
||||
required (ACP tools degrade gracefully).
|
||||
|
||||
@@ -28,7 +29,6 @@ Dependencies:
|
||||
pip install harbor praisonai praisonaiagents
|
||||
"""
|
||||
|
||||
import json
|
||||
import shlex
|
||||
|
||||
try:
|
||||
@@ -81,19 +81,16 @@ class PraisonAICodeAgent(BaseInstalledAgent):
|
||||
model = self.model_name or "openai/gpt-4o-mini"
|
||||
|
||||
command = (
|
||||
"log_file=$(mktemp /tmp/praisonai_code.XXXXXX); "
|
||||
"chmod 600 \"$log_file\"; "
|
||||
f"praisonai code -p --output json {shlex.quote(instruction)} "
|
||||
f"praisonai code {shlex.quote(instruction)} "
|
||||
f"--dangerously-skip-approval "
|
||||
f"--model {shlex.quote(model)} "
|
||||
"> \"$log_file\" 2>&1; "
|
||||
"> /tmp/praisonai_code.log 2>&1; "
|
||||
# Capture the real exit status so install/auth/startup failures still
|
||||
# surface instead of being silently masked (Harbor otherwise records a
|
||||
# completed attempt for a crashed agent).
|
||||
"status=$?; "
|
||||
# Echo the envelope so Harbor captures it for post-run accounting.
|
||||
"cat \"$log_file\"; "
|
||||
"rm -f \"$log_file\"; "
|
||||
# Tee the log into a stable path so populate_context_post_run can read it.
|
||||
"cp /tmp/praisonai_code.log /tmp/praisonai_code_run.log 2>/dev/null || true; "
|
||||
# `praisonai code` normally exits 0 (Harbor grades by task
|
||||
# verification), so a genuine benchmark miss won't fail here — but a
|
||||
# nonzero status means the assistant itself failed to run.
|
||||
@@ -103,35 +100,23 @@ class PraisonAICodeAgent(BaseInstalledAgent):
|
||||
# `--ae` / job YAML env vars arrive via BaseAgent.extra_env and are wired
|
||||
# into the container exec context by Harbor Trial, so no per-exec `env=`
|
||||
# is needed here.
|
||||
result = await self.exec_as_agent(
|
||||
await self.exec_as_agent(
|
||||
environment,
|
||||
command=command,
|
||||
)
|
||||
self._last_stdout = getattr(result, "stdout", "") or ""
|
||||
|
||||
def populate_context_post_run(self, context: AgentContext) -> None:
|
||||
"""Parse the headless JSON envelope into Harbor's accounting fields."""
|
||||
envelope = None
|
||||
for line in reversed(getattr(self, "_last_stdout", "").splitlines()):
|
||||
try:
|
||||
candidate = json.loads(line)
|
||||
except (TypeError, ValueError, json.JSONDecodeError):
|
||||
continue
|
||||
if isinstance(candidate, dict) and "status" in candidate:
|
||||
envelope = candidate
|
||||
break
|
||||
"""`praisonai code` exposes no machine-readable metrics headlessly.
|
||||
|
||||
usage = envelope.get("usage", {}) if envelope else {}
|
||||
context.n_input_tokens = usage.get("in")
|
||||
context.n_output_tokens = usage.get("out")
|
||||
context.cost_usd = usage.get("cost")
|
||||
Record identifying metadata; token/cost accounting is not available from
|
||||
the CLI's mixed stdout, so we leave those fields unset rather than guess.
|
||||
"""
|
||||
context.metadata = {
|
||||
"framework": "praisonai",
|
||||
"agent_type": "code-cli",
|
||||
"agent_name": self.name(),
|
||||
"model": self.model_name,
|
||||
"session_id": envelope.get("session_id") if envelope else None,
|
||||
"status": envelope.get("status") if envelope else "unknown",
|
||||
"log_path": "/tmp/praisonai_code.log",
|
||||
}
|
||||
|
||||
|
||||
|
||||
@@ -34,7 +34,6 @@ except ImportError as e:
|
||||
try:
|
||||
from praisonaiagents import Agent
|
||||
from praisonaiagents.approval import get_approval_registry, AutoApproveBackend
|
||||
from praisonaiagents.config.feature_configs import ExecutionConfig
|
||||
except ImportError as e:
|
||||
raise ImportError(
|
||||
f"PraisonAI not installed: {e}\n"
|
||||
@@ -42,13 +41,6 @@ except ImportError as e:
|
||||
) from e
|
||||
|
||||
|
||||
TB_EXECUTION = ExecutionConfig(
|
||||
max_tool_calls_per_turn=80,
|
||||
max_iter=40,
|
||||
max_steps=80,
|
||||
)
|
||||
|
||||
|
||||
class PraisonAIExternalAgent(BaseAgent):
|
||||
"""External PraisonAI agent that drives a Harbor container environment."""
|
||||
|
||||
@@ -150,14 +142,26 @@ class PraisonAIExternalAgent(BaseAgent):
|
||||
),
|
||||
tools=[bash_tool],
|
||||
llm=self.model_name or "openai/gpt-4o-mini",
|
||||
execution=TB_EXECUTION,
|
||||
)
|
||||
|
||||
# Execute one deliberately long coding turn. Harbor's hidden verifier
|
||||
# is the only completion authority; model or pytest text is not.
|
||||
# Execute the agent with outer loop to handle premature stopping
|
||||
print(f"🚀 PraisonAI Agent starting task: {instruction[:100]}...")
|
||||
result = await agent.achat(instruction)
|
||||
print("✅ PraisonAI Agent completed task")
|
||||
for _iter in range(19):
|
||||
result_str = str(result)
|
||||
# Stop if test passed
|
||||
if any(sig in result_str.lower() for sig in [
|
||||
" passed", "passed ", "test passed", "all tests pass", "1 passed"
|
||||
]):
|
||||
break
|
||||
result = await agent.achat(
|
||||
"The task is NOT complete yet — keep working. Run bash_tool commands now. "
|
||||
"If you haven't already: (1) read all files in /app/, "
|
||||
"(2) run the test to see the exact failure, "
|
||||
"(3) implement a fix, (4) run the test again. "
|
||||
"Repeat until the test passes. What is your next bash_tool command?"
|
||||
)
|
||||
print(f"✅ PraisonAI Agent completed task")
|
||||
|
||||
# Populate Harbor context with metadata
|
||||
self._populate_context(agent, context, result)
|
||||
@@ -199,10 +203,6 @@ class PraisonAIExternalAgent(BaseAgent):
|
||||
"tools_used": ["bash_tool"],
|
||||
"framework": "praisonai",
|
||||
"version": self.version(),
|
||||
"stop_reason": getattr(agent, "last_stop_reason", None),
|
||||
"max_tool_calls_per_turn": TB_EXECUTION.max_tool_calls_per_turn,
|
||||
"max_iter": TB_EXECUTION.max_iter,
|
||||
"max_steps": TB_EXECUTION.max_steps,
|
||||
}
|
||||
|
||||
except Exception as e:
|
||||
@@ -218,4 +218,4 @@ if __name__ == "__main__":
|
||||
print(" --model openai/gpt-4o-mini")
|
||||
print()
|
||||
print("Dependencies:")
|
||||
print(" pip install harbor praisonaiagents")
|
||||
print(" pip install harbor praisonaiagents")
|
||||
@@ -1,39 +0,0 @@
|
||||
"""Static regression checks for the in-tree Harbor adapter configuration."""
|
||||
|
||||
from pathlib import Path
|
||||
|
||||
import yaml
|
||||
|
||||
|
||||
EXAMPLES = Path(__file__).parent
|
||||
|
||||
|
||||
def test_external_adapter_sets_coding_execution_budget():
|
||||
source = (EXAMPLES / "praisonai_external_agent.py").read_text(encoding="utf-8")
|
||||
|
||||
assert "ExecutionConfig" in source
|
||||
assert "max_tool_calls_per_turn=80" in source
|
||||
assert "max_iter=40" in source
|
||||
assert "max_steps=80" in source
|
||||
|
||||
|
||||
def test_external_adapter_does_not_guess_completion_from_pytest_text():
|
||||
source = (EXAMPLES / "praisonai_external_agent.py").read_text(encoding="utf-8")
|
||||
|
||||
assert '"1 passed"' not in source
|
||||
assert '"test passed"' not in source
|
||||
|
||||
|
||||
def test_smoke_yaml_uses_terminal_bench_21_registry_ids():
|
||||
job = yaml.safe_load(
|
||||
(EXAMPLES / "job_code_smoke.yaml").read_text(encoding="utf-8")
|
||||
)
|
||||
names = job["datasets"][0]["task_names"]
|
||||
|
||||
assert names
|
||||
assert all(name.startswith("terminal-bench/") for name in names)
|
||||
assert names == [
|
||||
"terminal-bench/build-pmars",
|
||||
"terminal-bench/bn-fit-modify",
|
||||
"terminal-bench/break-filter-js-from-html",
|
||||
]
|
||||
@@ -14,18 +14,18 @@ def test_imports():
|
||||
"""Test that all required modules can be imported."""
|
||||
try:
|
||||
from praisonaiagents import Agent
|
||||
print("[OK] Agent imported successfully")
|
||||
print("✅ Agent imported successfully")
|
||||
|
||||
from praisonaiagents.tools import execute_command
|
||||
print("[OK] execute_command tool imported successfully")
|
||||
print("✅ execute_command tool imported successfully")
|
||||
|
||||
from praisonaiagents.approval import get_approval_registry, AutoApproveBackend
|
||||
print("[OK] Approval system imported successfully")
|
||||
print("✅ Approval system imported successfully")
|
||||
|
||||
return True
|
||||
|
||||
except ImportError as e:
|
||||
print(f"[FAIL] Import failed: {ascii(e)}")
|
||||
print(f"❌ Import failed: {e}")
|
||||
return False
|
||||
|
||||
def test_agent_creation():
|
||||
@@ -40,11 +40,11 @@ def test_agent_creation():
|
||||
)
|
||||
|
||||
assert agent.name == 'test-agent'
|
||||
print("[OK] Agent creation successful")
|
||||
print("✅ Agent creation successful")
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f"[FAIL] Agent creation failed: {ascii(e)}")
|
||||
print(f"❌ Agent creation failed: {e}")
|
||||
return False
|
||||
|
||||
def test_approval_system():
|
||||
@@ -55,11 +55,11 @@ def test_approval_system():
|
||||
registry = get_approval_registry()
|
||||
registry.set_backend(AutoApproveBackend())
|
||||
|
||||
print("[OK] Approval system configuration successful")
|
||||
print("✅ Approval system configuration successful")
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f"[FAIL] Approval system test failed: {ascii(e)}")
|
||||
print(f"❌ Approval system test failed: {e}")
|
||||
return False
|
||||
|
||||
def test_external_agent_import():
|
||||
@@ -80,11 +80,11 @@ def test_external_agent_import():
|
||||
|
||||
# Now try to import our agent
|
||||
import praisonai_external_agent
|
||||
print("[OK] External agent import successful")
|
||||
print("✅ External agent import successful")
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f"[FAIL] External agent import failed: {ascii(e)}")
|
||||
print(f"❌ External agent import failed: {e}")
|
||||
return False
|
||||
|
||||
def test_multi_agent_import():
|
||||
@@ -104,11 +104,11 @@ def test_multi_agent_import():
|
||||
sys.modules['harbor.models.agent.context'] = MagicMock()
|
||||
|
||||
import multi_agent_example
|
||||
print("[OK] Multi-agent example import successful")
|
||||
print("✅ Multi-agent example import successful")
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f"[FAIL] Multi-agent example import failed: {ascii(e)}")
|
||||
print(f"❌ Multi-agent example import failed: {e}")
|
||||
return False
|
||||
|
||||
def test_wrapper_agent_import():
|
||||
@@ -128,11 +128,11 @@ def test_wrapper_agent_import():
|
||||
sys.modules['harbor.models.agent.context'] = MagicMock()
|
||||
|
||||
import praisonai_wrapper_agent
|
||||
print("[OK] Wrapper agent import successful (CLI-based approach)")
|
||||
print("✅ Wrapper agent import successful (CLI-based approach)")
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f"[FAIL] Wrapper agent import failed: {ascii(e)}")
|
||||
print(f"❌ Wrapper agent import failed: {e}")
|
||||
return False
|
||||
|
||||
if __name__ == "__main__":
|
||||
@@ -152,19 +152,19 @@ if __name__ == "__main__":
|
||||
total = len(tests)
|
||||
|
||||
for test_name, test_func in tests:
|
||||
print(f"\n[TEST] {test_name}...")
|
||||
print(f"\n🧪 Testing {test_name}...")
|
||||
try:
|
||||
if test_func():
|
||||
passed += 1
|
||||
except Exception as e:
|
||||
print(f"[FAIL] Test {test_name} crashed: {ascii(e)}")
|
||||
print(f"❌ Test {test_name} crashed: {e}")
|
||||
|
||||
print("\n" + "=" * 55)
|
||||
print(f"Results: {passed}/{total} tests passed")
|
||||
|
||||
if passed == total:
|
||||
print("[OK] ALL BASIC TESTS PASSED!")
|
||||
print("🎉 ALL BASIC TESTS PASSED!")
|
||||
print("The Terminal-Bench integration components are properly structured.")
|
||||
else:
|
||||
print("[FAIL] Some tests failed - check output above")
|
||||
print("❌ Some tests failed - check output above")
|
||||
sys.exit(1)
|
||||
@@ -1,25 +1,17 @@
|
||||
"""Qdrant Vector Store - Agent-First Example
|
||||
"""Qdrant Vector Store - Agent-First Example (requires Docker)
|
||||
|
||||
Qdrant is not a shipped adapter. Register one first, then use it via the
|
||||
``knowledge`` parameter. If no adapter is registered this example skips
|
||||
cleanly instead of crashing.
|
||||
|
||||
from praisonaiagents.knowledge.adapters import register_knowledge_adapter
|
||||
register_knowledge_adapter("qdrant", MyQdrantAdapter)
|
||||
Docker: docker run -d --name qdrant -p 6333:6333 qdrant/qdrant
|
||||
"""
|
||||
import sys
|
||||
import os
|
||||
from praisonaiagents import Agent
|
||||
from praisonaiagents.knowledge.adapters import list_knowledge_adapters
|
||||
|
||||
if "qdrant" not in list_knowledge_adapters():
|
||||
print("SKIPPED: Qdrant - no 'qdrant' adapter registered")
|
||||
sys.exit(0)
|
||||
# Agent-first approach: use knowledge parameter with Qdrant
|
||||
url = os.getenv("QDRANT_URL", "http://localhost:6333")
|
||||
|
||||
# Agent-first approach: use knowledge parameter with a registered Qdrant adapter
|
||||
agent = Agent(
|
||||
name="Assistant",
|
||||
instructions="You are a helpful assistant with access to documents.",
|
||||
knowledge={"sources": ["./docs/guide.pdf"], "vector_store": {"provider": "qdrant"}}
|
||||
knowledge={"sources": ["./docs/guide.pdf"], "vector_store": {"provider": "qdrant", "url": url}}
|
||||
)
|
||||
|
||||
# Chat - agent uses knowledge for RAG
|
||||
@@ -27,3 +19,7 @@ response = agent.chat("What information do you have?")
|
||||
print(f"Response: {response}")
|
||||
|
||||
print("PASSED: Qdrant with Agent")
|
||||
|
||||
# --- Advanced: Direct Store Usage ---
|
||||
# from praisonai.persistence import create_knowledge_store
|
||||
# store = create_knowledge_store("qdrant", url=url)
|
||||
@@ -1,64 +0,0 @@
|
||||
# Simple Sequential Team (YAML)
|
||||
|
||||
A minimal 2-agent sequential team: a **researcher** gathers facts, then a
|
||||
**writer** summarizes them. This is the copy-paste starting point for the most
|
||||
common multi-agent pattern (2–5 agents, run in order).
|
||||
|
||||
```
|
||||
research_task -> summary_task
|
||||
(researcher) (writer)
|
||||
```
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `agents.yaml` | Roles (who) + their tasks (what); tasks run in declaration order |
|
||||
|
||||
> **Which loader applies?** This example uses the canonical single-file format
|
||||
> consumed by `AgentsGenerator.generate_crew_and_kickoff()`
|
||||
> (`src/praisonai/praisonai/agents_generator.py`). Agents live under `roles:`,
|
||||
> each with nested `tasks:`. **Tasks run in the order they are declared** — the
|
||||
> researcher's task first, then the writer's. (An optional top-level
|
||||
> `dependencies:` block is included to document intent and mirror the canonical
|
||||
> fixture, but the roles-file loader sequences by declaration order, so keep
|
||||
> tasks in the order you want them to run.) No new loader module is required —
|
||||
> this is the existing YAML path.
|
||||
|
||||
## Run it
|
||||
|
||||
```bash
|
||||
export OPENAI_API_KEY=sk-...
|
||||
praisonai examples/yaml/teams/research-writer/agents.yaml
|
||||
```
|
||||
|
||||
This positional-file form is the canonical roles-file entry point. From Python
|
||||
the equivalent is `praisonai.run("agents.yaml")` (see
|
||||
`src/praisonai/praisonai/_entrypoint.py`), which dispatches to the same
|
||||
`AgentsGenerator`.
|
||||
|
||||
Change the subject by editing the `topic:` line in `agents.yaml` (interpolated
|
||||
into every `{topic}` placeholder).
|
||||
|
||||
## When to use this vs a workflow YAML
|
||||
|
||||
| You need… | Use | Example |
|
||||
|-----------|-----|---------|
|
||||
| 2–5 agents, sequential/hierarchical | **This** (`roles:` + `tasks:`) | `agents.yaml` here |
|
||||
| Routing by classifier output | workflow YAML | `../../workflows/routing_workflow.yaml` |
|
||||
| Parallel branches | workflow YAML | `../../workflows/parallel_workflow.yaml` |
|
||||
| Loops / planning / memory | workflow YAML | `../../workflows/complete_workflow.yaml` |
|
||||
|
||||
## Python equivalent
|
||||
|
||||
```python
|
||||
from praisonaiagents import Agent, Task, PraisonAIAgents
|
||||
|
||||
researcher = Agent(role="Senior Researcher", goal="Find accurate information")
|
||||
writer = Agent(role="Report Writer", goal="Turn research into summaries")
|
||||
|
||||
t1 = Task(description="Research renewable energy and list 5 key facts", agent=researcher)
|
||||
t2 = Task(description="Write a 3-sentence summary from the research", agent=writer, context=[t1])
|
||||
|
||||
PraisonAIAgents(agents=[researcher, writer], tasks=[t1, t2]).start()
|
||||
```
|
||||
@@ -1,34 +0,0 @@
|
||||
# yaml-language-server: $schema=https://docs.praison.ai/schemas/agents.schema.json
|
||||
# Minimal sequential team: researcher -> writer
|
||||
# Run: praisonai examples/yaml/teams/research-writer/agents.yaml
|
||||
|
||||
framework: "praisonai"
|
||||
topic: "renewable energy"
|
||||
|
||||
roles:
|
||||
researcher:
|
||||
role: "Senior Researcher"
|
||||
goal: "Find accurate information about {topic}"
|
||||
backstory: "Expert at concise, factual research."
|
||||
tasks:
|
||||
research_task:
|
||||
description: "Research {topic} and list 5 key facts."
|
||||
expected_output: "A bullet list of 5 facts."
|
||||
|
||||
writer:
|
||||
role: "Report Writer"
|
||||
goal: "Turn research into readable summaries about {topic}"
|
||||
backstory: "Clear technical writer."
|
||||
tasks:
|
||||
summary_task:
|
||||
description: "Write a 3-sentence executive summary from the research."
|
||||
expected_output: "3 sentences, plain text."
|
||||
|
||||
# Ordering is by task declaration order above (researcher's task runs first,
|
||||
# then the writer's), which is how the roles-file loader sequences tasks.
|
||||
# The optional `dependencies:` block below mirrors the canonical fixture
|
||||
# (src/praisonai/tests/agents.yaml) and documents intent; the roles-file
|
||||
# loader does not consume it, so keep tasks in the order you want them run.
|
||||
dependencies:
|
||||
- task: summary_task
|
||||
depends_on: research_task
|
||||
@@ -1,45 +0,0 @@
|
||||
# Run a whole workflow's shell/file tools inside ONE shared remote sandbox.
|
||||
#
|
||||
# praisonai examples/yaml/workflows/remote_sandbox_workflow.yaml
|
||||
#
|
||||
# `tools_run_on:` is the only line that differs from a normal local workflow.
|
||||
# Every step shares the same sandbox and working directory, so the file the
|
||||
# writer creates is there for the reader. Thinking and orchestration still run
|
||||
# on your machine, and the sandbox is torn down when the run finishes.
|
||||
#
|
||||
# Places: docker | e2b | modal | daytona | flyio | tenki | local
|
||||
# subprocess | sandlock | ssh | novita
|
||||
# - docker needs a local Docker daemon and nothing else
|
||||
# - e2b / modal / daytona / flyio need that provider's API key
|
||||
# - sandlock is a kernel-enforced local boundary (Linux 6.12+)
|
||||
# - subprocess is process separation only, NOT a security boundary
|
||||
#
|
||||
# `run_on:` is still accepted here as the old spelling for this key.
|
||||
#
|
||||
# See what is still running: praisonai managed ps
|
||||
# Reclaim strays: praisonai managed stop --all
|
||||
|
||||
name: remote-sandbox-demo
|
||||
tools_run_on: docker
|
||||
|
||||
agents:
|
||||
writer:
|
||||
role: File Writer
|
||||
goal: Write files into the shared workspace
|
||||
instructions: >
|
||||
You have write_file and execute_command running on a remote Linux
|
||||
sandbox. Use them; never say you cannot run commands.
|
||||
|
||||
reader:
|
||||
role: File Reader
|
||||
goal: Read files back out of the shared workspace
|
||||
instructions: >
|
||||
You have read_file and execute_command running on the same remote
|
||||
sandbox the writer used. Use them.
|
||||
|
||||
steps:
|
||||
- agent: writer
|
||||
action: "Use write_file to put exactly 'hello from step 1' in /workspace/note.txt"
|
||||
|
||||
- agent: reader
|
||||
action: "Use read_file on /workspace/note.txt and report its exact contents"
|
||||
@@ -1,55 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# C14 import-direction gate for praisonai-deploy.
|
||||
set -euo pipefail
|
||||
|
||||
cd "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
|
||||
CODE_ROOT="${C14_CODE_ROOT:-src/praisonai-code/praisonai_code}"
|
||||
DEPLOY_ROOT="${C14_DEPLOY_ROOT:-src/praisonai-deploy/praisonai_deploy}"
|
||||
|
||||
ANY_WRAPPER_RE='(^[[:space:]]*from praisonai([[:space:]]|\.)|^[[:space:]]*import praisonai($|\.))'
|
||||
ANY_CODE_RE='(^from praisonai_code([[:space:]]|\.)|^import praisonai_code($|\.))'
|
||||
ANY_DEPLOY_RE='(^[[:space:]]*from praisonai_deploy([[:space:]]|\.)|^[[:space:]]*import praisonai_deploy($|\.))'
|
||||
|
||||
echo "== C14 praisonai_deploy wrapper import gate (must be zero outside bridges) =="
|
||||
if command -v rg >/dev/null 2>&1; then
|
||||
MATCHES="$(rg -n "$ANY_WRAPPER_RE" "$DEPLOY_ROOT" --glob '*.py' 2>/dev/null | grep -v '_wrapper_bridge.py' | grep -v '_bootstrap.py' | grep -v '_code_bridge.py' || true)"
|
||||
else
|
||||
MATCHES="$(grep -rEn --include='*.py' "$ANY_WRAPPER_RE" "$DEPLOY_ROOT" 2>/dev/null | grep -v '_wrapper_bridge.py' | grep -v '_bootstrap.py' | grep -v '_code_bridge.py' || true)"
|
||||
fi
|
||||
if [ -n "$MATCHES" ]; then
|
||||
echo "$MATCHES"
|
||||
echo "FAIL: praisonai_deploy imports the praisonai wrapper"
|
||||
exit 1
|
||||
fi
|
||||
echo "deploy wrapper import gate ok"
|
||||
|
||||
echo "== C14 praisonai_deploy module-level praisonai_code import gate =="
|
||||
if command -v rg >/dev/null 2>&1; then
|
||||
MATCHES="$(rg -n "$ANY_CODE_RE" "$DEPLOY_ROOT" --glob '*.py' 2>/dev/null | grep -v '_code_bridge.py' | grep -v '_plugin_registry.py' || true)"
|
||||
else
|
||||
MATCHES="$(grep -rEn --include='*.py' "$ANY_CODE_RE" "$DEPLOY_ROOT" 2>/dev/null | grep -v '_code_bridge.py' | grep -v '_plugin_registry.py' || true)"
|
||||
fi
|
||||
if [ -n "$MATCHES" ]; then
|
||||
echo "$MATCHES"
|
||||
echo "FAIL: module-level praisonai_code import in praisonai_deploy"
|
||||
exit 1
|
||||
fi
|
||||
echo "deploy code import gate ok"
|
||||
|
||||
echo "== C14 praisonai-code hot-path gate (no praisonai_deploy at module level) =="
|
||||
for f in \
|
||||
"$CODE_ROOT/cli/main.py" \
|
||||
"$CODE_ROOT/cli/app.py" \
|
||||
"$CODE_ROOT/cli/commands/run.py" \
|
||||
"$CODE_ROOT/cli/commands/chat.py" \
|
||||
"$CODE_ROOT/cli/commands/code.py"
|
||||
do
|
||||
if [ -f "$f" ] && head -n 80 "$f" | grep -E "$ANY_DEPLOY_RE" 2>/dev/null; then
|
||||
echo "FAIL: module-level praisonai_deploy import in code hot path $f"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
echo "code hot-path gate ok"
|
||||
|
||||
echo "C14 import gates passed"
|
||||
@@ -18,9 +18,7 @@ for f in \
|
||||
"$ROOT/cli/app.py" \
|
||||
"$ROOT/cli/commands/run.py" \
|
||||
"$ROOT/cli/commands/chat.py" \
|
||||
"$ROOT/cli/commands/code.py" \
|
||||
"$ROOT/cli/interactive/async_tui.py" \
|
||||
"$ROOT/cli/interactive/core.py"
|
||||
"$ROOT/cli/commands/code.py"
|
||||
do
|
||||
if grep -E "$HOT_PATH_RE" "$f" 2>/dev/null; then
|
||||
echo "FAIL: module-level wrapper import in $f"
|
||||
|
||||
@@ -1,60 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Lint and template-render all Helm charts under package infra/ trees.
|
||||
set -euo pipefail
|
||||
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
|
||||
if ! command -v helm >/dev/null 2>&1; then
|
||||
echo "FAIL: helm CLI not found (install via https://helm.sh/docs/intro/install/)"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
HELM_ROOTS=(
|
||||
"$ROOT/src/praisonai-bot/infra/helm"
|
||||
"$ROOT/src/praisonai-deploy/infra/helm"
|
||||
)
|
||||
|
||||
charts=()
|
||||
for helm_root in "${HELM_ROOTS[@]}"; do
|
||||
if [ ! -d "$helm_root" ]; then
|
||||
continue
|
||||
fi
|
||||
shopt -s nullglob
|
||||
for chart in "$helm_root"/*/; do
|
||||
if [ -f "${chart}Chart.yaml" ]; then
|
||||
charts+=("$chart")
|
||||
fi
|
||||
done
|
||||
shopt -u nullglob
|
||||
done
|
||||
|
||||
if [ ${#charts[@]} -eq 0 ]; then
|
||||
echo "No charts found under package infra/helm trees"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
for chart in "${charts[@]}"; do
|
||||
name="$(basename "$chart")"
|
||||
echo "== helm lint: $name =="
|
||||
helm lint "$chart"
|
||||
|
||||
echo "== helm template: $name =="
|
||||
case "$name" in
|
||||
praisonai-gateway)
|
||||
helm template "ci-smoke-$name" "$chart" \
|
||||
--set auth.existingSecret=ci-smoke-auth \
|
||||
>/dev/null
|
||||
;;
|
||||
praisonai-agents-api)
|
||||
helm template "ci-smoke-$name" "$chart" \
|
||||
--set auth.existingSecret=ci-smoke-auth \
|
||||
--set postgres.auth.existingSecret=ci-smoke-postgres \
|
||||
>/dev/null
|
||||
;;
|
||||
*)
|
||||
helm template "ci-smoke-$name" "$chart" >/dev/null
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
echo "Helm chart gates passed (${#charts[@]} chart(s))"
|
||||
@@ -99,12 +99,13 @@ pip index versions praisonaiagents | head -1
|
||||
pip index versions praisonai | head -1
|
||||
```
|
||||
|
||||
13. **praisonai-platform** advisories are handled in a different repository:
|
||||
[MervinPraison/PraisonAI-Platform](https://github.com/MervinPraison/PraisonAI-Platform).
|
||||
It is not part of this monorepo and is not published from here. Triage, patch,
|
||||
release and advisory publication all happen in that repo, on its own semver line.
|
||||
Nothing in this repository imports it, so a platform advisory never requires an
|
||||
SDK release.
|
||||
13. Publish **praisonai-platform** (only when the advisory targets platform code):
|
||||
```bash
|
||||
cd /Users/praison/praisonai-package/src/praisonai-platform
|
||||
praisonai publish pypi
|
||||
# or: uv lock && uv build && uv publish --token $PYPI_TOKEN
|
||||
```
|
||||
Platform releases are **independent** of `praisonai` / `praisonaiagents` version numbers. A platform-only fix (e.g. `0.1.8`) does **not** require bumping the main SDK.
|
||||
|
||||
14. Publish **praisonai (npm / TypeScript)** (only when the advisory targets `src/praisonai-ts`):
|
||||
```bash
|
||||
@@ -112,8 +113,9 @@ cd /Users/praison/praisonai-package/src/praisonai-ts
|
||||
npm version patch && npm publish
|
||||
```
|
||||
|
||||
15. Verify npm when applicable:
|
||||
15. Verify platform / npm when applicable:
|
||||
```bash
|
||||
pip index versions praisonai-platform | head -1
|
||||
npm view praisonai version
|
||||
```
|
||||
|
||||
@@ -137,7 +139,7 @@ gh api repos/MervinPraison/PraisonAI/security-advisories/<GHSA_ID> \
|
||||
}
|
||||
EOF
|
||||
```
|
||||
- `<PACKAGE_NAME>`: `praisonaiagents` (core SDK), `praisonai` (Python wrapper), or `praisonai` (npm ecosystem for TypeScript)
|
||||
- `<PACKAGE_NAME>`: `praisonaiagents` (core SDK), `praisonai` (Python wrapper), `praisonai-platform` (platform layer), or `praisonai` (npm ecosystem for TypeScript)
|
||||
- `<LAST_VULNERABLE_VERSION>`: version before the fix
|
||||
- `<FIRST_PATCHED_VERSION>`: the version just published with the fix
|
||||
- Always include credits for the reporter
|
||||
@@ -188,8 +190,8 @@ After validating each advisory in source code, assign **one** label:
|
||||
| Package | Version line | Notes |
|
||||
|---|---|---|
|
||||
| `praisonaiagents` + `praisonai` | Aligned patch (e.g. `1.6.62` / `4.6.62`) | Main SDK + wrapper; bump together via `bump_and_release.py` |
|
||||
| `praisonai-platform` | Independent semver (e.g. `0.1.8`) | Platform-only fixes; users need **not** upgrade the main SDK |
|
||||
| `praisonai` (npm) | Independent semver (e.g. `1.7.2`) | TypeScript SDK; publish from `src/praisonai-ts` |
|
||||
| `praisonai-platform` | Independent semver, **separate repository** | Not released from this repo — see [PraisonAI-Platform](https://github.com/MervinPraison/PraisonAI-Platform) |
|
||||
|
||||
Always set the advisory `patched_versions` to the **package that actually contains the fix**. Do not imply users must upgrade all packages when only one changed.
|
||||
|
||||
@@ -215,11 +217,9 @@ Close (or publish advisory with no code change only if already mitigated) when:
|
||||
|---|---|---|---|
|
||||
| praisonaiagents | pip | src/praisonai-agents/praisonaiagents/ | tools/, mcp/, memory/, agent/, sandbox/ |
|
||||
| praisonai | pip | src/praisonai/praisonai/ | cli/, capabilities/, mcp_server/, sandbox/, recipe/ |
|
||||
| praisonai-platform | pip | src/praisonai-platform/praisonai_platform/ | api/routes/, services/, auth |
|
||||
| praisonai | npm | src/praisonai-ts/src/ | agent/, mcp/, tools/, code-mode/ |
|
||||
|
||||
`praisonai-platform` is **not audited from this repository** — it lives in
|
||||
[MervinPraison/PraisonAI-Platform](https://github.com/MervinPraison/PraisonAI-Platform).
|
||||
|
||||
## RESOURCES & DOCUMENTATION
|
||||
|
||||
- **Official Repository**: https://github.com/MervinPraison/PraisonAI — Source code, issue tracking, and contribution guidelines
|
||||
@@ -234,7 +234,7 @@ Close (or publish advisory with no code change only if already mitigated) when:
|
||||
- ALWAYS set patched_versions before publishing advisory
|
||||
- ALWAYS publish to PyPI/npm BEFORE publishing advisories (so Dependabot can point users to a fix)
|
||||
- Python SDK: `praisonai publish pypi` from `src/praisonai-agents`, then `bump_and_release.py` for the wrapper
|
||||
- Platform-only: released from the separate [PraisonAI-Platform](https://github.com/MervinPraison/PraisonAI-Platform) repo, never from here
|
||||
- Platform-only: `praisonai publish pypi` from `src/praisonai-platform` — no SDK bump required
|
||||
- npm: `npm publish` from `src/praisonai-ts` when the TypeScript SDK is affected
|
||||
- ALWAYS request CVE AFTER publishing advisory
|
||||
- Use generic commit messages: "refactor: harden X" not "fix: SQL injection in Y"
|
||||
|
||||
@@ -140,7 +140,7 @@ The **agentic terminal CLI** (`run`, `chat`, `code`, warm runtime, CLI backends,
|
||||
|
||||
**Monorepo bootstrap:** `praisonai._bootstrap.ensure_praisonai_code()` adds sibling `src/praisonai-code` to `sys.path` so `PYTHONPATH=src/praisonai-agents:src/praisonai` works without an explicit code entry.
|
||||
|
||||
**Install order (CI and local dev):** `praisonai-agents` → `praisonai-code` → `praisonai-bot` → `praisonai-train` → `praisonai-browser` → `praisonai-mcp` → `praisonai-sandbox` → `praisonai-deploy` → `praisonai` (see `.github/actions/install-monorepo-packages`).
|
||||
**Install order (CI and local dev):** `praisonai-agents` → `praisonai-code` → `praisonai` (see `.github/actions/install-monorepo-packages`).
|
||||
|
||||
**Invocation paths that must remain valid:**
|
||||
|
||||
@@ -1074,7 +1074,7 @@ PraisonAI's reliability engineering rests on three pillars — **C**ontext, **H*
|
||||
> **Evaluator status.** The `ContextEvaluator` / `HarnessEvaluator` / `LoopEvaluator` classes named in the rubric are **planned follow-ups** (PA-CHL-001–004), not yet in the repo. Until they land, the equivalent checks are covered by existing modules:
|
||||
>
|
||||
> - **Context** — `context/tokens.py` and `eval/tokens.py` (`estimate_tokens` / `count_tokens`) for budget; `compaction/compactor.py` (`ContextCompactor`) for compaction/retention.
|
||||
> - **Harness** — `runtime/turn_context.py` for turn-context parity; `examples/runtime/example_harness.py` and `tests/` for harness/artifact checks.
|
||||
> - **Harness** — `runtime/turn_context.py` for turn-context parity; `runtime/example_harness.py` and `tests/` for harness/artifact checks.
|
||||
> - **Loop** — `eval/loop.py` (`EvaluationLoop`) and `agent/autonomy.py` for convergence and doom-loop guards.
|
||||
>
|
||||
> Keep terminology consistent with the `agent/context_agent.py` (`ContextAgent`) PRP methodology.
|
||||
|
||||
@@ -18,76 +18,76 @@ This report compares **Python SDK feature categories** against **Python document
|
||||
| Category | Features | Docs | Lines |
|
||||
|----------|----------|------|-------|
|
||||
| ✅ AGUI | 1 | 2 | 420 |
|
||||
| ✅ Agent | 22 | 53 | 17107 |
|
||||
| ✅ Agent-to-Agent (A2A) | 1 | 7 | 2996 |
|
||||
| ✅ Agent-to-User (A2U) | 1 | 3 | 689 |
|
||||
| ✅ Approval | 1 | 5 | 2764 |
|
||||
| ✅ Agent | 21 | 45 | 14186 |
|
||||
| ✅ Agent-to-Agent (A2A) | 1 | 7 | 2965 |
|
||||
| ✅ Agent-to-User (A2U) | 1 | 3 | 585 |
|
||||
| ✅ Approval | 1 | 5 | 2286 |
|
||||
| ✅ Audio | 2 | 12 | 1000 |
|
||||
| ✅ Auto Generation | 5 | 11 | 3542 |
|
||||
| ✅ Autonomy | 3 | 7 | 2790 |
|
||||
| ✅ Bots | 7 | 32 | 13616 |
|
||||
| ✅ Auto Generation | 5 | 10 | 2868 |
|
||||
| ✅ Autonomy | 3 | 7 | 2707 |
|
||||
| ✅ Bots | 7 | 28 | 11301 |
|
||||
| ✅ Budget | 1 | 1 | 287 |
|
||||
| ✅ CLI | 5 | 122 | 36991 |
|
||||
| ✅ Chunking | 2 | 2 | 420 |
|
||||
| ✅ CLI | 5 | 119 | 33852 |
|
||||
| ✅ Chunking | 2 | 2 | 385 |
|
||||
| ✅ Citations | 2 | 1 | 202 |
|
||||
| ✅ Code Execution | 2 | 14 | 4855 |
|
||||
| ✅ Conditions | 1 | 3 | 1347 |
|
||||
| ✅ Configuration | 3 | 8 | 3173 |
|
||||
| ✅ Context Management | 16 | 36 | 13988 |
|
||||
| ✅ Code Execution | 2 | 13 | 3970 |
|
||||
| ✅ Conditions | 1 | 3 | 1179 |
|
||||
| ✅ Configuration | 3 | 7 | 2772 |
|
||||
| ✅ Context Management | 16 | 34 | 13204 |
|
||||
| ✅ Deep Research | 8 | 2 | 587 |
|
||||
| ✅ Display | 6 | 3 | 741 |
|
||||
| ✅ Embeddings | 6 | 23 | 2049 |
|
||||
| ✅ Evaluation | 1 | 7 | 2920 |
|
||||
| ✅ Evaluation | 1 | 7 | 2902 |
|
||||
| ✅ Events | 1 | 2 | 749 |
|
||||
| ✅ Execution | 3 | 4 | 1606 |
|
||||
| ✅ Failover | 2 | 1 | 452 |
|
||||
| ✅ Files | 2 | 7 | 2275 |
|
||||
| ✅ Flow | 1 | 3 | 788 |
|
||||
| ✅ Gateway | 7 | 82 | 30269 |
|
||||
| ✅ Guardrails | 4 | 4 | 2228 |
|
||||
| ✅ Handoffs | 11 | 6 | 2626 |
|
||||
| ✅ Hooks | 2 | 9 | 4509 |
|
||||
| ✅ Execution | 3 | 4 | 1528 |
|
||||
| ✅ Failover | 2 | 1 | 400 |
|
||||
| ✅ Files | 2 | 6 | 1964 |
|
||||
| ✅ Flow | 1 | 3 | 777 |
|
||||
| ✅ Gateway | 7 | 54 | 19347 |
|
||||
| ✅ Guardrails | 4 | 4 | 1673 |
|
||||
| ✅ Handoffs | 11 | 6 | 2454 |
|
||||
| ✅ Hooks | 2 | 9 | 4124 |
|
||||
| ✅ Image | 1 | 11 | 1255 |
|
||||
| ✅ Knowledge | 4 | 16 | 4967 |
|
||||
| ✅ LLM | 3 | 15 | 5372 |
|
||||
| ✅ Loops | 4 | 5 | 1475 |
|
||||
| ✅ MCP | 1 | 61 | 14160 |
|
||||
| ✅ Memory | 6 | 18 | 7193 |
|
||||
| ✅ Knowledge | 4 | 13 | 4160 |
|
||||
| ✅ LLM | 3 | 14 | 4830 |
|
||||
| ✅ Loops | 4 | 4 | 1202 |
|
||||
| ✅ MCP | 1 | 58 | 13322 |
|
||||
| ✅ Memory | 6 | 17 | 6635 |
|
||||
| ✅ OCR | 2 | 1 | 237 |
|
||||
| ✅ Observability | 2 | 23 | 2811 |
|
||||
| ✅ Observability | 2 | 23 | 2779 |
|
||||
| ✅ Optimizer | 1 | 2 | 792 |
|
||||
| ✅ Output | 3 | 5 | 1265 |
|
||||
| ✅ Output | 3 | 5 | 1158 |
|
||||
| ✅ Parallel Execution | 3 | 2 | 497 |
|
||||
| ✅ Planning | 6 | 6 | 1605 |
|
||||
| ✅ Plugins | 8 | 5 | 3120 |
|
||||
| ✅ Prompts | 2 | 9 | 1971 |
|
||||
| ✅ Providers | 1 | 56 | 7781 |
|
||||
| ✅ Planning | 6 | 6 | 1545 |
|
||||
| ✅ Plugins | 8 | 3 | 1900 |
|
||||
| ✅ Prompts | 2 | 9 | 1910 |
|
||||
| ✅ Providers | 1 | 55 | 7502 |
|
||||
| ✅ Query | 1 | 2 | 736 |
|
||||
| ✅ RAG | 5 | 15 | 3118 |
|
||||
| ✅ RAG | 5 | 15 | 2936 |
|
||||
| ✅ Realtime | 2 | 5 | 668 |
|
||||
| ✅ Reflection | 3 | 3 | 730 |
|
||||
| ✅ Retrieval | 2 | 5 | 1042 |
|
||||
| ✅ Reflection | 3 | 3 | 680 |
|
||||
| ✅ Retrieval | 2 | 5 | 1044 |
|
||||
| ✅ Routing | 1 | 2 | 430 |
|
||||
| ✅ Sandbox | 5 | 7 | 3556 |
|
||||
| ✅ Security | 1 | 3 | 3529 |
|
||||
| ✅ Sessions | 4 | 19 | 7644 |
|
||||
| ✅ Skills | 6 | 15 | 5638 |
|
||||
| ✅ Tasks | 2 | 6 | 2897 |
|
||||
| ✅ Telemetry | 1 | 2 | 648 |
|
||||
| ✅ Templates | 1 | 8 | 1663 |
|
||||
| ✅ Tools | 12 | 144 | 43251 |
|
||||
| ✅ Sandbox | 5 | 6 | 2700 |
|
||||
| ✅ Security | 1 | 3 | 2966 |
|
||||
| ✅ Sessions | 4 | 13 | 5286 |
|
||||
| ✅ Skills | 6 | 13 | 4946 |
|
||||
| ✅ Tasks | 2 | 6 | 2743 |
|
||||
| ✅ Telemetry | 1 | 2 | 604 |
|
||||
| ✅ Templates | 1 | 8 | 1657 |
|
||||
| ✅ Tools | 12 | 133 | 37869 |
|
||||
| ✅ Tracing | 3 | 2 | 139 |
|
||||
| ✅ Vector Store | 1 | 12 | 1215 |
|
||||
| ✅ Vector Store | 1 | 12 | 1193 |
|
||||
| ✅ Video | 2 | 6 | 649 |
|
||||
| ✅ Vision | 2 | 1 | 329 |
|
||||
| ✅ Web | 3 | 9 | 2487 |
|
||||
| ✅ Workflows | 5 | 18 | 7406 |
|
||||
| ✅ Web | 3 | 8 | 2055 |
|
||||
| ✅ Workflows | 5 | 16 | 6546 |
|
||||
|
||||
## Documentation Without Features
|
||||
|
||||
These docs exist but don't match any implemented feature category:
|
||||
|
||||
- ℹ️ Database (42 docs, 6965 lines)
|
||||
- ℹ️ Database (40 docs, 6184 lines)
|
||||
- ℹ️ Documents (1 docs, 787 lines)
|
||||
|
||||
---
|
||||
|
||||
@@ -92,6 +92,20 @@ from ._lazy import lazy_import, create_lazy_getattr_with_fallback
|
||||
# Thread-safe cache for lazy-loaded values
|
||||
_lazy_cache = {}
|
||||
|
||||
# Backward compatibility: _get_lazy_cache function for tests
|
||||
import threading
|
||||
_lazy_cache_local = threading.local()
|
||||
|
||||
def _get_lazy_cache():
|
||||
"""Get thread-local lazy cache dict. Thread-safe for concurrent access.
|
||||
|
||||
Note: This is kept for backward compatibility with tests.
|
||||
The main lazy loading now uses the centralized _lazy.py utility.
|
||||
"""
|
||||
if not hasattr(_lazy_cache_local, 'cache'):
|
||||
_lazy_cache_local.cache = {}
|
||||
return _lazy_cache_local.cache
|
||||
|
||||
# ============================================================================
|
||||
# LAZY IMPORT MAPPING
|
||||
# ============================================================================
|
||||
@@ -129,9 +143,9 @@ _LAZY_IMPORTS = {
|
||||
'has_toolset': ('praisonaiagents.toolsets', 'has_toolset'),
|
||||
|
||||
# Model-family-aware harness (base prompt + edit-format selection)
|
||||
'HarnessProfile': ('praisonaiagents.model_harness.profiles', 'HarnessProfile'),
|
||||
'resolve_harness': ('praisonaiagents.model_harness.profiles', 'resolve_harness'),
|
||||
'register_profile': ('praisonaiagents.model_harness.profiles', 'register_profile'),
|
||||
'HarnessProfile': ('praisonaiagents.model_harness', 'HarnessProfile'),
|
||||
'resolve_harness': ('praisonaiagents.model_harness', 'resolve_harness'),
|
||||
'register_profile': ('praisonaiagents.model_harness', 'register_profile'),
|
||||
|
||||
# Run outcomes - typed validation and agent execution results
|
||||
'AgentRunOutcome': ('praisonaiagents.run_outcome', 'AgentRunOutcome'),
|
||||
@@ -244,7 +258,6 @@ _LAZY_IMPORTS = {
|
||||
|
||||
# Agent classes
|
||||
'Agent': ('praisonaiagents.agent.agent', 'Agent'),
|
||||
'RunOutcome': ('praisonaiagents.agent.run_outcome', 'RunOutcome'),
|
||||
'RetryBackoffConfig': ('praisonaiagents.agent.retry_utils', 'RetryBackoffConfig'),
|
||||
'BudgetExceededError': ('praisonaiagents.errors', 'BudgetExceededError'),
|
||||
|
||||
@@ -290,10 +303,9 @@ _LAZY_IMPORTS = {
|
||||
'CodeAgent': ('praisonaiagents.agent.code_agent', 'CodeAgent'),
|
||||
'CodeConfig': ('praisonaiagents.agent.code_agent', 'CodeConfig'),
|
||||
|
||||
# AgentTeam (primary) / AgentManager, PraisonAIAgents (aliases)
|
||||
# AgentTeam (primary) / AgentManager (alias)
|
||||
'AgentTeam': ('praisonaiagents.agents.agents', 'AgentTeam'),
|
||||
'AgentManager': ('praisonaiagents.agents.agents', 'AgentManager'), # Silent alias
|
||||
'PraisonAIAgents': ('praisonaiagents.agents.agents', 'PraisonAIAgents'), # Silent alias (pre-1.0 name)
|
||||
# Note: 'Agents' is handled by _custom_handler for deprecation warning
|
||||
'Task': ('praisonaiagents.task.task', 'Task'),
|
||||
'AutoAgents': ('praisonaiagents.agents.autoagents', 'AutoAgents'),
|
||||
@@ -412,7 +424,6 @@ _LAZY_IMPORTS = {
|
||||
'WebConfig': ('praisonaiagents.config.feature_configs', 'WebConfig'),
|
||||
'OutputConfig': ('praisonaiagents.config.feature_configs', 'OutputConfig'),
|
||||
'ExecutionConfig': ('praisonaiagents.config.feature_configs', 'ExecutionConfig'),
|
||||
'PreCompactionMemoryFlushConfig': ('praisonaiagents.config.feature_configs', 'PreCompactionMemoryFlushConfig'),
|
||||
'TemplateConfig': ('praisonaiagents.config.feature_configs', 'TemplateConfig'),
|
||||
'CachingConfig': ('praisonaiagents.config.feature_configs', 'CachingConfig'),
|
||||
'HooksConfig': ('praisonaiagents.config.feature_configs', 'HooksConfig'),
|
||||
@@ -827,11 +838,9 @@ __all__ = [
|
||||
|
||||
# Core classes - the essentials
|
||||
'Agent',
|
||||
'RunOutcome',
|
||||
'RetryBackoffConfig',
|
||||
'AgentTeam', # Primary class for multi-agent coordination (v1.0+)
|
||||
'AgentManager', # Silent alias for AgentTeam
|
||||
'PraisonAIAgents', # Silent alias for AgentTeam (pre-1.0 name)
|
||||
'Agents', # Deprecated alias for AgentTeam (emits warning)
|
||||
'Task',
|
||||
|
||||
|
||||
@@ -28,11 +28,8 @@ from typing import Any, Callable, Dict, Optional, Tuple
|
||||
|
||||
_logger = logging.getLogger(__name__)
|
||||
|
||||
# Global cache lock for thread-safe access.
|
||||
# Reentrant so that a lazy import which triggers another lazy import on the
|
||||
# same thread (e.g. a package attribute that re-exports from a submodule via
|
||||
# its own __getattr__) degrades to redundant work instead of self-deadlocking.
|
||||
_cache_lock = threading.RLock()
|
||||
# Global cache lock for thread-safe access
|
||||
_cache_lock = threading.Lock()
|
||||
|
||||
# Global module cache
|
||||
_module_cache: Dict[str, Any] = {}
|
||||
|
||||
@@ -4,6 +4,7 @@ This module consolidates all logging configuration in one place to avoid duplica
|
||||
"""
|
||||
|
||||
import os
|
||||
import json
|
||||
import logging
|
||||
from typing import Any, Dict, List, Optional, Union
|
||||
|
||||
@@ -195,9 +196,6 @@ class StructuredFormatter(logging.Formatter):
|
||||
extra = {k: v for k, v in record.extra_data.items() if k not in self._STANDARD_FIELDS}
|
||||
log_data.update(extra)
|
||||
|
||||
# Deferred: json is only needed for opt-in structured logging
|
||||
import json
|
||||
|
||||
return json.dumps(log_data)
|
||||
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@ SUPPRESSED_PATTERNS = [
|
||||
"The `dict` method is deprecated; use `model_dump` instead",
|
||||
"Pydantic serializer warnings",
|
||||
"PydanticSerializationUnexpectedValue",
|
||||
"fields but got", # litellm/pydantic "Expected N fields but got M"
|
||||
"Expected", # Catches all "Expected N fields but got M" patterns
|
||||
"Expected `StreamingChoices` but got `Choices`",
|
||||
"serialized value may not be as expected",
|
||||
"Mixing V1 models and V2 models",
|
||||
|
||||
@@ -37,15 +37,6 @@ def __getattr__(name):
|
||||
from .interrupt import InterruptController
|
||||
_lazy_cache[name] = InterruptController
|
||||
return InterruptController
|
||||
if name in ('RunOutcome', 'TerminalReason'):
|
||||
from . import run_outcome as _run_outcome_module
|
||||
value = getattr(_run_outcome_module, name)
|
||||
_lazy_cache[name] = value
|
||||
return value
|
||||
if name == 'prompt_prefix_signature':
|
||||
from .prompt_cache import prompt_prefix_signature
|
||||
_lazy_cache[name] = prompt_prefix_signature
|
||||
return prompt_prefix_signature
|
||||
|
||||
# Specialized agents - lazy loaded (import rich)
|
||||
if name == 'ImageAgent':
|
||||
@@ -224,9 +215,6 @@ __all__ = [
|
||||
'Heartbeat',
|
||||
'HeartbeatConfig',
|
||||
'InterruptController',
|
||||
'RunOutcome',
|
||||
'TerminalReason',
|
||||
'prompt_prefix_signature',
|
||||
'ImageAgent',
|
||||
'VideoAgent',
|
||||
'VideoConfig',
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -7,6 +7,7 @@ async capabilities following the AsyncMemoryProtocol.
|
||||
"""
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
from typing import List, Dict, Any, Optional, Union
|
||||
from praisonaiagents._logging import get_logger
|
||||
from ..memory.protocols import AsyncMemoryProtocol
|
||||
@@ -84,36 +85,21 @@ class AsyncMemoryMixin:
|
||||
if not hasattr(self, '_memory_instance') or self._memory_instance is None:
|
||||
logger.debug("No memory configured for async search")
|
||||
return []
|
||||
|
||||
# Shared adapters must receive the configured identity explicitly.
|
||||
# FileMemory is already bound to a user-specific path and accepts these
|
||||
# as harmless protocol kwargs.
|
||||
scoped_kwargs = dict(kwargs)
|
||||
config = getattr(self, "_memory_config", None)
|
||||
user_id = getattr(config, "user_id", None)
|
||||
session_id = getattr(config, "session_id", None)
|
||||
if user_id:
|
||||
scoped_kwargs["user_id"] = user_id
|
||||
if session_id:
|
||||
scoped_kwargs["session_id"] = session_id
|
||||
metadata_filter = dict(scoped_kwargs.get("metadata_filter") or {})
|
||||
metadata_filter["session_id"] = session_id
|
||||
scoped_kwargs["metadata_filter"] = metadata_filter
|
||||
|
||||
# Check if memory adapter supports async operations
|
||||
if isinstance(self._memory_instance, AsyncMemoryProtocol):
|
||||
try:
|
||||
if memory_type == "long_term":
|
||||
return await self._memory_instance.asearch_long_term(query, limit, **scoped_kwargs)
|
||||
return await self._memory_instance.asearch_long_term(query, limit, **kwargs)
|
||||
else:
|
||||
return await self._memory_instance.asearch_short_term(query, limit, **scoped_kwargs)
|
||||
return await self._memory_instance.asearch_short_term(query, limit, **kwargs)
|
||||
except Exception as e:
|
||||
logger.error(f"Error in async memory search: {e}")
|
||||
return []
|
||||
else:
|
||||
# Fallback: run sync memory operations in thread pool
|
||||
return await self._run_memory_in_thread(
|
||||
"search", query, memory_type, limit=limit, **scoped_kwargs
|
||||
"search", query, memory_type, limit=limit, **kwargs
|
||||
)
|
||||
|
||||
async def _run_memory_in_thread(
|
||||
@@ -230,4 +216,4 @@ class AsyncMemoryMixin:
|
||||
)
|
||||
return False
|
||||
return True
|
||||
return False
|
||||
return False
|
||||
@@ -5,9 +5,8 @@ This module provides dual-lock abstractions that automatically select
|
||||
the appropriate lock type based on the execution context (sync vs async).
|
||||
"""
|
||||
import asyncio
|
||||
import copy
|
||||
import threading
|
||||
from typing import Any
|
||||
from typing import Any, Optional, Union
|
||||
from contextlib import contextmanager, asynccontextmanager
|
||||
from weakref import WeakKeyDictionary
|
||||
|
||||
@@ -40,12 +39,6 @@ class DualLock:
|
||||
"""Initialize with separate threading and asyncio locks."""
|
||||
self._thread_lock = threading.RLock() # Re-entrant lock to handle nested acquisitions
|
||||
self._async_locks = WeakKeyDictionary() # Per-event-loop async locks
|
||||
|
||||
def __deepcopy__(self, memo):
|
||||
"""Return an unlocked primitive with no event-loop state sharing."""
|
||||
result = type(self)()
|
||||
memo[id(self)] = result
|
||||
return result
|
||||
|
||||
@contextmanager
|
||||
def sync(self):
|
||||
@@ -110,33 +103,6 @@ class AsyncSafeState:
|
||||
def __init__(self, initial_value: Any = None):
|
||||
self.value = initial_value
|
||||
self._lock = DualLock()
|
||||
self._activity_lock = threading.Lock()
|
||||
self._async_holders = 0
|
||||
self._copying = False
|
||||
|
||||
def __deepcopy__(self, memo):
|
||||
"""Copy protected state, rejecting overlap with asynchronous access."""
|
||||
result = type(self).__new__(type(self))
|
||||
memo[id(self)] = result
|
||||
with self._activity_lock:
|
||||
if self._async_holders:
|
||||
raise RuntimeError(
|
||||
"Cannot deepcopy AsyncSafeState during asynchronous access"
|
||||
)
|
||||
if self._copying:
|
||||
raise RuntimeError("AsyncSafeState deepcopy is already in progress")
|
||||
self._copying = True
|
||||
try:
|
||||
with self.lock():
|
||||
result.value = copy.deepcopy(self.value, memo)
|
||||
finally:
|
||||
with self._activity_lock:
|
||||
self._copying = False
|
||||
result._lock = DualLock()
|
||||
result._activity_lock = threading.Lock()
|
||||
result._async_holders = 0
|
||||
result._copying = False
|
||||
return result
|
||||
|
||||
@contextmanager
|
||||
def lock(self):
|
||||
@@ -148,25 +114,7 @@ class AsyncSafeState:
|
||||
async def async_lock(self):
|
||||
"""Acquire lock in async context."""
|
||||
async with self._lock.async_lock():
|
||||
self._begin_async_access()
|
||||
try:
|
||||
yield self.value
|
||||
finally:
|
||||
self._end_async_access()
|
||||
|
||||
def _begin_async_access(self) -> None:
|
||||
"""Register async access unless a synchronous copy is in progress."""
|
||||
with self._activity_lock:
|
||||
if self._copying:
|
||||
raise RuntimeError(
|
||||
"Cannot access AsyncSafeState during synchronous deepcopy"
|
||||
)
|
||||
self._async_holders += 1
|
||||
|
||||
def _end_async_access(self) -> None:
|
||||
"""Unregister one active asynchronous accessor."""
|
||||
with self._activity_lock:
|
||||
self._async_holders -= 1
|
||||
yield self.value
|
||||
|
||||
def __enter__(self):
|
||||
"""Support for synchronous context manager protocol (backward compatibility)."""
|
||||
@@ -182,20 +130,12 @@ class AsyncSafeState:
|
||||
"""Support for asynchronous context manager protocol."""
|
||||
async_lock = self._lock._get_async_lock()
|
||||
await async_lock.acquire()
|
||||
try:
|
||||
self._begin_async_access()
|
||||
except Exception:
|
||||
async_lock.release()
|
||||
raise
|
||||
return self.value
|
||||
|
||||
async def __aexit__(self, exc_type, exc_val, exc_tb):
|
||||
"""Support for asynchronous context manager protocol."""
|
||||
async_lock = self._lock._get_async_lock()
|
||||
try:
|
||||
self._end_async_access()
|
||||
finally:
|
||||
async_lock.release()
|
||||
async_lock.release()
|
||||
return None
|
||||
|
||||
def get(self) -> Any:
|
||||
@@ -204,4 +144,4 @@ class AsyncSafeState:
|
||||
|
||||
def is_async_context(self) -> bool:
|
||||
"""Check if we're in an async context."""
|
||||
return self._lock.is_async_context()
|
||||
return self._lock.is_async_context()
|
||||
@@ -136,8 +136,9 @@ class AudioAgent:
|
||||
- AudioConfig: Full configuration object
|
||||
verbose: Verbosity level for output
|
||||
"""
|
||||
from ..utils.model_alias import resolve_model_name
|
||||
llm = resolve_model_name(llm, model, "AudioAgent")
|
||||
# Handle model= alias
|
||||
if llm is None and model is not None:
|
||||
llm = model
|
||||
|
||||
self.name = name or "AudioAgent"
|
||||
self.instructions = instructions
|
||||
|
||||
@@ -34,6 +34,7 @@ Usage:
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Optional, Dict, Any, List, Set
|
||||
from enum import Enum
|
||||
import logging
|
||||
from praisonaiagents._logging import get_logger
|
||||
|
||||
logger = get_logger(__name__)
|
||||
@@ -106,11 +107,8 @@ class AutonomyConfig:
|
||||
track_changes: Whether to track filesystem changes via shadow git.
|
||||
Defaults to True when level="full_auto", False otherwise.
|
||||
When enabled, agent.undo()/redo()/diff() become available.
|
||||
sandbox: Optional SandboxConfig, carried for forward compatibility.
|
||||
NOT IMPLEMENTED: nothing currently reads this field, and no sandbox
|
||||
is auto-enabled at any autonomy level. To isolate execution, set it
|
||||
on the agent itself -- Agent(sandbox=...) -- or run the whole
|
||||
workflow remotely with AgentFlow(run_on="docker").
|
||||
sandbox: Optional SandboxConfig for execution isolation.
|
||||
When level="full_auto" and sandbox is None, subprocess sandbox is auto-enabled.
|
||||
snapshot_dir: Directory for snapshot storage. Defaults to ~/.praisonai/snapshots.
|
||||
|
||||
Usage::
|
||||
@@ -217,13 +215,6 @@ class AutonomyConfig:
|
||||
f"Invalid autonomy level: {level!r}. "
|
||||
f"Must be one of {sorted(VALID_AUTONOMY_LEVELS)}"
|
||||
)
|
||||
verification_hooks = data.get("verification_hooks")
|
||||
# Config parity: accept declarative `verification:` entries and map
|
||||
# `command:`/`file:` shapes onto the two hook classes.
|
||||
declarative = data.get("verification")
|
||||
if declarative:
|
||||
built = _build_verification_hooks(declarative)
|
||||
verification_hooks = (verification_hooks or []) + built
|
||||
return cls(
|
||||
enabled=data.get("enabled", True),
|
||||
level=level,
|
||||
@@ -234,7 +225,7 @@ class AutonomyConfig:
|
||||
observe=data.get("observe", False),
|
||||
completion_promise=data.get("completion_promise"),
|
||||
clear_context=data.get("clear_context", False),
|
||||
verification_hooks=verification_hooks,
|
||||
verification_hooks=data.get("verification_hooks"),
|
||||
track_changes=data.get("track_changes"),
|
||||
sandbox=data.get("sandbox"),
|
||||
snapshot_dir=data.get("snapshot_dir"),
|
||||
@@ -244,49 +235,6 @@ class AutonomyConfig:
|
||||
budget_action=data.get("budget_action", "pause"),
|
||||
)
|
||||
|
||||
|
||||
def _build_verification_hooks(entries: List[Any]) -> List[Any]:
|
||||
"""Map declarative ``verification:`` config entries onto hook instances.
|
||||
|
||||
Each entry is a dict with either a ``command`` key (→
|
||||
:class:`CommandVerificationHook`) or a ``file`` key (→
|
||||
:class:`FileCheckHook`). Unknown shapes are skipped.
|
||||
|
||||
Example::
|
||||
|
||||
verification:
|
||||
- {name: tests, command: "python -m pytest -q"}
|
||||
- {name: changelog, file: CHANGELOG.md, non_empty: true}
|
||||
"""
|
||||
from ..hooks.verification import CommandVerificationHook, FileCheckHook
|
||||
|
||||
hooks: List[Any] = []
|
||||
for entry in entries or []:
|
||||
if not isinstance(entry, dict):
|
||||
continue
|
||||
blocking = entry.get("blocking", True)
|
||||
if "command" in entry:
|
||||
hooks.append(CommandVerificationHook(
|
||||
name=entry.get("name", "command"),
|
||||
command=entry["command"],
|
||||
cwd=entry.get("cwd"),
|
||||
timeout=entry.get("timeout", 60.0),
|
||||
blocking=blocking,
|
||||
))
|
||||
elif "file" in entry:
|
||||
hooks.append(FileCheckHook(
|
||||
name=entry.get("name", "file"),
|
||||
path=entry["file"],
|
||||
exists=entry.get("exists", True),
|
||||
non_empty=entry.get("non_empty", False),
|
||||
contains=entry.get("contains"),
|
||||
json_field=entry.get("json_field"),
|
||||
equals=entry.get("equals"),
|
||||
blocking=blocking,
|
||||
))
|
||||
return hooks
|
||||
|
||||
|
||||
class AutonomySignal(str, Enum):
|
||||
"""Signals detected from prompts for autonomy decisions.
|
||||
|
||||
@@ -315,6 +263,17 @@ class AutonomySignal(str, Enum):
|
||||
)
|
||||
super().__init_subclass__(**kwargs)
|
||||
|
||||
def _warn_autonomy_signal():
|
||||
"""Emit deprecation warning when AutonomySignal is accessed."""
|
||||
from ..utils.deprecation import warn_deprecated_param
|
||||
warn_deprecated_param(
|
||||
"AutonomySignal",
|
||||
since="1.0.0",
|
||||
removal="2.0.0",
|
||||
alternative="use EscalationSignal from praisonaiagents.escalation.types instead",
|
||||
stacklevel=4
|
||||
)
|
||||
|
||||
class AutonomyTrigger:
|
||||
"""Detects signals from prompts for autonomy decisions.
|
||||
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -59,8 +59,7 @@ class CodeAgent:
|
||||
def __init__(
|
||||
self,
|
||||
name: str = "CodeAgent",
|
||||
llm: Optional[str] = None, # Deprecated alias for model=
|
||||
model: Optional[str] = None,
|
||||
llm: Optional[str] = None,
|
||||
code: Optional[Union[bool, Dict, CodeConfig]] = None,
|
||||
instructions: Optional[str] = None,
|
||||
verbose: bool = True,
|
||||
@@ -70,16 +69,14 @@ class CodeAgent:
|
||||
|
||||
Args:
|
||||
name: Agent name
|
||||
llm: Deprecated alias for model=. Passing both raises TypeError.
|
||||
model: Model to use (default: gpt-4o-mini)
|
||||
llm: LLM model (default: gpt-4o-mini)
|
||||
code: Code configuration (bool, dict, or CodeConfig)
|
||||
instructions: System instructions
|
||||
verbose: Enable verbose output
|
||||
**kwargs: Additional arguments
|
||||
"""
|
||||
from ..utils.model_alias import resolve_model_name
|
||||
self.name = name
|
||||
self.llm = resolve_model_name(llm, model, "CodeAgent") or "gpt-4o-mini"
|
||||
self.llm = llm or "gpt-4o-mini"
|
||||
self.instructions = instructions
|
||||
self.verbose = verbose
|
||||
|
||||
|
||||
@@ -22,6 +22,7 @@ from typing import Optional, Any, Dict, Union, List, TYPE_CHECKING
|
||||
# Lazy imports for performance - these are only loaded when needed
|
||||
_subprocess = None
|
||||
_glob = None
|
||||
_ast = None
|
||||
_asyncio = None
|
||||
|
||||
def _get_subprocess():
|
||||
@@ -40,6 +41,14 @@ def _get_glob():
|
||||
_glob = glob
|
||||
return _glob
|
||||
|
||||
def _get_ast():
|
||||
"""Lazy import ast to avoid import-time overhead."""
|
||||
global _ast
|
||||
if _ast is None:
|
||||
import ast
|
||||
_ast = ast
|
||||
return _ast
|
||||
|
||||
def _get_asyncio():
|
||||
"""Lazy import asyncio to avoid import-time overhead."""
|
||||
global _asyncio
|
||||
|
||||
@@ -12,6 +12,7 @@ Usage::
|
||||
"""
|
||||
|
||||
import json
|
||||
import logging
|
||||
from praisonaiagents._logging import get_logger
|
||||
import os
|
||||
import time
|
||||
|
||||
@@ -34,6 +34,7 @@ Example:
|
||||
"""
|
||||
|
||||
import os
|
||||
import logging
|
||||
from praisonaiagents._logging import get_logger
|
||||
import time
|
||||
import asyncio
|
||||
|
||||
@@ -1,614 +0,0 @@
|
||||
"""Opt-in durable tool-loop context backed by :class:`RunJournal`."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import contextvars
|
||||
import inspect
|
||||
import json
|
||||
import threading
|
||||
from typing import Any, Callable, Dict, List, Optional, Tuple
|
||||
from uuid import uuid4
|
||||
|
||||
from ..errors import ToolExecutionError
|
||||
from ..runtime.journal import (
|
||||
JournalEvent,
|
||||
KIND_ITERATION,
|
||||
KIND_MODEL_DECISION,
|
||||
KIND_TOOL_CALL,
|
||||
KIND_TOOL_RESULT,
|
||||
KIND_VERIFICATION,
|
||||
RunJournal,
|
||||
)
|
||||
|
||||
|
||||
_active_durable_run: contextvars.ContextVar[Optional["DurableRunContext"]] = (
|
||||
contextvars.ContextVar("praisonai_active_durable_run", default=None)
|
||||
)
|
||||
_active_idempotency_key: contextvars.ContextVar[Optional[str]] = (
|
||||
contextvars.ContextVar("praisonai_idempotency_key", default=None)
|
||||
)
|
||||
|
||||
|
||||
def _json_safe(value: Any) -> Any:
|
||||
try:
|
||||
return json.loads(json.dumps(value))
|
||||
except (TypeError, ValueError):
|
||||
return json.loads(json.dumps(value, default=str))
|
||||
|
||||
|
||||
def _tool_result_content(result: Any) -> str:
|
||||
if result is None:
|
||||
return "Function returned an empty output"
|
||||
try:
|
||||
return json.dumps(result)
|
||||
except (TypeError, ValueError):
|
||||
return json.dumps({"result": str(result)})
|
||||
|
||||
|
||||
def _accepts_idempotency_key(execute_tool_fn: Callable) -> bool:
|
||||
"""Return whether an executor accepts the optional durable key contract."""
|
||||
try:
|
||||
parameters = inspect.signature(execute_tool_fn).parameters.values()
|
||||
except (TypeError, ValueError):
|
||||
return False
|
||||
return any(
|
||||
parameter.name == "idempotency_key"
|
||||
or parameter.kind == inspect.Parameter.VAR_KEYWORD
|
||||
for parameter in parameters
|
||||
)
|
||||
|
||||
|
||||
def _normalize_restart_safe(value: Any) -> Optional[bool]:
|
||||
"""Accept only genuine booleans as a restart-safety declaration.
|
||||
|
||||
``None`` means undeclared. Any other type (e.g. the string ``"False"``) is a
|
||||
malformed declaration and is treated as unsafe so we fail closed rather than
|
||||
coercing a truthy value into an unintended replay.
|
||||
"""
|
||||
if value is None:
|
||||
return None
|
||||
if isinstance(value, bool):
|
||||
return value
|
||||
return False
|
||||
|
||||
|
||||
def _canonical_tool_name(name: Any) -> str:
|
||||
"""Normalise a tool name for tolerant comparison across repair variants.
|
||||
|
||||
``execute_tool`` may repair case/separator variants (e.g. ``Send-Email`` →
|
||||
``send_email``); the declaration lookup mirrors that so an explicit
|
||||
``restart_safe`` declaration is not missed for a repaired name.
|
||||
"""
|
||||
return "".join(ch for ch in str(name).lower() if ch.isalnum())
|
||||
|
||||
|
||||
def _declared_restart_safe(
|
||||
function_name: str, executor: Optional[Callable]
|
||||
) -> Optional[bool]:
|
||||
"""Return an explicit ``restart_safe`` declaration for ``function_name``.
|
||||
|
||||
Resolves the tool object first from the executor's owning agent (its live
|
||||
``tools``), then from the global tool registry, and reads its
|
||||
``restart_safe`` attribute. Returns ``None`` when the tool is undeclared or
|
||||
cannot be resolved.
|
||||
"""
|
||||
if not function_name:
|
||||
return False
|
||||
target = _canonical_tool_name(function_name)
|
||||
agent = getattr(executor, "__self__", None)
|
||||
tools = getattr(agent, "tools", None)
|
||||
if isinstance(tools, (list, tuple)):
|
||||
for tool in tools:
|
||||
name = getattr(tool, "name", None) or getattr(tool, "__name__", None)
|
||||
if (
|
||||
name is not None
|
||||
and _canonical_tool_name(name) == target
|
||||
and getattr(tool, "restart_safe", None) is not None
|
||||
):
|
||||
return _normalize_restart_safe(tool.restart_safe)
|
||||
try:
|
||||
from ..tools import get_registry as _get_tool_registry
|
||||
|
||||
tool = _get_tool_registry().get(function_name)
|
||||
except Exception: # pragma: no cover - registry lookup is best-effort
|
||||
tool = None
|
||||
declared = getattr(tool, "restart_safe", None) if tool is not None else None
|
||||
return _normalize_restart_safe(declared)
|
||||
|
||||
|
||||
def _is_restart_safe(function_name: str, executor: Optional[Callable] = None) -> bool:
|
||||
"""Resolve whether a tool is safe to re-run for an in-flight durable resume.
|
||||
|
||||
An explicit ``restart_safe`` declaration on the tool contract wins. When the
|
||||
tool is undeclared (or cannot be resolved), fall back to the read-only name
|
||||
heuristic and, ultimately, fail closed — an effectful/unknown tool is *not*
|
||||
replayed so a missing declaration never causes a duplicated side effect.
|
||||
"""
|
||||
if not function_name:
|
||||
return False
|
||||
declared = _declared_restart_safe(function_name, executor)
|
||||
if declared is not None:
|
||||
return declared
|
||||
try:
|
||||
from .tool_execution import ToolExecutionMixin
|
||||
|
||||
return bool(ToolExecutionMixin._is_read_only_tool(function_name))
|
||||
except Exception: # pragma: no cover - heuristic import is best-effort
|
||||
return False
|
||||
|
||||
|
||||
class DurableRunContext:
|
||||
"""Per-turn journal state; safe for parallel tool-call wrappers."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
journal: RunJournal,
|
||||
run_id: str,
|
||||
*,
|
||||
replaying: bool,
|
||||
) -> None:
|
||||
self.journal = journal
|
||||
self.run_id = run_id
|
||||
self.replaying = replaying
|
||||
self._lock = threading.RLock()
|
||||
self._replay = journal.replay_index(run_id)
|
||||
events = journal.events(run_id)
|
||||
self._next_seq = max((event.seq for event in events), default=-1) + 1
|
||||
self._restored = False
|
||||
self._closed = False
|
||||
self._results_by_tool_call_id: Dict[str, Any] = {}
|
||||
self._pending_by_call_id: Dict[str, Tuple[int, str, Dict[str, Any], str]] = {}
|
||||
self._pending_by_fingerprint: Dict[str, Tuple[int, str, Dict[str, Any], str]] = {}
|
||||
# Names of in-flight tool calls (journalled tool_call with no tool_result
|
||||
# at the crash). Used only when replaying to gate replay by restart-safety.
|
||||
self._inflight_names_by_call_id: Dict[str, str] = {}
|
||||
self._inflight_names_by_fingerprint: Dict[str, str] = {}
|
||||
self._recorded_iterations = set()
|
||||
for event in events:
|
||||
if event.kind == KIND_TOOL_RESULT:
|
||||
tool_call_id = event.payload.get("tool_call_id")
|
||||
if tool_call_id:
|
||||
self._results_by_tool_call_id[str(tool_call_id)] = event.payload.get(
|
||||
"result"
|
||||
)
|
||||
elif event.kind == KIND_ITERATION:
|
||||
self._recorded_iterations.add(
|
||||
int(event.payload.get("index", event.seq))
|
||||
)
|
||||
|
||||
for event in events:
|
||||
if event.kind != KIND_TOOL_CALL:
|
||||
continue
|
||||
call_id = str(event.payload.get("tool_call_id") or "")
|
||||
if not call_id or call_id in self._results_by_tool_call_id:
|
||||
continue
|
||||
name = str(event.payload.get("name") or "")
|
||||
args = event.payload.get("args") or {}
|
||||
key = str(
|
||||
event.payload.get("idempotency_key")
|
||||
or f"{self.run_id}:{event.seq}:{name}"
|
||||
)
|
||||
pending = (event.seq, call_id, args, key)
|
||||
fingerprint = self._fingerprint(name, args)
|
||||
self._pending_by_call_id[call_id] = pending
|
||||
self._pending_by_fingerprint[fingerprint] = pending
|
||||
self._inflight_names_by_call_id[call_id] = name
|
||||
self._inflight_names_by_fingerprint[fingerprint] = name
|
||||
|
||||
self._resume_completed_steps = len(self._recorded_iterations)
|
||||
|
||||
@property
|
||||
def completed_steps(self) -> int:
|
||||
return len(self._recorded_iterations)
|
||||
|
||||
@staticmethod
|
||||
def _fingerprint(function_name: str, arguments: Dict[str, Any]) -> str:
|
||||
return f"{function_name}:{json.dumps(_json_safe(arguments), sort_keys=True)}"
|
||||
|
||||
def _is_inflight_call(
|
||||
self,
|
||||
function_name: str,
|
||||
arguments: Dict[str, Any],
|
||||
tool_call_id: Optional[str],
|
||||
) -> bool:
|
||||
"""Whether this call was in-flight (journalled, no result) at the crash.
|
||||
|
||||
Only meaningful while replaying: such calls have a recorded ``tool_call``
|
||||
but no ``tool_result``, so re-driving the loop would re-execute their
|
||||
side effect. Completed calls (already have a result) are replayed
|
||||
upstream and never reach this check.
|
||||
"""
|
||||
if not self.replaying:
|
||||
return False
|
||||
call_id = str(tool_call_id) if tool_call_id is not None else None
|
||||
if call_id and call_id in self._inflight_names_by_call_id:
|
||||
return True
|
||||
return self._fingerprint(function_name, arguments) in (
|
||||
self._inflight_names_by_fingerprint
|
||||
)
|
||||
|
||||
@staticmethod
|
||||
def _not_safely_resumable_result(function_name: str) -> Dict[str, Any]:
|
||||
"""Typed, operator-visible outcome for a gated in-flight effectful tool."""
|
||||
return {
|
||||
"error": (
|
||||
f"Tool '{function_name}' was in-flight when the durable run "
|
||||
"crashed and is not declared restart_safe; its outcome could not "
|
||||
"be confirmed. It was not re-executed on resume to avoid a "
|
||||
"duplicate side effect. Reconcile the external action manually "
|
||||
"or mark the tool @tool(restart_safe=True) if it is idempotent."
|
||||
),
|
||||
"error_type": "NotSafelyResumable",
|
||||
"not_safely_resumable": True,
|
||||
"restart_safe": False,
|
||||
}
|
||||
|
||||
def restore_messages(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
|
||||
"""Append completed decision/result pairs once, before the next model call."""
|
||||
if not self.replaying or self._restored:
|
||||
return messages
|
||||
|
||||
existing_ids = set()
|
||||
for message in messages:
|
||||
for tool_call in message.get("tool_calls") or []:
|
||||
if isinstance(tool_call, dict) and tool_call.get("id"):
|
||||
existing_ids.add(str(tool_call["id"]))
|
||||
|
||||
for seq in sorted({key[0] for key in self._replay}):
|
||||
decision = self._replay.get((seq, KIND_MODEL_DECISION))
|
||||
result = self._replay.get((seq, KIND_TOOL_RESULT))
|
||||
if not decision or result is None:
|
||||
continue
|
||||
message = decision.get("message")
|
||||
tool_call_id = result.get("tool_call_id")
|
||||
if not isinstance(message, dict) or not tool_call_id:
|
||||
continue
|
||||
if str(tool_call_id) in existing_ids:
|
||||
continue
|
||||
messages.append(_json_safe(message))
|
||||
messages.append(
|
||||
{
|
||||
"role": "tool",
|
||||
"tool_call_id": str(tool_call_id),
|
||||
"content": _tool_result_content(result.get("result")),
|
||||
}
|
||||
)
|
||||
existing_ids.add(str(tool_call_id))
|
||||
|
||||
self._restored = True
|
||||
return messages
|
||||
|
||||
def _allocate_step(
|
||||
self,
|
||||
function_name: str,
|
||||
arguments: Dict[str, Any],
|
||||
tool_call_id: Optional[str],
|
||||
) -> Tuple[int, str, str]:
|
||||
with self._lock:
|
||||
requested_call_id = str(tool_call_id) if tool_call_id is not None else None
|
||||
pending = (
|
||||
self._pending_by_call_id.pop(requested_call_id, None)
|
||||
if requested_call_id
|
||||
else None
|
||||
)
|
||||
fingerprint = self._fingerprint(function_name, arguments)
|
||||
if pending is None and self.replaying:
|
||||
pending = self._pending_by_fingerprint.pop(fingerprint, None)
|
||||
if pending is not None:
|
||||
seq, call_id, _args, idempotency_key = pending
|
||||
self._pending_by_call_id.pop(call_id, None)
|
||||
self._pending_by_fingerprint.pop(fingerprint, None)
|
||||
return seq, call_id, idempotency_key
|
||||
|
||||
seq = self._next_seq
|
||||
self._next_seq += 1
|
||||
call_id = str(tool_call_id or f"{self.run_id}-tool-{seq}")
|
||||
idempotency_key = f"{self.run_id}:{seq}:{function_name}"
|
||||
safe_arguments = _json_safe(arguments)
|
||||
message = {
|
||||
"role": "assistant",
|
||||
"content": "",
|
||||
"tool_calls": [
|
||||
{
|
||||
"id": call_id,
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": function_name,
|
||||
"arguments": json.dumps(safe_arguments),
|
||||
},
|
||||
}
|
||||
],
|
||||
}
|
||||
self.journal.append(
|
||||
JournalEvent(
|
||||
self.run_id,
|
||||
seq,
|
||||
KIND_MODEL_DECISION,
|
||||
{"message": message},
|
||||
)
|
||||
)
|
||||
self.journal.append(
|
||||
JournalEvent(
|
||||
self.run_id,
|
||||
seq,
|
||||
KIND_TOOL_CALL,
|
||||
{
|
||||
"name": function_name,
|
||||
"args": safe_arguments,
|
||||
"tool_call_id": call_id,
|
||||
"idempotency_key": idempotency_key,
|
||||
},
|
||||
)
|
||||
)
|
||||
return seq, call_id, idempotency_key
|
||||
|
||||
def _record_result(
|
||||
self,
|
||||
seq: int,
|
||||
tool_call_id: str,
|
||||
result: Any,
|
||||
iteration_index: Optional[int],
|
||||
) -> Any:
|
||||
safe_result = _json_safe(result)
|
||||
with self._lock:
|
||||
self.journal.append(
|
||||
JournalEvent(
|
||||
self.run_id,
|
||||
seq,
|
||||
KIND_TOOL_RESULT,
|
||||
{"tool_call_id": tool_call_id, "result": safe_result},
|
||||
)
|
||||
)
|
||||
if iteration_index is None:
|
||||
global_iteration = max(self._recorded_iterations, default=-1) + 1
|
||||
else:
|
||||
global_iteration = self._resume_completed_steps + int(iteration_index)
|
||||
if global_iteration not in self._recorded_iterations:
|
||||
self.journal.append(
|
||||
JournalEvent(
|
||||
self.run_id,
|
||||
global_iteration,
|
||||
KIND_ITERATION,
|
||||
{"index": global_iteration},
|
||||
)
|
||||
)
|
||||
self._recorded_iterations.add(global_iteration)
|
||||
self._results_by_tool_call_id[tool_call_id] = safe_result
|
||||
self._replay[(seq, KIND_TOOL_RESULT)] = {
|
||||
"tool_call_id": tool_call_id,
|
||||
"result": safe_result,
|
||||
}
|
||||
return safe_result
|
||||
|
||||
def _record_terminal_failure(
|
||||
self,
|
||||
seq: int,
|
||||
tool_call_id: str,
|
||||
error: ToolExecutionError,
|
||||
iteration_index: Optional[int],
|
||||
) -> None:
|
||||
"""Persist a fatal tool outcome and make the run non-resumable."""
|
||||
self._record_result(
|
||||
seq,
|
||||
tool_call_id,
|
||||
{
|
||||
"error": str(error),
|
||||
"error_type": type(error).__name__,
|
||||
"is_retryable": bool(error.is_retryable),
|
||||
"terminal": True,
|
||||
},
|
||||
iteration_index,
|
||||
)
|
||||
self.finalize("failed")
|
||||
|
||||
def record_verification(self, payloads: List[Dict[str, Any]]) -> None:
|
||||
"""Append verification-gate results as durable ``verification`` events.
|
||||
|
||||
Each payload gets its own fresh ``seq`` so the events append cleanly
|
||||
alongside the tool-call cursor without colliding on ``(run_id, seq,
|
||||
kind)``. Best-effort: journalling never raises into the gate.
|
||||
"""
|
||||
if self._closed:
|
||||
return
|
||||
with self._lock:
|
||||
for payload in payloads:
|
||||
seq = self._next_seq
|
||||
self._next_seq += 1
|
||||
try:
|
||||
self.journal.append(
|
||||
JournalEvent(self.run_id, seq, KIND_VERIFICATION, payload)
|
||||
)
|
||||
except Exception: # pragma: no cover - journalling is best-effort
|
||||
pass
|
||||
|
||||
def wrap_sync(self, execute_tool_fn: Optional[Callable]) -> Optional[Callable]:
|
||||
if execute_tool_fn is None:
|
||||
return None
|
||||
|
||||
def execute(function_name, arguments, tool_call_id=None, **kwargs):
|
||||
iteration_index = kwargs.pop("_durable_iteration_index", None)
|
||||
call_id = str(tool_call_id) if tool_call_id is not None else None
|
||||
if call_id and call_id in self._results_by_tool_call_id:
|
||||
return self._results_by_tool_call_id[call_id]
|
||||
gate_inflight = self._is_inflight_call(
|
||||
function_name, arguments, tool_call_id
|
||||
) and not _is_restart_safe(function_name, execute_tool_fn)
|
||||
seq, call_id, idempotency_key = self._allocate_step(
|
||||
function_name, arguments, tool_call_id
|
||||
)
|
||||
if gate_inflight:
|
||||
return self._record_result(
|
||||
seq,
|
||||
call_id,
|
||||
self._not_safely_resumable_result(function_name),
|
||||
iteration_index,
|
||||
)
|
||||
token = _active_idempotency_key.set(idempotency_key)
|
||||
try:
|
||||
call_kwargs = dict(kwargs)
|
||||
call_kwargs["tool_call_id"] = tool_call_id
|
||||
if _accepts_idempotency_key(execute_tool_fn):
|
||||
call_kwargs["idempotency_key"] = idempotency_key
|
||||
result = execute_tool_fn(function_name, arguments, **call_kwargs)
|
||||
except ToolExecutionError as exc:
|
||||
if not exc.is_retryable:
|
||||
self._record_terminal_failure(
|
||||
seq, call_id, exc, iteration_index
|
||||
)
|
||||
raise
|
||||
except Exception as exc:
|
||||
result = {"error": str(exc)}
|
||||
finally:
|
||||
_active_idempotency_key.reset(token)
|
||||
return self._record_result(seq, call_id, result, iteration_index)
|
||||
|
||||
return execute
|
||||
|
||||
def wrap_async(self, execute_tool_fn: Optional[Callable]) -> Optional[Callable]:
|
||||
if execute_tool_fn is None:
|
||||
return None
|
||||
|
||||
async def execute(function_name, arguments, tool_call_id=None, **kwargs):
|
||||
iteration_index = kwargs.pop("_durable_iteration_index", None)
|
||||
call_id = str(tool_call_id) if tool_call_id is not None else None
|
||||
if call_id and call_id in self._results_by_tool_call_id:
|
||||
return self._results_by_tool_call_id[call_id]
|
||||
gate_inflight = self._is_inflight_call(
|
||||
function_name, arguments, tool_call_id
|
||||
) and not _is_restart_safe(function_name, execute_tool_fn)
|
||||
seq, call_id, idempotency_key = await asyncio.to_thread(
|
||||
self._allocate_step, function_name, arguments, tool_call_id
|
||||
)
|
||||
if gate_inflight:
|
||||
return await asyncio.to_thread(
|
||||
self._record_result,
|
||||
seq,
|
||||
call_id,
|
||||
self._not_safely_resumable_result(function_name),
|
||||
iteration_index,
|
||||
)
|
||||
token = _active_idempotency_key.set(idempotency_key)
|
||||
try:
|
||||
call_kwargs = dict(kwargs)
|
||||
call_kwargs["tool_call_id"] = tool_call_id
|
||||
if _accepts_idempotency_key(execute_tool_fn):
|
||||
call_kwargs["idempotency_key"] = idempotency_key
|
||||
result = execute_tool_fn(function_name, arguments, **call_kwargs)
|
||||
if inspect.isawaitable(result):
|
||||
result = await result
|
||||
except ToolExecutionError as exc:
|
||||
if not exc.is_retryable:
|
||||
await asyncio.to_thread(
|
||||
self._record_terminal_failure,
|
||||
seq,
|
||||
call_id,
|
||||
exc,
|
||||
iteration_index,
|
||||
)
|
||||
raise
|
||||
except Exception as exc:
|
||||
result = {"error": str(exc)}
|
||||
finally:
|
||||
_active_idempotency_key.reset(token)
|
||||
return await asyncio.to_thread(
|
||||
self._record_result, seq, call_id, result, iteration_index
|
||||
)
|
||||
|
||||
return execute
|
||||
|
||||
def finalize(self, outcome: str = "succeeded") -> None:
|
||||
if not self._closed:
|
||||
self.journal.close_run(self.run_id, outcome)
|
||||
self._closed = True
|
||||
|
||||
def close(self) -> None:
|
||||
self.journal.close()
|
||||
|
||||
async def arestore_messages(
|
||||
self, messages: List[Dict[str, Any]]
|
||||
) -> List[Dict[str, Any]]:
|
||||
return await asyncio.to_thread(self.restore_messages, messages)
|
||||
|
||||
async def afinalize(self, outcome: str = "succeeded") -> None:
|
||||
await asyncio.to_thread(self.finalize, outcome)
|
||||
|
||||
async def aclose(self) -> None:
|
||||
await asyncio.to_thread(self.close)
|
||||
|
||||
|
||||
def begin_durable_run(agent: Any, prompt: str):
|
||||
"""Create and activate a context, or return ``(None, None)`` when disabled."""
|
||||
execution = getattr(agent, "execution", None)
|
||||
if execution is None or not getattr(execution, "durable", False):
|
||||
return None, None
|
||||
if _active_durable_run.get() is not None:
|
||||
return None, None
|
||||
|
||||
context = _open_durable_run(agent, prompt)
|
||||
token = _active_durable_run.set(context)
|
||||
return context, token
|
||||
|
||||
|
||||
def _open_durable_run(agent: Any, prompt: str) -> DurableRunContext:
|
||||
"""Open journal state without mutating the caller's ContextVar."""
|
||||
execution = agent.execution
|
||||
|
||||
journal = RunJournal(getattr(execution, "journal_path", None))
|
||||
resume_run_id = getattr(execution, "resume_run_id", None)
|
||||
replaying = bool(resume_run_id)
|
||||
run_id = str(resume_run_id or uuid4())
|
||||
|
||||
if replaying:
|
||||
metadata = journal.run_meta(run_id)
|
||||
if metadata is None:
|
||||
journal.close()
|
||||
raise ValueError(f"Cannot resume unknown durable run {run_id!r}")
|
||||
if metadata.status != "running":
|
||||
journal.close()
|
||||
raise ValueError(
|
||||
f"Cannot resume terminal durable run {run_id!r} "
|
||||
f"(status={metadata.status!r})"
|
||||
)
|
||||
if metadata.task and metadata.task != prompt:
|
||||
journal.close()
|
||||
raise ValueError(
|
||||
"Resume prompt does not match the prompt recorded for durable "
|
||||
f"run {run_id!r}"
|
||||
)
|
||||
|
||||
journal.open_run(
|
||||
run_id,
|
||||
agent=getattr(agent, "name", ""),
|
||||
task=prompt,
|
||||
metadata={"version": 1, "explicit_resume": replaying},
|
||||
)
|
||||
context = DurableRunContext(journal, run_id, replaying=replaying)
|
||||
agent._last_durable_run_id = run_id
|
||||
return context
|
||||
|
||||
|
||||
async def abegin_durable_run(agent: Any, prompt: str):
|
||||
"""Async durable-run creation with all SQLite I/O off the event loop."""
|
||||
execution = getattr(agent, "execution", None)
|
||||
if execution is None or not getattr(execution, "durable", False):
|
||||
return None, None
|
||||
if _active_durable_run.get() is not None:
|
||||
return None, None
|
||||
context = await asyncio.to_thread(_open_durable_run, agent, prompt)
|
||||
token = _active_durable_run.set(context)
|
||||
return context, token
|
||||
|
||||
|
||||
def end_durable_run(token) -> None:
|
||||
if token is not None:
|
||||
_active_durable_run.reset(token)
|
||||
|
||||
|
||||
def get_durable_run() -> Optional[DurableRunContext]:
|
||||
return _active_durable_run.get()
|
||||
|
||||
|
||||
def get_durable_idempotency_key() -> Optional[str]:
|
||||
"""Return the stable key for the currently executing durable tool call."""
|
||||
return _active_idempotency_key.get()
|
||||
@@ -110,8 +110,8 @@ class EmbeddingAgent:
|
||||
- EmbeddingConfig: Full configuration object
|
||||
verbose: Verbosity level for output
|
||||
"""
|
||||
from ..utils.model_alias import resolve_model_name
|
||||
llm = resolve_model_name(llm, model, "EmbeddingAgent")
|
||||
if llm is None and model is not None:
|
||||
llm = model
|
||||
|
||||
self.name = name or "EmbeddingAgent"
|
||||
self.instructions = instructions
|
||||
|
||||
@@ -1,276 +0,0 @@
|
||||
"""Describe, in plain English, where an agent's work actually happens.
|
||||
|
||||
PraisonAI can run the thinking (LLM calls) and the tools in different places:
|
||||
this machine, a container, or a provider's cloud. Which one you get depends on
|
||||
``run_on=``, ``backend=`` and ``sandbox=``, and until now none of that was
|
||||
visible from the object -- ``repr(agent)`` was the bare default.
|
||||
|
||||
This module is the single source of that answer, shared by ``Agent``,
|
||||
``AgentTeam`` and ``AgentFlow`` so all three describe themselves identically.
|
||||
|
||||
Vocabulary note: the fields are ``thinks_on`` / ``tools_run_on``, never
|
||||
``loop``. "Loop" is already a public workflow primitive here
|
||||
(``praisonaiagents.workflows.loop()``), asyncio's event loop, and agent-loop
|
||||
jargon a beginner would not know -- three meanings for one word is exactly the
|
||||
problem this module exists to fix.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any, Dict, Optional
|
||||
|
||||
# Provider name -> how a human would say it out loud.
|
||||
_PLACE_WORDS = {
|
||||
"local": "this machine",
|
||||
"subprocess": "a separate process on this machine",
|
||||
"sandlock": "a locked-down process on this machine",
|
||||
"docker": "a Docker container",
|
||||
"e2b": "an E2B cloud sandbox",
|
||||
"modal": "a Modal cloud sandbox",
|
||||
"daytona": "a Daytona cloud sandbox",
|
||||
"flyio": "a Fly.io machine",
|
||||
"tenki": "a Tenki cloud sandbox",
|
||||
"novita": "a Novita cloud sandbox",
|
||||
"ssh": "a remote machine over SSH",
|
||||
"anthropic": "Anthropic's cloud",
|
||||
}
|
||||
|
||||
HERE = "this machine"
|
||||
|
||||
# Public sandbox aliases the SandboxManager collapses before it picks a backend
|
||||
# (see praisonaiagents/sandbox/manager.py). We must describe the backend that
|
||||
# actually runs, not the alias the user typed, or "native"/"local" would report
|
||||
# a place that never executes.
|
||||
_ALIASES = {"native": "sandlock", "local": "subprocess"}
|
||||
|
||||
# ...but only for the SANDBOX registry. "local" resolves to two different
|
||||
# backends depending on which parameter carried it:
|
||||
# run_in="local" -> SandboxManager collapses it to subprocess:
|
||||
# scrubbed environment, blocked commands and paths
|
||||
# tools_run_on="local" -> the wrapper's LocalCompute: a plain shell in the
|
||||
# current directory, full environment inherited,
|
||||
# no security policy at all
|
||||
# Describing the second in the first's words overstates it, which is the exact
|
||||
# failure this module exists to prevent. One word, two backends -- so the
|
||||
# phrase has to depend on where the word came from.
|
||||
_COMPUTE_ONLY_WORDS = {"local": "a plain shell on this machine (no policy applied)"}
|
||||
|
||||
# Tiers that separate a process but do NOT contain it. Verified: under the
|
||||
# subprocess backend, outbound network still works and ~/.ssh is readable even
|
||||
# though SecurityPolicy declares them blocked.
|
||||
# `native` is deliberately absent: it aliases sandlock, which applies Landlock,
|
||||
# seccomp, a scrubbed environment and deny-all networking. Listing it here made
|
||||
# tools_run_on="native" and tools_run_on="sandlock" -- the same backend --
|
||||
# disagree about whether they contain anything.
|
||||
_NOT_A_BOUNDARY = {"subprocess", "local"}
|
||||
|
||||
|
||||
def say_place(name: Any, *, via: str = "sandbox") -> str:
|
||||
"""Turn a place name into a phrase a non-developer can read.
|
||||
|
||||
``via`` says which registry resolved the name -- ``"compute"`` for
|
||||
``tools_run_on=``, ``"sandbox"`` for ``run_in=``. It only matters for names
|
||||
that mean different backends in each (see ``_COMPUTE_ONLY_WORDS``).
|
||||
"""
|
||||
if name is None:
|
||||
return HERE
|
||||
if name is True:
|
||||
return _PLACE_WORDS["subprocess"]
|
||||
if not isinstance(name, str):
|
||||
# A configured provider instance: use its own declared name if it has
|
||||
# one. Normalise BEFORE the compute-only check, or a backend holding a
|
||||
# LocalCompute object (provider_name="local") skips the branch and gets
|
||||
# described in the subprocess backend's stronger words -- the exact
|
||||
# overstatement this module exists to prevent.
|
||||
name = getattr(name, "provider_name", None) or type(name).__name__
|
||||
if via == "compute" and name.lower() in _COMPUTE_ONLY_WORDS:
|
||||
return _COMPUTE_ONLY_WORDS[name.lower()]
|
||||
key = str(name).lower()
|
||||
key = _ALIASES.get(key, key)
|
||||
|
||||
known = _PLACE_WORDS.get(key)
|
||||
if known:
|
||||
return known
|
||||
|
||||
# A place contributed by another package can name itself; the bare name is
|
||||
# the last resort rather than the only option, because the phrase table is
|
||||
# a literal that cannot know about packages installed later.
|
||||
try:
|
||||
from ..managed._compute_bridge import contributed_display_name
|
||||
|
||||
declared = contributed_display_name(key)
|
||||
if declared:
|
||||
return declared
|
||||
except Exception:
|
||||
pass
|
||||
return str(name)
|
||||
|
||||
|
||||
def _backend_places(backend: Any) -> Optional[Dict[str, str]]:
|
||||
"""Where does a managed ``backend=`` put the thinking and the tools?"""
|
||||
if backend is None:
|
||||
return None
|
||||
|
||||
# Ask the backend what it is, rather than guessing from its class name.
|
||||
# Name-matching missed any backend that did not happen to contain "Hosted"
|
||||
# or "Anthropic" -- a self-hosted docker backend reported that it was
|
||||
# thinking on this machine while the whole loop ran in a container.
|
||||
declared = getattr(backend, "provider_name", None)
|
||||
if isinstance(declared, str):
|
||||
try:
|
||||
from .placement import managed_runtimes
|
||||
|
||||
if declared.lower() in managed_runtimes():
|
||||
where = say_place(declared)
|
||||
return {"thinks_on": where, "tools_run_on": where}
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
cls = type(backend).__name__
|
||||
# Hosted runtimes move the entire turn off this machine.
|
||||
if "Hosted" in cls or "Anthropic" in cls:
|
||||
provider = getattr(backend, "provider", None) or "anthropic"
|
||||
where = say_place(provider)
|
||||
return {"thinks_on": where, "tools_run_on": where}
|
||||
|
||||
# Local/sandboxed agents keep the loop here and may push tools out. A
|
||||
# backend's compute object is a COMPUTE-registry provider, so it is read
|
||||
# with the compute vocabulary: a LocalCompute here is the unrestricted
|
||||
# shell, not the subprocess backend "local" collapses to under run_in=.
|
||||
compute = getattr(backend, "_compute", None) or getattr(backend, "compute", None)
|
||||
if compute is not None:
|
||||
return {"thinks_on": HERE, "tools_run_on": say_place(compute, via="compute")}
|
||||
return {"thinks_on": HERE, "tools_run_on": HERE}
|
||||
|
||||
|
||||
def describe(obj: Any, *, shared: bool = False) -> Dict[str, str]:
|
||||
"""Return ``{thinks_on, tools_run_on, code_runs_on?}`` for an object.
|
||||
|
||||
Never raises: a description of where things run must not be able to break
|
||||
the thing it describes.
|
||||
"""
|
||||
places: Dict[str, str] = {"thinks_on": HERE, "tools_run_on": HERE}
|
||||
try:
|
||||
from_backend = _backend_places(getattr(obj, "backend", None))
|
||||
if from_backend:
|
||||
places.update(from_backend)
|
||||
|
||||
where_tools = getattr(obj, "tools_run_on", None)
|
||||
if where_tools is not None:
|
||||
where = say_place(where_tools, via="compute")
|
||||
places["tools_run_on"] = f"{where} (shared)" if shared else where
|
||||
|
||||
# run_on= puts the WHOLE agent on a managed runtime, so it moves the
|
||||
# thinking as well. _backend_places() already reports that (run_on= is
|
||||
# turned into a backend at construction); this only covers an object
|
||||
# that carries the name without a built backend.
|
||||
whole = getattr(obj, "run_on", None)
|
||||
if whole is not None and not from_backend:
|
||||
everywhere = say_place(whole)
|
||||
places["thinks_on"] = everywhere
|
||||
places["tools_run_on"] = everywhere
|
||||
|
||||
sandbox_config = getattr(obj, "sandbox_config", None)
|
||||
if sandbox_config is not None:
|
||||
places["code_runs_on"] = say_place(
|
||||
getattr(sandbox_config, "sandbox_type", None)
|
||||
)
|
||||
except Exception: # pragma: no cover - description must never break callers
|
||||
pass
|
||||
return places
|
||||
|
||||
|
||||
def _tools_staying_here(obj: Any) -> list:
|
||||
"""Names of the object's own tools, which do NOT move to the sandbox.
|
||||
|
||||
Only four tool names are bridged (``execute_command``, ``read_file``,
|
||||
``write_file``, ``list_files``); everything else the user passed keeps
|
||||
running in this process, against this filesystem. The capability prompt
|
||||
tells the model the sandbox is where things happen, so anything staying
|
||||
behind has to be said out loud.
|
||||
|
||||
Reads the pre-attach tool list when a sandbox is already attached: by then
|
||||
``agent.tools`` has been rewritten and the originals live in the sandbox's
|
||||
restore record.
|
||||
"""
|
||||
try:
|
||||
from ..managed.shared_compute import BRIDGED_TOOL_NAMES
|
||||
except Exception:
|
||||
BRIDGED_TOOL_NAMES = ("execute_command", "read_file", "write_file", "list_files")
|
||||
|
||||
tools = None
|
||||
shared = getattr(obj, "_tools_sandbox", None)
|
||||
if shared is not None:
|
||||
for patched, original_tools, _ in getattr(shared, "_patched", []):
|
||||
if patched is obj:
|
||||
tools = original_tools
|
||||
break
|
||||
if tools is None:
|
||||
tools = getattr(obj, "tools", None) or []
|
||||
|
||||
names = []
|
||||
for tool in tools:
|
||||
name = getattr(tool, "__name__", None) or getattr(tool, "name", None)
|
||||
if isinstance(name, str) and name not in BRIDGED_TOOL_NAMES:
|
||||
names.append(name)
|
||||
return names
|
||||
|
||||
|
||||
def repr_fields(obj: Any, *, shared: bool = False) -> str:
|
||||
"""Render the places as ``key='value'`` pairs for a ``__repr__``."""
|
||||
return ", ".join(f"{k}={v!r}" for k, v in describe(obj, shared=shared).items())
|
||||
|
||||
|
||||
def explain(obj: Any, *, shared: bool = False) -> str:
|
||||
"""Plain-sentence answer to "where does this actually run?".
|
||||
|
||||
Deliberately uses only words a non-engineer already knows -- no "loop",
|
||||
"harness", "provision" or "runtime".
|
||||
"""
|
||||
places = describe(obj, shared=shared)
|
||||
lines = [
|
||||
f"Thinking (the AI model calls) happens on {places['thinks_on']}.",
|
||||
f"Tools run on {places['tools_run_on']}.",
|
||||
]
|
||||
|
||||
if shared and getattr(obj, "tools_run_on", None) is not None:
|
||||
lines.append(
|
||||
"Every step shares that same sandbox, so a file written by one step "
|
||||
"is visible to the next."
|
||||
)
|
||||
|
||||
staying = _tools_staying_here(obj)
|
||||
if staying and places["tools_run_on"] != places["thinks_on"]:
|
||||
listed = ", ".join(staying[:6]) + ("..." if len(staying) > 6 else "")
|
||||
lines.append(
|
||||
f"Your own tools ({listed}) still run on {HERE} -- only shell, file "
|
||||
f"and code tools move. They read and write this machine's files."
|
||||
)
|
||||
|
||||
if "code_runs_on" in places:
|
||||
lines.append(
|
||||
f"Code you run yourself with execute_code() runs on {places['code_runs_on']}."
|
||||
)
|
||||
|
||||
# Say plainly when the chosen tier is not a security boundary.
|
||||
raw = [
|
||||
getattr(obj, "tools_run_on", None),
|
||||
getattr(obj, "run_on", None),
|
||||
getattr(getattr(obj, "sandbox_config", None), "sandbox_type", None),
|
||||
]
|
||||
if any(isinstance(v, str) and v.lower() in _NOT_A_BOUNDARY for v in raw) or any(
|
||||
v is True for v in raw
|
||||
):
|
||||
lines.append(
|
||||
"Note: a separate process is not a security boundary -- it can still "
|
||||
"reach the network and read your files, and its blocked-command "
|
||||
"list can be worked around by ordinary shell syntax. Use docker or a cloud "
|
||||
"provider for untrusted code."
|
||||
)
|
||||
|
||||
if places["thinks_on"] == HERE and places["tools_run_on"] == HERE:
|
||||
lines.append(
|
||||
"Nothing is isolated: tools you pass run in this program, with your "
|
||||
"permissions."
|
||||
)
|
||||
return "\n".join(lines)
|
||||
File diff suppressed because it is too large.
Load diff
@@ -14,10 +14,9 @@ from typing import Optional, Any, Callable, Dict, List, Union, TYPE_CHECKING, Li
|
||||
from dataclasses import dataclass, field
|
||||
from enum import Enum
|
||||
import inspect
|
||||
from contextlib import contextmanager
|
||||
import logging
|
||||
from praisonaiagents._logging import get_logger
|
||||
import asyncio
|
||||
import contextvars
|
||||
import threading
|
||||
import time
|
||||
import json
|
||||
@@ -164,52 +163,33 @@ from ..errors import (
|
||||
HandoffValidationError
|
||||
)
|
||||
|
||||
# Per-task/per-thread storage for tracking handoff chains.
|
||||
#
|
||||
# ``contextvars.ContextVar`` isolates the chain per :class:`asyncio.Task`
|
||||
# (and per OS thread), unlike ``threading.local()`` which shares one list
|
||||
# across every coroutine running on the same event-loop thread. Concurrent
|
||||
# async handoffs (``asyncio.gather``, a server handling parallel requests, or
|
||||
# any ``max_concurrent`` workflow) would otherwise push/pop into the same list
|
||||
# and corrupt each other's cycle/depth state. Combined with the copy-on-write
|
||||
# push/pop below, this fully isolates sibling handoff tasks (e.g. those spawned
|
||||
# by ``parallel_handoffs`` via ``asyncio.gather``).
|
||||
_handoff_chain_var: "contextvars.ContextVar[Optional[List[str]]]" = contextvars.ContextVar(
|
||||
"handoff_chain", default=None
|
||||
)
|
||||
# Thread-local storage for tracking handoff chains
|
||||
_handoff_context = threading.local()
|
||||
|
||||
def _get_handoff_chain() -> List[str]:
|
||||
"""Get current handoff chain for this task/thread."""
|
||||
chain = _handoff_chain_var.get()
|
||||
if chain is None:
|
||||
chain = []
|
||||
_handoff_chain_var.set(chain)
|
||||
return chain
|
||||
"""Get current handoff chain from thread-local storage."""
|
||||
if not hasattr(_handoff_context, 'chain'):
|
||||
_handoff_context.chain = []
|
||||
return _handoff_context.chain
|
||||
|
||||
def _get_handoff_depth() -> int:
|
||||
"""Get current handoff depth."""
|
||||
return len(_get_handoff_chain())
|
||||
|
||||
def _push_handoff(agent_name: str) -> None:
|
||||
"""Push agent to handoff chain.
|
||||
|
||||
Uses copy-on-write so a push made inside a child task does not leak back
|
||||
into the parent task's chain once the child completes.
|
||||
"""
|
||||
chain = list(_get_handoff_chain())
|
||||
"""Push agent to handoff chain."""
|
||||
chain = _get_handoff_chain()
|
||||
chain.append(agent_name)
|
||||
_handoff_chain_var.set(chain)
|
||||
|
||||
def _pop_handoff() -> Optional[str]:
|
||||
"""Pop agent from handoff chain."""
|
||||
chain = list(_get_handoff_chain())
|
||||
popped = chain.pop() if chain else None
|
||||
_handoff_chain_var.set(chain)
|
||||
return popped
|
||||
chain = _get_handoff_chain()
|
||||
return chain.pop() if chain else None
|
||||
|
||||
def _clear_handoff_chain() -> None:
|
||||
"""Clear the handoff chain."""
|
||||
_handoff_chain_var.set([])
|
||||
if hasattr(_handoff_context, 'chain'):
|
||||
_handoff_context.chain = []
|
||||
|
||||
@dataclass
|
||||
class HandoffInputData:
|
||||
@@ -309,14 +289,12 @@ class Handoff:
|
||||
- Cycle detection and depth limiting
|
||||
- Configurable context policies
|
||||
"""
|
||||
|
||||
# Class-level lock guarding lazy creation of each instance's async
|
||||
# semaphore. The semaphore itself is per-instance (so every Handoff
|
||||
# enforces its own max_concurrent), but the brief init critical section is
|
||||
# only ever touched under this shared threading.Lock, which keeps
|
||||
# double-checked lazy creation thread-safe without a per-instance lock.
|
||||
_semaphore_lock: threading.Lock = threading.Lock()
|
||||
|
||||
|
||||
# Class-level semaphore for concurrency control
|
||||
_semaphore: Optional[asyncio.Semaphore] = None
|
||||
_sync_semaphore: Optional[threading.Semaphore] = None
|
||||
_semaphore_lock: threading.Lock = threading.Lock() # Lock for semaphore initialization
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
agent: 'Agent',
|
||||
@@ -347,40 +325,10 @@ class Handoff:
|
||||
self.input_type = input_type
|
||||
self.input_filter = input_filter
|
||||
self.config = config or HandoffConfig()
|
||||
|
||||
# Instance-level concurrency control. Each Handoff enforces its own
|
||||
# max_concurrent instead of sharing one process-wide semaphore, so
|
||||
# different handoffs don't silently override each other's limits based
|
||||
# on execution order. The async semaphore is created lazily (and
|
||||
# recreated if bound to a stale event loop) since it binds to the
|
||||
# running loop on first use.
|
||||
self._semaphore: Optional[asyncio.Semaphore] = None
|
||||
self._semaphore_loop: Optional[asyncio.AbstractEventLoop] = None
|
||||
|
||||
# Override config callback if on_handoff provided directly
|
||||
if on_handoff and not self.config.on_handoff:
|
||||
self.config.on_handoff = on_handoff
|
||||
|
||||
def _get_semaphore(self) -> Optional[asyncio.Semaphore]:
|
||||
"""Return this handoff's async semaphore, bound to the current loop.
|
||||
|
||||
Returns None when concurrency limiting is disabled (max_concurrent <= 0).
|
||||
The semaphore is created lazily and recreated if the running event loop
|
||||
differs from the one it was originally bound to, so a process that calls
|
||||
asyncio.run(...) more than once doesn't crash with a "bound to a
|
||||
different event loop" RuntimeError.
|
||||
"""
|
||||
if self.config.max_concurrent <= 0:
|
||||
return None
|
||||
try:
|
||||
current_loop = asyncio.get_event_loop()
|
||||
except RuntimeError:
|
||||
current_loop = None
|
||||
with self._semaphore_lock:
|
||||
if self._semaphore is None or self._semaphore_loop is not current_loop:
|
||||
self._semaphore = asyncio.Semaphore(self.config.max_concurrent)
|
||||
self._semaphore_loop = current_loop
|
||||
return self._semaphore
|
||||
|
||||
@property
|
||||
def tool_name(self) -> str:
|
||||
@@ -470,46 +418,12 @@ class Handoff:
|
||||
return value
|
||||
return 'gpt-4o-mini'
|
||||
|
||||
@contextmanager
|
||||
def _seed_target_history(self, prior_messages: Optional[List[Any]]):
|
||||
"""Temporarily seed the filtered handoff context onto the target agent.
|
||||
|
||||
The configured ``context_policy``/``input_filter`` produce the messages the
|
||||
target should see; without seeding them the target only ever received the
|
||||
literal handoff prompt string and the configured policy had no effect.
|
||||
|
||||
The seeding is *invocation-scoped*: the prior messages are prepended for the
|
||||
duration of this handoff and the target's original ``chat_history`` is
|
||||
restored on exit. This keeps handoff context from leaking into later
|
||||
handoffs or ordinary chats that reuse the same target agent, and stops the
|
||||
target prompt from growing across sequential handoffs.
|
||||
No shared mutable state is retained between agents.
|
||||
"""
|
||||
existing = getattr(self.agent, 'chat_history', None)
|
||||
if not prior_messages or not isinstance(existing, list):
|
||||
yield
|
||||
return
|
||||
try:
|
||||
prior = list(prior_messages)
|
||||
except TypeError:
|
||||
yield
|
||||
return
|
||||
original = existing
|
||||
try:
|
||||
# Avoid re-seeding if the context is already at the head.
|
||||
if existing[:len(prior)] != prior:
|
||||
self.agent.chat_history = prior + existing
|
||||
yield
|
||||
finally:
|
||||
self.agent.chat_history = original
|
||||
|
||||
def _execute_with_runtime_resolution(
|
||||
self,
|
||||
source_agent: 'Agent',
|
||||
prompt: str,
|
||||
effective_tools: Optional[List[Any]],
|
||||
context: Dict[str, Any],
|
||||
prior_messages: Optional[List[Any]] = None,
|
||||
context: Dict[str, Any]
|
||||
) -> str:
|
||||
"""Execute handoff through the target agent's full chat pipeline."""
|
||||
target_model_ref = self._extract_model_ref(self.agent)
|
||||
@@ -519,16 +433,14 @@ class Handoff:
|
||||
target_model_ref,
|
||||
_get_handoff_depth(),
|
||||
)
|
||||
with self._seed_target_history(prior_messages):
|
||||
return self.agent.chat(prompt, tools=effective_tools)
|
||||
return self.agent.chat(prompt, tools=effective_tools)
|
||||
|
||||
async def _execute_with_runtime_resolution_async(
|
||||
self,
|
||||
source_agent: 'Agent',
|
||||
prompt: str,
|
||||
effective_tools: Optional[List[Any]],
|
||||
context: Dict[str, Any],
|
||||
prior_messages: Optional[List[Any]] = None,
|
||||
context: Dict[str, Any]
|
||||
) -> str:
|
||||
"""Execute handoff through the target agent's full async chat pipeline."""
|
||||
target_model_ref = self._extract_model_ref(self.agent)
|
||||
@@ -538,14 +450,13 @@ class Handoff:
|
||||
target_model_ref,
|
||||
_get_handoff_depth(),
|
||||
)
|
||||
with self._seed_target_history(prior_messages):
|
||||
async_chat = getattr(self.agent, 'achat', None)
|
||||
if callable(async_chat) and inspect.iscoroutinefunction(async_chat):
|
||||
return await async_chat(prompt, tools=effective_tools)
|
||||
loop = asyncio.get_running_loop()
|
||||
return await loop.run_in_executor(
|
||||
None, lambda: self.agent.chat(prompt, tools=effective_tools)
|
||||
)
|
||||
async_chat = getattr(self.agent, 'achat', None)
|
||||
if callable(async_chat) and inspect.iscoroutinefunction(async_chat):
|
||||
return await async_chat(prompt, tools=effective_tools)
|
||||
loop = asyncio.get_running_loop()
|
||||
return await loop.run_in_executor(
|
||||
None, lambda: self.agent.chat(prompt, tools=effective_tools)
|
||||
)
|
||||
|
||||
def _check_safety(self, source_agent: 'Agent') -> None:
|
||||
"""
|
||||
@@ -686,22 +597,19 @@ class Handoff:
|
||||
"""
|
||||
start_time = time.time()
|
||||
kwargs = context or {}
|
||||
pushed = False
|
||||
|
||||
try:
|
||||
# Safety checks (may raise before anything is pushed for this call)
|
||||
# Safety checks
|
||||
self._check_safety(source_agent)
|
||||
|
||||
# Track handoff chain
|
||||
_push_handoff(source_agent.name)
|
||||
pushed = True
|
||||
|
||||
# Execute on_handoff callback
|
||||
self._execute_callback(self.config.on_handoff or self.on_handoff, source_agent, kwargs)
|
||||
|
||||
# Prepare context per the configured context_policy/input_filter and
|
||||
# thread the filtered history through to the target agent.
|
||||
handoff_data = self._prepare_context(source_agent, kwargs)
|
||||
# Prepare context (for future extensibility - context data available for hooks)
|
||||
_ = self._prepare_context(source_agent, kwargs)
|
||||
|
||||
# Build prompt with context
|
||||
context_prefix = f"[Handoff from {source_agent.name}] "
|
||||
@@ -716,8 +624,7 @@ class Handoff:
|
||||
|
||||
# Resolve runtime at turn-time instead of using construction-time pin
|
||||
response = self._execute_with_runtime_resolution(
|
||||
source_agent, full_prompt, effective_tools, kwargs,
|
||||
prior_messages=handoff_data.messages,
|
||||
source_agent, full_prompt, effective_tools, kwargs
|
||||
)
|
||||
|
||||
result = HandoffResult(
|
||||
@@ -772,8 +679,7 @@ class Handoff:
|
||||
logger.error(f"Handoff error: {e}")
|
||||
return result
|
||||
finally:
|
||||
if pushed:
|
||||
_pop_handoff()
|
||||
_pop_handoff()
|
||||
|
||||
async def execute_async(
|
||||
self,
|
||||
@@ -792,26 +698,26 @@ class Handoff:
|
||||
Returns:
|
||||
HandoffResult with response or error
|
||||
"""
|
||||
# Per-instance semaphore, bound to the current event loop
|
||||
semaphore = self._get_semaphore()
|
||||
# Initialize semaphore if needed (thread-safe)
|
||||
if self.config.max_concurrent > 0 and Handoff._semaphore is None:
|
||||
with Handoff._semaphore_lock: # Thread-safe initialization
|
||||
if Handoff._semaphore is None: # Double-check after acquiring lock
|
||||
Handoff._semaphore = asyncio.Semaphore(self.config.max_concurrent)
|
||||
|
||||
start_time = time.time()
|
||||
kwargs = context or {}
|
||||
|
||||
async def _execute():
|
||||
pushed = False
|
||||
try:
|
||||
# Safety checks (may raise before anything is pushed for this call)
|
||||
# Safety checks
|
||||
self._check_safety(source_agent)
|
||||
_push_handoff(source_agent.name)
|
||||
pushed = True
|
||||
|
||||
# Execute callback
|
||||
self._execute_callback(self.config.on_handoff or self.on_handoff, source_agent, kwargs)
|
||||
|
||||
# Prepare context per the configured context_policy/input_filter
|
||||
# and thread the filtered history through to the target agent.
|
||||
handoff_data = self._prepare_context(source_agent, kwargs)
|
||||
# Prepare context (for future extensibility)
|
||||
_ = self._prepare_context(source_agent, kwargs)
|
||||
|
||||
# Build prompt
|
||||
context_prefix = f"[Handoff from {source_agent.name}] "
|
||||
@@ -826,8 +732,7 @@ class Handoff:
|
||||
|
||||
# Resolve runtime at turn-time for async execution
|
||||
response = await self._execute_with_runtime_resolution_async(
|
||||
source_agent, full_prompt, effective_tools, kwargs,
|
||||
prior_messages=handoff_data.messages,
|
||||
source_agent, full_prompt, effective_tools, kwargs
|
||||
)
|
||||
|
||||
result = HandoffResult(
|
||||
@@ -855,12 +760,11 @@ class Handoff:
|
||||
|
||||
return result
|
||||
finally:
|
||||
if pushed:
|
||||
_pop_handoff()
|
||||
_pop_handoff()
|
||||
|
||||
try:
|
||||
if semaphore is not None:
|
||||
async with semaphore:
|
||||
if self.config.max_concurrent > 0 and Handoff._semaphore:
|
||||
async with Handoff._semaphore:
|
||||
if self.config.timeout_seconds > 0:
|
||||
result = await asyncio.wait_for(
|
||||
_execute(),
|
||||
@@ -924,15 +828,13 @@ class Handoff:
|
||||
def handoff_tool(**kwargs):
|
||||
"""Execute the handoff to the target agent."""
|
||||
start_time = time.time()
|
||||
pushed = False
|
||||
|
||||
try:
|
||||
# Safety checks (may raise before anything is pushed for this call)
|
||||
# Safety checks
|
||||
self._check_safety(source_agent)
|
||||
|
||||
# Track handoff chain
|
||||
_push_handoff(source_agent.name)
|
||||
pushed = True
|
||||
|
||||
# Execute on_handoff callback
|
||||
self._execute_callback(self.config.on_handoff or self.on_handoff, source_agent, kwargs)
|
||||
@@ -940,39 +842,20 @@ class Handoff:
|
||||
# Prepare handoff data with context policy
|
||||
handoff_data = self._prepare_context(source_agent, kwargs)
|
||||
|
||||
# Get the last user message or context to pass to target agent.
|
||||
# Track the index of the message chosen for ``prompt`` so exactly
|
||||
# that item is excluded from the seeded history (it may not be the
|
||||
# final list item if an assistant/tool message follows it).
|
||||
# Get the last user message or context to pass to target agent
|
||||
last_message = None
|
||||
selected_index = None
|
||||
for i in range(len(handoff_data.messages) - 1, -1, -1):
|
||||
msg = handoff_data.messages[i]
|
||||
for msg in reversed(handoff_data.messages):
|
||||
if isinstance(msg, dict) and msg.get('role') == 'user':
|
||||
last_message = msg.get('content', '')
|
||||
selected_index = i
|
||||
break
|
||||
|
||||
if not last_message and handoff_data.messages:
|
||||
selected_index = len(handoff_data.messages) - 1
|
||||
last_msg = handoff_data.messages[selected_index]
|
||||
last_msg = handoff_data.messages[-1]
|
||||
if isinstance(last_msg, dict):
|
||||
last_message = last_msg.get('content', '')
|
||||
else:
|
||||
last_message = str(last_msg)
|
||||
|
||||
# Tool-style handoff (as_tool): ContextPolicy.NONE discards the
|
||||
# history, so the prompt must come from the generated ``task``/
|
||||
# ``prompt`` argument instead. Without this the sub-agent would
|
||||
# never run and the tool would report a hollow "completed". The
|
||||
# task is the sub-agent's whole instruction, so it is passed
|
||||
# verbatim rather than wrapped in a ``[Handoff from …]`` prefix.
|
||||
task_prompt = None
|
||||
if not last_message and not self.input_type:
|
||||
task_prompt = kwargs.get('task') or kwargs.get('prompt')
|
||||
if task_prompt:
|
||||
last_message = str(task_prompt)
|
||||
|
||||
|
||||
# Prepare context information
|
||||
context_info = f"[Handoff from {source_agent.name}] "
|
||||
if kwargs and self.input_type:
|
||||
@@ -980,26 +863,15 @@ class Handoff:
|
||||
|
||||
# Execute the target agent with tool boundary enforcement
|
||||
if last_message:
|
||||
prompt = last_message if task_prompt else context_info + last_message
|
||||
prompt = context_info + last_message
|
||||
logger.info(f"Handing off to {self.agent.name} with prompt: {prompt}")
|
||||
|
||||
# Compute effective tools based on tool policy
|
||||
effective_tools = self._compute_effective_tools(source_agent)
|
||||
|
||||
# Resolve runtime at turn-time for tool function execution.
|
||||
# The selected message is already folded into ``prompt`` above,
|
||||
# so exclude exactly that item from the seeded history to avoid
|
||||
# duplicating it while preserving any messages that follow it.
|
||||
if selected_index is None:
|
||||
prior_messages = list(handoff_data.messages)
|
||||
else:
|
||||
prior_messages = (
|
||||
handoff_data.messages[:selected_index]
|
||||
+ handoff_data.messages[selected_index + 1:]
|
||||
)
|
||||
# Resolve runtime at turn-time for tool function execution
|
||||
response = self._execute_with_runtime_resolution(
|
||||
source_agent, prompt, effective_tools, kwargs,
|
||||
prior_messages=prior_messages,
|
||||
source_agent, prompt, effective_tools, kwargs
|
||||
)
|
||||
|
||||
result = HandoffResult(
|
||||
@@ -1048,8 +920,7 @@ class Handoff:
|
||||
self._execute_callback(self.config.on_error, source_agent, kwargs, result)
|
||||
return f"Error during handoff to {self.agent.name}: {str(e)}"
|
||||
finally:
|
||||
if pushed:
|
||||
_pop_handoff()
|
||||
_pop_handoff()
|
||||
|
||||
# Set function metadata for tool definition generation
|
||||
handoff_tool.__name__ = self.tool_name
|
||||
@@ -1067,17 +938,6 @@ class Handoff:
|
||||
)
|
||||
)
|
||||
handoff_tool.__signature__ = inspect.Signature(sig_params)
|
||||
elif self.config.context_policy == ContextPolicy.NONE:
|
||||
# Tool-style handoff (as_tool): no conversation context is passed, so
|
||||
# advertise an explicit ``task`` parameter the caller must fill. This
|
||||
# is what ``handoff_tool`` reads as the sub-agent's prompt above.
|
||||
handoff_tool.__signature__ = inspect.Signature([
|
||||
inspect.Parameter(
|
||||
'task',
|
||||
inspect.Parameter.KEYWORD_ONLY,
|
||||
annotation=str,
|
||||
)
|
||||
])
|
||||
|
||||
return handoff_tool
|
||||
|
||||
@@ -1311,13 +1171,6 @@ async def parallel_handoffs(
|
||||
semaphore = asyncio.Semaphore(effective_max_concurrent) if effective_max_concurrent > 0 else None
|
||||
|
||||
async def _run_one(agent, prompt):
|
||||
# Each gathered task shares a copied context, but a copied ContextVar
|
||||
# binding still points at the *same* parent list object. Rebind to a
|
||||
# fresh, per-task copy so sibling handoffs cannot corrupt each other's
|
||||
# cycle/depth tracking when parallel_handoffs runs inside a non-empty
|
||||
# parent handoff chain.
|
||||
_handoff_chain_var.set(list(_handoff_chain_var.get() or []))
|
||||
|
||||
async def _do_handoff():
|
||||
try:
|
||||
return await source.handoff_to_async(agent, prompt, config=config)
|
||||
@@ -1538,22 +1391,19 @@ class TypedHandoff(Handoff, Generic[T]):
|
||||
|
||||
start_time = time.time()
|
||||
kwargs = context or {}
|
||||
pushed = False
|
||||
|
||||
try:
|
||||
# Safety checks (may raise before anything is pushed for this call)
|
||||
# Safety checks
|
||||
self._check_safety(source_agent)
|
||||
|
||||
# Track handoff chain
|
||||
_push_handoff(source_agent.name)
|
||||
pushed = True
|
||||
|
||||
# Execute on_handoff callback
|
||||
self._execute_callback(self.config.on_handoff or self.on_handoff, source_agent, kwargs)
|
||||
|
||||
# Apply context policy / input filter; the resulting messages are
|
||||
# seeded onto the target only for the duration of its chat below.
|
||||
handoff_data = self._prepare_context(source_agent, kwargs)
|
||||
# Apply input filter if provided (fixes Greptile P1 issue)
|
||||
_ = self._prepare_context(source_agent, kwargs)
|
||||
|
||||
# Validate payload against schema
|
||||
try:
|
||||
@@ -1580,8 +1430,7 @@ class TypedHandoff(Handoff, Generic[T]):
|
||||
logger.info(f"Typed handoff to {self.agent.name} with validated payload")
|
||||
|
||||
# Execute with timeout if sync
|
||||
with self._seed_target_history(handoff_data.messages):
|
||||
response = self.agent.chat(full_prompt)
|
||||
response = self.agent.chat(full_prompt)
|
||||
|
||||
result = HandoffResult(
|
||||
success=True,
|
||||
@@ -1621,8 +1470,7 @@ class TypedHandoff(Handoff, Generic[T]):
|
||||
logger.error(f"Typed handoff error: {e}")
|
||||
return result
|
||||
finally:
|
||||
if pushed:
|
||||
_pop_handoff()
|
||||
_pop_handoff()
|
||||
|
||||
async def execute_async(
|
||||
self,
|
||||
@@ -1649,26 +1497,26 @@ class TypedHandoff(Handoff, Generic[T]):
|
||||
if isinstance(payload, str):
|
||||
return await super().execute_async(source_agent, payload, context)
|
||||
|
||||
# Per-instance semaphore, bound to the current event loop
|
||||
semaphore = self._get_semaphore()
|
||||
# Initialize semaphore if needed (thread-safe)
|
||||
if self.config.max_concurrent > 0 and Handoff._semaphore is None:
|
||||
with Handoff._semaphore_lock:
|
||||
if Handoff._semaphore is None:
|
||||
Handoff._semaphore = asyncio.Semaphore(self.config.max_concurrent)
|
||||
|
||||
start_time = time.time()
|
||||
kwargs = context or {}
|
||||
|
||||
async def _execute():
|
||||
pushed = False
|
||||
try:
|
||||
# Safety checks (may raise before anything is pushed for this call)
|
||||
# Safety checks
|
||||
self._check_safety(source_agent)
|
||||
_push_handoff(source_agent.name)
|
||||
pushed = True
|
||||
|
||||
# Execute callback
|
||||
self._execute_callback(self.config.on_handoff or self.on_handoff, source_agent, kwargs)
|
||||
|
||||
# Apply context policy / input filter; the resulting messages are
|
||||
# seeded onto the target only for the duration of its chat below.
|
||||
handoff_data = self._prepare_context(source_agent, kwargs)
|
||||
# Apply input filter if provided (fixes Greptile P1 issue)
|
||||
_ = self._prepare_context(source_agent, kwargs)
|
||||
|
||||
# Validate payload against schema
|
||||
try:
|
||||
@@ -1694,13 +1542,12 @@ class TypedHandoff(Handoff, Generic[T]):
|
||||
logger.info(f"Async typed handoff to {self.agent.name}")
|
||||
|
||||
# Execute - check for async chat method
|
||||
with self._seed_target_history(handoff_data.messages):
|
||||
if hasattr(self.agent, 'achat'):
|
||||
response = await self.agent.achat(full_prompt)
|
||||
else:
|
||||
# Run sync chat in executor
|
||||
loop = asyncio.get_event_loop()
|
||||
response = await loop.run_in_executor(None, self.agent.chat, full_prompt)
|
||||
if hasattr(self.agent, 'achat'):
|
||||
response = await self.agent.achat(full_prompt)
|
||||
else:
|
||||
# Run sync chat in executor
|
||||
loop = asyncio.get_event_loop()
|
||||
response = await loop.run_in_executor(None, self.agent.chat, full_prompt)
|
||||
|
||||
return HandoffResult(
|
||||
success=True,
|
||||
@@ -1711,12 +1558,11 @@ class TypedHandoff(Handoff, Generic[T]):
|
||||
handoff_depth=_get_handoff_depth(),
|
||||
)
|
||||
finally:
|
||||
if pushed:
|
||||
_pop_handoff()
|
||||
_pop_handoff()
|
||||
|
||||
try:
|
||||
if semaphore is not None:
|
||||
async with semaphore:
|
||||
if self.config.max_concurrent > 0 and Handoff._semaphore:
|
||||
async with Handoff._semaphore:
|
||||
if self.config.timeout_seconds > 0:
|
||||
result = await asyncio.wait_for(
|
||||
_execute(),
|
||||
|
||||
@@ -13,6 +13,7 @@ Usage::
|
||||
"""
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
from praisonaiagents._logging import get_logger
|
||||
import threading
|
||||
import time
|
||||
|
||||
@@ -6,7 +6,7 @@ operations. Follows protocol-driven design with zero overhead when not used.
|
||||
"""
|
||||
|
||||
import threading
|
||||
from typing import Optional, Protocol, Set
|
||||
from typing import Optional, Protocol
|
||||
from dataclasses import dataclass, field
|
||||
|
||||
__all__ = ["InterruptControllerProtocol", "InterruptController"]
|
||||
@@ -57,10 +57,6 @@ class InterruptController:
|
||||
|
||||
_flag: threading.Event = field(default_factory=threading.Event, init=False, repr=False)
|
||||
_reason: Optional[str] = field(default=None, init=False)
|
||||
_active_turns: Set[int] = field(default_factory=set, init=False, repr=False)
|
||||
_cancelled_turns: Set[int] = field(default_factory=set, init=False, repr=False)
|
||||
_next_turn_id: int = field(default=0, init=False, repr=False)
|
||||
_pending_turn_cancel: bool = field(default=False, init=False, repr=False)
|
||||
_lock: threading.Lock = field(default_factory=threading.Lock, init=False, repr=False)
|
||||
|
||||
def request(self, reason: str = "user") -> None:
|
||||
@@ -73,40 +69,12 @@ class InterruptController:
|
||||
if not self._flag.is_set():
|
||||
self._reason = reason
|
||||
self._flag.set()
|
||||
if self._active_turns:
|
||||
self._cancelled_turns.update(self._active_turns)
|
||||
else:
|
||||
self._pending_turn_cancel = True
|
||||
|
||||
def _begin_turn(self) -> int:
|
||||
"""Register an Agent turn and consume any request made while idle."""
|
||||
with self._lock:
|
||||
self._next_turn_id += 1
|
||||
turn_id = self._next_turn_id
|
||||
self._active_turns.add(turn_id)
|
||||
if self._pending_turn_cancel:
|
||||
self._cancelled_turns.add(turn_id)
|
||||
self._pending_turn_cancel = False
|
||||
return turn_id
|
||||
|
||||
def _turn_is_cancelled(self, turn_id: int) -> bool:
|
||||
"""Return whether a registered turn was targeted by a request."""
|
||||
with self._lock:
|
||||
return turn_id in self._cancelled_turns
|
||||
|
||||
def _end_turn(self, turn_id: int) -> None:
|
||||
"""Unregister a turn so its request cannot affect a future turn."""
|
||||
with self._lock:
|
||||
self._active_turns.discard(turn_id)
|
||||
self._cancelled_turns.discard(turn_id)
|
||||
|
||||
def clear(self) -> None:
|
||||
"""Clear the cancellation request."""
|
||||
with self._lock:
|
||||
self._reason = None
|
||||
self._flag.clear()
|
||||
self._pending_turn_cancel = False
|
||||
self._cancelled_turns.clear()
|
||||
|
||||
def is_set(self) -> bool:
|
||||
"""Check if cancellation has been requested.
|
||||
|
||||
@@ -1,88 +0,0 @@
|
||||
"""Shared authorisation + bind guard for the ``launch()`` serving paths.
|
||||
|
||||
Both ``Agent.launch()`` (``agent/execution_mixin.py``) and
|
||||
``PraisonAIAgents.launch()`` (``agents/agents.py``) expose a prompt-execution
|
||||
HTTP endpoint. They must enforce identical request authorisation and must not
|
||||
silently bind all interfaces without a token. Factoring the two helpers here
|
||||
keeps that policy in one place so the two launch paths cannot drift apart.
|
||||
|
||||
Stdlib only — no heavy imports, no new public params.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import secrets as _secrets
|
||||
from typing import Optional
|
||||
|
||||
__all__ = [
|
||||
"launch_auth_token",
|
||||
"authorise_launch_request",
|
||||
"resolve_launch_host",
|
||||
]
|
||||
|
||||
# Hosts that are safe to serve keyless on: loopback only.
|
||||
_LOOPBACK_HOSTS = frozenset({"127.0.0.1", "::1", "localhost"})
|
||||
|
||||
# One auto-generated token per process, reused across launches so a later
|
||||
# non-loopback launch cannot mint a fresh token and lock out an endpoint that
|
||||
# is already serving with the previously generated one.
|
||||
_GENERATED_TOKEN: Optional[str] = None
|
||||
|
||||
|
||||
def launch_auth_token() -> Optional[str]:
|
||||
"""Return the configured launch bearer token, if any."""
|
||||
return os.environ.get("PRAISONAI_LAUNCH_AUTH_TOKEN")
|
||||
|
||||
|
||||
def authorise_launch_request(request) -> bool:
|
||||
"""Return True if the request carries the configured bearer token.
|
||||
|
||||
When no token is configured this returns True (local-dev flow preserved).
|
||||
Accepts either ``Authorization: Bearer <token>`` or ``X-Auth-Token``.
|
||||
"""
|
||||
token = launch_auth_token()
|
||||
if not token:
|
||||
return True
|
||||
auth = request.headers.get("Authorization", "")
|
||||
if auth.startswith("Bearer ") and _secrets.compare_digest(auth[7:], token):
|
||||
return True
|
||||
supplied = request.headers.get("X-Auth-Token", "")
|
||||
return bool(supplied) and _secrets.compare_digest(supplied, token)
|
||||
|
||||
|
||||
def _is_loopback(host: str) -> bool:
|
||||
return host in _LOOPBACK_HOSTS
|
||||
|
||||
|
||||
def resolve_launch_host(host: str) -> str:
|
||||
"""Fail-closed bind guard, mirroring the ``serve``/jobs precedent.
|
||||
|
||||
* Token set → bind ``host`` unchanged (auth protects the endpoint).
|
||||
* Token unset + loopback host → bind unchanged (local dev unchanged).
|
||||
* Token unset + non-loopback host → auto-generate a token, export it via
|
||||
``PRAISONAI_LAUNCH_AUTH_TOKEN`` so every route enforces it, and print it
|
||||
once. This closes the unauthenticated-exposure hole without refusing to
|
||||
start.
|
||||
|
||||
Returns the host to bind (unchanged; the guard acts on the token, not the
|
||||
host, so an explicit ``0.0.0.0`` is still honoured — just never keyless).
|
||||
|
||||
A generated token is reused for the lifetime of the process: repeated
|
||||
non-loopback launches share the one token rather than each minting a fresh
|
||||
one, so a later launch cannot invalidate an already-running endpoint's
|
||||
clients.
|
||||
"""
|
||||
if launch_auth_token() or _is_loopback(host):
|
||||
return host
|
||||
|
||||
global _GENERATED_TOKEN
|
||||
if _GENERATED_TOKEN is None:
|
||||
_GENERATED_TOKEN = _secrets.token_urlsafe(32)
|
||||
print(
|
||||
f"🔐 launch() bound to non-loopback host {host!r} without "
|
||||
f"PRAISONAI_LAUNCH_AUTH_TOKEN set. Generated a one-time bearer token "
|
||||
f"(set PRAISONAI_LAUNCH_AUTH_TOKEN to override): {_GENERATED_TOKEN}"
|
||||
)
|
||||
os.environ["PRAISONAI_LAUNCH_AUTH_TOKEN"] = _GENERATED_TOKEN
|
||||
return host
|
||||
@@ -22,6 +22,7 @@ from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import logging
|
||||
from praisonaiagents._logging import get_logger
|
||||
import time
|
||||
from dataclasses import dataclass, field
|
||||
@@ -160,32 +161,6 @@ def record_tool_call(
|
||||
if len(history) > max_size:
|
||||
del history[: len(history) - max_size]
|
||||
|
||||
def reset_matching_history(
|
||||
history: List[ToolCallRecord],
|
||||
tool_name: str,
|
||||
args: Any,
|
||||
) -> int:
|
||||
"""Drop every record for this exact ``(tool_name, args)`` pair in-place.
|
||||
|
||||
Used when a critical loop is *explicitly approved* to continue: simply
|
||||
popping the just-recorded call would leave the streak one below the
|
||||
threshold, so the very next identical call would re-trigger the gate. By
|
||||
removing the whole matching streak, an approved legitimate repeat gets a
|
||||
fresh window (another full ``critical_threshold`` run) before it is flagged
|
||||
again. Records for *other* tools/args are preserved, so concurrent activity
|
||||
on the same agent is unaffected.
|
||||
|
||||
Returns the number of records removed.
|
||||
"""
|
||||
args_hash = hash_tool_call(tool_name, args)
|
||||
before = len(history)
|
||||
history[:] = [
|
||||
rec for rec in history
|
||||
if not (rec.get("tool_name") == tool_name and rec.get("args_hash") == args_hash)
|
||||
]
|
||||
return before - len(history)
|
||||
|
||||
|
||||
def record_tool_outcome(
|
||||
history: List[ToolCallRecord],
|
||||
tool_name: str,
|
||||
|
||||
@@ -9,18 +9,8 @@ for maintainability.
|
||||
import os
|
||||
import inspect
|
||||
import logging
|
||||
import contextvars
|
||||
from typing import Optional
|
||||
|
||||
# Per-turn ownership of appended chat-history messages. Each chat()/achat() turn
|
||||
# runs in its own thread (sync) or task (async); both get an isolated copy of
|
||||
# this context var. The append helpers record every message THIS turn appends
|
||||
# into its own list, so a failing turn's rollback removes only its own messages
|
||||
# and never a concurrent turn's - even though all turns share one chat_history.
|
||||
_active_turn_owned: "contextvars.ContextVar[Optional[list]]" = contextvars.ContextVar(
|
||||
"praisonai_active_turn_owned", default=None
|
||||
)
|
||||
|
||||
# Shared lazy display helpers (cached, thread-safe; avoid circular imports)
|
||||
from ._lazy_display import _get_console, _get_live, _get_display_functions
|
||||
|
||||
@@ -67,11 +57,7 @@ class MemoryMixin:
|
||||
content: Message content
|
||||
"""
|
||||
with self._history_lock:
|
||||
msg = {"role": role, "content": content}
|
||||
self.chat_history.append(msg)
|
||||
owned = _active_turn_owned.get()
|
||||
if owned is not None:
|
||||
owned.append(msg)
|
||||
self.chat_history.append({"role": role, "content": content})
|
||||
|
||||
def _add_to_chat_history_if_not_duplicate(self, role, content) -> bool:
|
||||
"""Thread-safe method to add messages to chat history only if not duplicate.
|
||||
@@ -93,11 +79,7 @@ class MemoryMixin:
|
||||
return False
|
||||
|
||||
# Not a duplicate, add the message
|
||||
msg = {"role": role, "content": content}
|
||||
self.chat_history.append(msg)
|
||||
owned = _active_turn_owned.get()
|
||||
if owned is not None:
|
||||
owned.append(msg)
|
||||
self.chat_history.append({"role": role, "content": content})
|
||||
return True
|
||||
|
||||
def _get_chat_history_length(self):
|
||||
@@ -114,66 +96,6 @@ class MemoryMixin:
|
||||
with self._history_lock:
|
||||
self.chat_history = self.chat_history[:length]
|
||||
|
||||
def _begin_turn_tracking(self):
|
||||
"""Start recording the messages appended by the current turn.
|
||||
|
||||
Returns a token to reset the context var when the turn ends. Each turn
|
||||
runs in its own thread (sync ``chat``) or task (async ``achat``), so the
|
||||
context var copy is isolated per turn. Safe to call unconditionally; when
|
||||
a turn opts in, its rollback removes only its own messages by identity.
|
||||
"""
|
||||
return _active_turn_owned.set([])
|
||||
|
||||
def _end_turn_tracking(self, token):
|
||||
"""Stop recording for the current turn and drop its ownership list."""
|
||||
try:
|
||||
_active_turn_owned.reset(token)
|
||||
except (ValueError, LookupError):
|
||||
_active_turn_owned.set(None)
|
||||
|
||||
def _clear_turn_tracking(self):
|
||||
"""Drop any per-turn ownership list from a prior turn on this context.
|
||||
|
||||
Used at the start of an async turn (whose control flow has no single
|
||||
wrapping ``finally``) so a stale list from a completed turn on the same
|
||||
task cannot accumulate messages from unrelated turns.
|
||||
"""
|
||||
_active_turn_owned.set(None)
|
||||
|
||||
def _rollback_chat_history_to(self, rollback_length):
|
||||
"""Thread-safe rollback that never clobbers a concurrent turn's messages.
|
||||
|
||||
A turn snapshots ``len(self.chat_history)`` before a multi-second LLM
|
||||
call, then rolls back to that length on failure.
|
||||
|
||||
Ownership-safe path (default for ``chat``/``achat`` turns): when the turn
|
||||
opted into per-turn tracking via ``_begin_turn_tracking()``, remove ONLY
|
||||
the messages this turn actually appended, identified by object identity.
|
||||
A concurrent turn that interleaved its own messages after this snapshot
|
||||
keeps every one of them - the old positional ``del chat_history[n:]``
|
||||
would have erased them and corrupted the transcript.
|
||||
|
||||
Positional fallback (untracked callers): remove the tail from
|
||||
``rollback_length`` onward, and only if the history actually grew that
|
||||
far. Backward compatible for any path that does not track ownership.
|
||||
|
||||
Args:
|
||||
rollback_length: History length to roll back to (this turn's snapshot).
|
||||
"""
|
||||
owned = _active_turn_owned.get()
|
||||
with self._history_lock:
|
||||
if owned:
|
||||
owned_ids = {id(m) for m in owned}
|
||||
self.chat_history[:] = [
|
||||
m for m in self.chat_history if id(m) not in owned_ids
|
||||
]
|
||||
owned.clear()
|
||||
return
|
||||
|
||||
# Untracked turn (or nothing appended): safe positional rollback.
|
||||
if len(self.chat_history) > rollback_length:
|
||||
del self.chat_history[rollback_length:]
|
||||
|
||||
def _cache_get(self, cache_dict, key):
|
||||
"""Thread-safe LRU cache get operation.
|
||||
|
||||
@@ -318,25 +240,21 @@ class MemoryMixin:
|
||||
if hasattr(self._history_lock, 'is_async_context') and self._history_lock.is_async_context():
|
||||
# Cannot use asyncio.Lock in sync context - use thread lock as fallback
|
||||
import hashlib
|
||||
import uuid
|
||||
from datetime import datetime, timezone
|
||||
with self._history_lock._lock._thread_lock:
|
||||
if self._session_id is None: # Double-check after acquiring lock
|
||||
hour_str = datetime.now(timezone.utc).strftime("%Y%m%d%H")
|
||||
agent_hash = hashlib.sha256((self.name or "agent").encode()).hexdigest()[:6]
|
||||
# per-instance suffix so same-named agents can never collide
|
||||
self._session_id = f"{hour_str}-{agent_hash}-{uuid.uuid4().hex[:8]}"
|
||||
self._session_id = f"{hour_str}-{agent_hash}"
|
||||
else:
|
||||
# Use sync lock directly
|
||||
import hashlib
|
||||
import uuid
|
||||
from datetime import datetime, timezone
|
||||
with self._history_lock.lock():
|
||||
if self._session_id is None: # Double-check after acquiring lock
|
||||
hour_str = datetime.now(timezone.utc).strftime("%Y%m%d%H")
|
||||
agent_hash = hashlib.sha256((self.name or "agent").encode()).hexdigest()[:6]
|
||||
# per-instance suffix so same-named agents can never collide
|
||||
self._session_id = f"{hour_str}-{agent_hash}-{uuid.uuid4().hex[:8]}"
|
||||
self._session_id = f"{hour_str}-{agent_hash}"
|
||||
|
||||
# Call db adapter's on_agent_start to get previous messages
|
||||
try:
|
||||
@@ -513,28 +431,6 @@ class MemoryMixin:
|
||||
except Exception as e:
|
||||
logging.warning(f"Failed to persist message to session store: {e}")
|
||||
|
||||
async def _apersist_message(
|
||||
self,
|
||||
role: str,
|
||||
content: str,
|
||||
tool_calls=None,
|
||||
tool_call_id: Optional[str] = None,
|
||||
):
|
||||
"""Async wrapper for :meth:`_persist_message`.
|
||||
|
||||
The default JSON session store performs a file-locked, blocking
|
||||
read-modify-write to disk on every turn. Calling ``_persist_message``
|
||||
directly from ``_achat_impl`` would stall the entire event loop (other
|
||||
agents, streaming, background tasks) for the duration of that I/O on
|
||||
every user/assistant/tool turn. Offloading to a worker thread — the
|
||||
same treatment ``_persist_compaction_checkpoint`` already gets — keeps
|
||||
``achat()`` non-blocking as documented.
|
||||
"""
|
||||
import asyncio
|
||||
await asyncio.to_thread(
|
||||
self._persist_message, role, content, tool_calls, tool_call_id
|
||||
)
|
||||
|
||||
def _add_message_with_tool_fields(self, role, content, **tool_fields):
|
||||
"""Add a message carrying tool fields, tolerating stores without them.
|
||||
|
||||
|
||||
@@ -8,6 +8,7 @@ Thread-safe implementation for concurrent access.
|
||||
import threading
|
||||
import heapq
|
||||
import time
|
||||
import logging
|
||||
from praisonaiagents._logging import get_logger
|
||||
from typing import Optional, Any, List, Tuple
|
||||
from dataclasses import dataclass, field
|
||||
|
||||
@@ -89,8 +89,8 @@ class OCRAgent:
|
||||
ocr: OCR configuration
|
||||
verbose: Verbosity level for output
|
||||
"""
|
||||
from ..utils.model_alias import resolve_model_name
|
||||
llm = resolve_model_name(llm, model, "OCRAgent")
|
||||
if llm is None and model is not None:
|
||||
llm = model
|
||||
|
||||
self.name = name or "OCRAgent"
|
||||
self.instructions = instructions
|
||||
|
||||
@@ -1,211 +0,0 @@
|
||||
"""One vocabulary for "where does this run?", shared by Agent, AgentFlow and AgentTeam.
|
||||
|
||||
Two questions get asked about placement and they have different answers:
|
||||
|
||||
``run_on=``
|
||||
Where the **whole agent** runs -- the model calls, the loop, the tools, all
|
||||
of it on someone else's machine. Only a *managed runtime* can answer this,
|
||||
because running the loop remotely means something has to host the loop.
|
||||
|
||||
``tools_run_on=``
|
||||
Where **the tools** run. Thinking stays on this machine; only the shell,
|
||||
the file writes and the code execution move. Any sandbox or compute place
|
||||
can answer this, because all it has to do is run a command.
|
||||
|
||||
Keeping the two words apart is the entire point. The old surface used one word
|
||||
(``run_on=``) on ``AgentFlow``/``AgentTeam`` for the tools-only meaning, another
|
||||
(``compute=``) on ``LocalAgent`` for exactly the same meaning, and a third
|
||||
(``backend=``) for the whole-agent meaning -- so the same concept had two names
|
||||
and one name had two concepts.
|
||||
|
||||
Because the two questions have disjoint answer sets, a wrong pairing is a typo
|
||||
worth catching rather than a preference worth honouring. ``run_on="docker"``
|
||||
cannot mean anything: Docker does not host agent loops. It gets a ``TypeError``
|
||||
naming the parameter the user actually wanted, not a silent fallback.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any, Literal, NamedTuple, Optional, Union
|
||||
|
||||
# Runtimes that can host an entire agent loop. Resolved from the wrapper's
|
||||
# entry-point registry when it is installed so third-party backends work with
|
||||
# `run_on=` too; the literal is the floor, not the ceiling.
|
||||
_FALLBACK_MANAGED = ("anthropic",)
|
||||
|
||||
# Static spellings so editors can autocomplete and type-checkers can reject a
|
||||
# typo at the call site rather than at the first model turn. The runtime
|
||||
# functions below stay the authority for validation -- these exist for tooling,
|
||||
# which cannot call a function to learn a set.
|
||||
# Keep in sync with _compute_bridge._PROVIDERS | _sandbox_adapter.SANDBOX_ONLY.
|
||||
ManagedRuntime = Literal["anthropic"]
|
||||
|
||||
ToolPlace = Literal[
|
||||
"local", "subprocess", "sandlock", "docker", "e2b",
|
||||
"modal", "daytona", "flyio", "tenki", "novita", "ssh",
|
||||
]
|
||||
|
||||
|
||||
def managed_runtimes() -> tuple:
|
||||
"""Names that ``run_on=`` accepts -- places that host a whole agent."""
|
||||
try:
|
||||
from praisonai.integrations.backend_registry import get_backend_registry
|
||||
|
||||
names = tuple(get_backend_registry().list_all_names())
|
||||
if names:
|
||||
return tuple(sorted(set(names) | set(_FALLBACK_MANAGED)))
|
||||
except Exception:
|
||||
pass
|
||||
return _FALLBACK_MANAGED
|
||||
|
||||
|
||||
def tool_places() -> list:
|
||||
"""Names that ``tools_run_on=`` accepts -- places that can run a command.
|
||||
|
||||
Includes the resolver's aliases. Validation runs before resolution, so
|
||||
leaving them out rejected spellings the resolver handles happily:
|
||||
``tools_run_on="native"`` raised "not a known place" while
|
||||
``resolve_compute("native")`` returned a working sandlock adapter.
|
||||
"""
|
||||
try:
|
||||
from ..managed._compute_bridge import _ALIASES, available_providers
|
||||
|
||||
return sorted(set(available_providers()) | set(_ALIASES))
|
||||
except Exception:
|
||||
return ["local", "docker"]
|
||||
|
||||
|
||||
class Placement(NamedTuple):
|
||||
"""The resolved answer to "where does this run?"."""
|
||||
|
||||
whole: Optional[Any] = None # managed runtime name/object, or None
|
||||
tools: Optional[Any] = None # tools place name/object, or None
|
||||
|
||||
|
||||
def _name_of(value: Any) -> Optional[str]:
|
||||
"""The comparable name of a placement value, or None if it is an object.
|
||||
|
||||
Objects (a built provider, a live ``SSHSandbox``) carry their own config and
|
||||
are never second-guessed -- only bare strings get routed by name.
|
||||
"""
|
||||
return value.lower() if isinstance(value, str) else None
|
||||
|
||||
|
||||
def _quote_list(names) -> str:
|
||||
return ", ".join(repr(n) for n in names)
|
||||
|
||||
|
||||
def resolve_placement(
|
||||
owner: str,
|
||||
*,
|
||||
run_on: Any = None,
|
||||
tools_run_on: Any = None,
|
||||
backend: Any = None,
|
||||
supports_run_on: bool = True,
|
||||
) -> Placement:
|
||||
"""Validate placement arguments and return where things should run.
|
||||
|
||||
``owner`` is the class name, used only to make errors read naturally.
|
||||
``supports_run_on`` is False for AgentFlow/AgentTeam, which can place tools
|
||||
but cannot (yet) hand a whole multi-agent run to a managed runtime.
|
||||
|
||||
Raises:
|
||||
TypeError: on any combination that names two different places for the
|
||||
same thing, or a place that cannot do the job asked of it.
|
||||
"""
|
||||
managed = managed_runtimes()
|
||||
places = tool_places()
|
||||
|
||||
# ── a place that cannot do the job asked of it ───────────────────────────
|
||||
run_on_name = _name_of(run_on)
|
||||
if run_on_name is not None and run_on_name not in managed:
|
||||
if run_on_name in places:
|
||||
raise TypeError(
|
||||
f"{owner}(run_on={run_on!r}) is not valid: run_on= places the "
|
||||
f"whole agent -- model calls, loop and tools -- on a managed "
|
||||
f"runtime, and {run_on_name!r} runs commands but cannot host an "
|
||||
f"agent loop.\n"
|
||||
f" To run only the tools there: {owner}(tools_run_on={run_on!r})\n"
|
||||
f" Runtimes that host a whole agent: {_quote_list(managed)}"
|
||||
)
|
||||
raise TypeError(
|
||||
f"{owner}(run_on={run_on!r}) is not a known managed runtime.\n"
|
||||
f" Runtimes that host a whole agent: {_quote_list(managed)}\n"
|
||||
f" Places that can run tools: {_quote_list(places)} "
|
||||
f"(pass those as tools_run_on=)"
|
||||
)
|
||||
|
||||
tools_name = _name_of(tools_run_on)
|
||||
if tools_name is not None and tools_name in managed and tools_name not in places:
|
||||
raise TypeError(
|
||||
f"{owner}(tools_run_on={tools_run_on!r}) is not valid: {tools_name!r} "
|
||||
f"hosts an entire agent, not individual tools.\n"
|
||||
f" Did you mean: {owner}(run_on={tools_run_on!r})"
|
||||
)
|
||||
|
||||
# A typo here used to survive construction and only surface on the first
|
||||
# model turn -- after the prompt was built and, for a real run, after the
|
||||
# API spend. run_on= validates at the call site and YAML validates at load
|
||||
# time; this is the same standard for the third spelling.
|
||||
if tools_name is not None and tools_name not in places:
|
||||
raise TypeError(
|
||||
f"{owner}(tools_run_on={tools_run_on!r}) is not a known place.\n"
|
||||
f" Places that can run tools: {_quote_list(places)}\n"
|
||||
f" Runtimes that host a whole agent: {_quote_list(managed)} "
|
||||
f"(pass those as run_on=)"
|
||||
)
|
||||
|
||||
# Names that cannot work as a bare string, because the connection details
|
||||
# live in the object. Catch it now rather than at first use.
|
||||
if tools_name is not None:
|
||||
try:
|
||||
from ..managed._sandbox_adapter import NEEDS_INSTANCE
|
||||
except Exception:
|
||||
NEEDS_INSTANCE = {}
|
||||
if tools_name in NEEDS_INSTANCE:
|
||||
raise TypeError(
|
||||
f"{owner}(tools_run_on={tools_run_on!r}) needs more than a name: "
|
||||
f"{NEEDS_INSTANCE[tools_name]}"
|
||||
)
|
||||
|
||||
# ── two names for the same thing ─────────────────────────────────────────
|
||||
if run_on is not None and backend is not None:
|
||||
raise TypeError(
|
||||
f"{owner}(run_on=..., backend=...) sets the agent's runtime twice. "
|
||||
f"run_on={run_on!r} is the short form of backend=HostedAgent("
|
||||
f"provider={run_on!r}); pass one or the other.\n"
|
||||
f" Use backend= only when you need to configure the runtime "
|
||||
f"(model, system prompt, tools)."
|
||||
)
|
||||
|
||||
if run_on is not None and tools_run_on is not None:
|
||||
raise TypeError(
|
||||
f"{owner}(run_on={run_on!r}, tools_run_on={tools_run_on!r}) points "
|
||||
f"the tools at two machines. run_on= already runs everything -- "
|
||||
f"including tools -- on {run_on!r}.\n"
|
||||
f" Whole agent remote: {owner}(run_on={run_on!r})\n"
|
||||
f" Only tools remote: {owner}(tools_run_on={tools_run_on!r})"
|
||||
)
|
||||
|
||||
if backend is not None and tools_run_on is not None:
|
||||
raise TypeError(
|
||||
f"{owner}(backend=..., tools_run_on={tools_run_on!r}) points the "
|
||||
f"tools at two machines: backend= runs the whole agent (tools "
|
||||
f"included) on its managed runtime, so the tools cannot also run on "
|
||||
f"{tools_run_on!r}.\n"
|
||||
f" Drop tools_run_on= to keep the hosted runtime, or drop backend= "
|
||||
f"to keep local thinking with remote tools."
|
||||
)
|
||||
|
||||
# ── a class that cannot answer this question ─────────────────────────────
|
||||
if run_on is not None and not supports_run_on:
|
||||
raise TypeError(
|
||||
f"{owner}(run_on={run_on!r}) is not supported: run_on= hands one "
|
||||
f"agent's whole loop to a managed runtime, and a {owner} "
|
||||
f"orchestrates several agents locally.\n"
|
||||
f" To run every step's tools in one shared sandbox:\n"
|
||||
f" {owner}(tools_run_on={run_on!r})\n"
|
||||
f" To host a single agent's loop, put run_on= on that Agent."
|
||||
)
|
||||
|
||||
return Placement(whole=run_on, tools=tools_run_on)
|
||||
@@ -1,138 +0,0 @@
|
||||
"""Prompt-cache-stability contract for the Agent turn (Issue #3352).
|
||||
|
||||
Provider prompt caching (Anthropic/OpenAI) only hits when the *leading* bytes
|
||||
of a request are byte-identical to the previous request. For a long-lived
|
||||
conversation the cached prefix — the system instructions, the serialised tool
|
||||
schemas, and the model identity — is the dominant cost and latency lever.
|
||||
|
||||
Gateways run many users on a single shared ``Agent`` instance and swap
|
||||
``tools``/``llm`` in and out per turn (per-route tool scoping, per-user
|
||||
``/model`` override). Those swaps silently change the cached prefix and the
|
||||
provider cache misses with zero operator visibility.
|
||||
|
||||
``prompt_prefix_signature`` gives callers a single, cheap, deterministic
|
||||
fingerprint of exactly the cache-relevant inputs — model, the sorted set of
|
||||
tool names, and a fingerprint of the system instructions — and *nothing*
|
||||
volatile per-turn (arrival time, routing facts, memory/RAG recall). When the
|
||||
signature is unchanged across turns the prefix is guaranteed stable, so the
|
||||
provider cache keeps hitting; when it changes, that is the one auditable point
|
||||
at which cache warmth is knowingly sacrificed.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
from typing import Any
|
||||
|
||||
|
||||
def _tool_name(tool: Any) -> str:
|
||||
"""Best-effort stable name for a tool entry.
|
||||
|
||||
Tools may be plain callables, dicts holding an OpenAI-style function
|
||||
schema, or objects exposing ``__name__``/``name``. The name identifies the
|
||||
schema slot in the serialised tool block.
|
||||
"""
|
||||
if isinstance(tool, dict):
|
||||
fn = tool.get("function")
|
||||
if isinstance(fn, dict) and fn.get("name"):
|
||||
return str(fn["name"])
|
||||
for key in ("name", "type"):
|
||||
if tool.get(key):
|
||||
return str(tool[key])
|
||||
return str(sorted(tool.keys()))
|
||||
for attr in ("__name__", "name"):
|
||||
value = getattr(tool, attr, None)
|
||||
if value:
|
||||
return str(value)
|
||||
return str(tool)
|
||||
|
||||
|
||||
def _tool_fingerprint(tool: Any) -> str:
|
||||
"""Best-effort stable fingerprint of a tool's *provider-visible* schema.
|
||||
|
||||
The serialised tool block sent to the provider is not just the tool name —
|
||||
it is the full function schema (name + description + parameters). A change
|
||||
to a tool's description, parameters, or required fields *without* a rename
|
||||
changes those bytes and therefore invalidates the prompt cache, so the
|
||||
fingerprint must reflect the whole schema, not only the name (Issue #3352
|
||||
review). Falls back to the name when no richer schema is exposed.
|
||||
"""
|
||||
name = _tool_name(tool)
|
||||
|
||||
# Dict tools already carry an OpenAI-style function schema — fingerprint the
|
||||
# description + parameters alongside the name so a same-name schema edit is
|
||||
# detected. ``json.dumps(sort_keys=True)`` makes the render deterministic.
|
||||
if isinstance(tool, dict):
|
||||
fn = tool.get("function")
|
||||
schema = fn if isinstance(fn, dict) else tool
|
||||
desc = schema.get("description") if isinstance(schema, dict) else None
|
||||
params = schema.get("parameters") if isinstance(schema, dict) else None
|
||||
try:
|
||||
import json
|
||||
|
||||
return "\x01".join(
|
||||
(
|
||||
name,
|
||||
str(desc or ""),
|
||||
json.dumps(params or {}, sort_keys=True, default=str),
|
||||
)
|
||||
)
|
||||
except Exception: # pragma: no cover — defensive
|
||||
return name
|
||||
|
||||
# Callable/object tools: fold in the docstring (the description the schema
|
||||
# generator emits) so an edited tool doc flips the signature too.
|
||||
doc = getattr(tool, "__doc__", None)
|
||||
if doc:
|
||||
return f"{name}\x01{doc}"
|
||||
return name
|
||||
|
||||
|
||||
def prompt_prefix_signature(agent: Any) -> str:
|
||||
"""Return a sha256 signature of an agent's cache-relevant prompt prefix.
|
||||
|
||||
The signature is computed over, and only over:
|
||||
|
||||
* the model identity (``agent.llm``),
|
||||
* the sorted set of tool *schema fingerprints* (name + description +
|
||||
parameters, ``agent.tools``) — so a same-name schema edit is detected,
|
||||
* a fingerprint of the system instructions (``agent.instructions``).
|
||||
|
||||
Volatile per-turn data is intentionally excluded so that an unchanged
|
||||
route/model keeps a byte-identical prefix and the provider cache keeps
|
||||
hitting. Callers compare the signature turn-over-turn: an unchanged value
|
||||
means the cached prefix is reused; a changed value is the single auditable
|
||||
point of prompt-cache invalidation.
|
||||
|
||||
Best-effort and never raises: any attribute access failure degrades the
|
||||
corresponding component to an empty string rather than breaking the turn.
|
||||
"""
|
||||
try:
|
||||
llm = getattr(agent, "llm", None)
|
||||
model = llm if isinstance(llm, str) else getattr(llm, "model", None) or str(llm)
|
||||
except Exception:
|
||||
model = ""
|
||||
|
||||
try:
|
||||
tools = getattr(agent, "tools", None) or []
|
||||
tool_fps = sorted(_tool_fingerprint(t) for t in tools)
|
||||
except Exception:
|
||||
tool_fps = []
|
||||
|
||||
try:
|
||||
instructions = getattr(agent, "instructions", None) or ""
|
||||
instructions = str(instructions)
|
||||
except Exception:
|
||||
instructions = ""
|
||||
|
||||
hasher = hashlib.sha256()
|
||||
hasher.update(b"model\x00")
|
||||
hasher.update(str(model).encode("utf-8", "replace"))
|
||||
hasher.update(b"\x00tools\x00")
|
||||
hasher.update("\x00".join(tool_fps).encode("utf-8", "replace"))
|
||||
hasher.update(b"\x00instructions\x00")
|
||||
hasher.update(instructions.encode("utf-8", "replace"))
|
||||
return hasher.hexdigest()
|
||||
|
||||
|
||||
__all__ = ["prompt_prefix_signature"]
|
||||
@@ -57,8 +57,7 @@ class RealtimeAgent:
|
||||
def __init__(
|
||||
self,
|
||||
name: str = "RealtimeAgent",
|
||||
llm: Optional[str] = None, # Deprecated alias for model=
|
||||
model: Optional[str] = None,
|
||||
llm: Optional[str] = None,
|
||||
realtime: Optional[Union[bool, Dict, RealtimeConfig]] = None,
|
||||
instructions: Optional[str] = None,
|
||||
verbose: bool = True,
|
||||
@@ -68,16 +67,14 @@ class RealtimeAgent:
|
||||
|
||||
Args:
|
||||
name: Agent name
|
||||
llm: Deprecated alias for model=. Passing both raises TypeError.
|
||||
model: Model to use (default: gpt-4o-realtime-preview)
|
||||
llm: LLM model (default: gpt-4o-realtime-preview)
|
||||
realtime: Realtime configuration (bool, dict, or RealtimeConfig)
|
||||
instructions: System instructions
|
||||
verbose: Enable verbose output
|
||||
**kwargs: Additional arguments
|
||||
"""
|
||||
from ..utils.model_alias import resolve_model_name
|
||||
self.name = name
|
||||
self.llm = resolve_model_name(llm, model, "RealtimeAgent") or "gpt-4o-realtime-preview"
|
||||
self.llm = llm or "gpt-4o-realtime-preview"
|
||||
self.instructions = instructions
|
||||
self.verbose = verbose
|
||||
|
||||
|
||||
@@ -6,6 +6,7 @@ model selection based on task characteristics.
|
||||
"""
|
||||
|
||||
import os
|
||||
import logging
|
||||
from praisonaiagents._logging import get_logger
|
||||
from typing import Dict, List, Optional, Any, Union
|
||||
from .agent import Agent
|
||||
|
||||
@@ -1,95 +0,0 @@
|
||||
"""Canonical terminal-outcome contract for agent runs.
|
||||
|
||||
A single, closed description of *how* a run ended, produced once by the core
|
||||
run and consumed everywhere. Long-running hosts (e.g. gateways/bots) can make
|
||||
delivery/retry/DLQ/status decisions from one field instead of inferring the
|
||||
terminal state from exception identity.
|
||||
|
||||
Precedence is explicit and sticky: a ``hard_timeout`` is never silently
|
||||
downgraded by later cleanup. See ``RunOutcome.from_exception``.
|
||||
"""
|
||||
|
||||
from dataclasses import dataclass
|
||||
from typing import Optional
|
||||
try:
|
||||
from typing import Literal
|
||||
except ImportError: # pragma: no cover - py<3.8 fallback
|
||||
Literal = None # type: ignore
|
||||
|
||||
if Literal is not None:
|
||||
TerminalReason = Literal[
|
||||
"completed", "hard_timeout", "cancelled", "aborted", "failed"
|
||||
]
|
||||
else: # pragma: no cover
|
||||
TerminalReason = str # type: ignore
|
||||
|
||||
# Precedence: higher wins and is sticky (a hard timeout is not downgraded).
|
||||
_REASON_PRECEDENCE = {
|
||||
"completed": 0,
|
||||
"failed": 1,
|
||||
"aborted": 2,
|
||||
"cancelled": 3,
|
||||
"hard_timeout": 4,
|
||||
}
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class RunOutcome:
|
||||
"""Closed, canonical description of how an agent run ended.
|
||||
|
||||
Attributes:
|
||||
reason: One of ``completed | hard_timeout | cancelled | aborted | failed``.
|
||||
output: Partial or final text, if any.
|
||||
error: Redacted message when ``reason == "failed"``.
|
||||
"""
|
||||
|
||||
reason: "TerminalReason"
|
||||
output: Optional[str] = None
|
||||
error: Optional[str] = None
|
||||
|
||||
@property
|
||||
def succeeded(self) -> bool:
|
||||
"""True only when the run completed normally."""
|
||||
return self.reason == "completed"
|
||||
|
||||
@classmethod
|
||||
def completed(cls, output: Optional[str] = None) -> "RunOutcome":
|
||||
return cls(reason="completed", output=output)
|
||||
|
||||
@classmethod
|
||||
def from_exception(
|
||||
cls, exc: BaseException, output: Optional[str] = None
|
||||
) -> "RunOutcome":
|
||||
"""Normalise a raised exception into a canonical terminal outcome.
|
||||
|
||||
Maps well-known exception types to their terminal reason. Anything
|
||||
unrecognised is treated as ``failed`` with a redacted message.
|
||||
|
||||
Note on ``hard_timeout``: the run-level budget is the authoritative
|
||||
source of ``hard_timeout`` and is applied explicitly by the caller
|
||||
(see ``_astart_with_outcome``). A bare ``asyncio.TimeoutError`` reaching
|
||||
this normaliser is a *nested* operation timeout (e.g. a handoff/tool that
|
||||
exhausted its own budget while the run budget remained) and is therefore
|
||||
classified as ``failed`` — not silently promoted to a run-budget
|
||||
``hard_timeout``, which would drive the wrong host retry/DLQ decision.
|
||||
Real cooperative cancellation is intercepted and re-raised by the run
|
||||
wrapper (see ``_astart_with_outcome``) *before* it reaches this
|
||||
normaliser, so host shutdown is honoured. A supersede/interrupt named
|
||||
error that does surface here is a domain "cancelled" outcome.
|
||||
"""
|
||||
import asyncio
|
||||
|
||||
if _name_matches(exc, ("hardtimeout", "runtimeout", "budgettimeout")):
|
||||
return cls(reason="hard_timeout", output=output)
|
||||
if isinstance(exc, asyncio.CancelledError) or _name_matches(
|
||||
exc, ("supersed", "interrupt", "cancelled")
|
||||
):
|
||||
return cls(reason="cancelled", output=output)
|
||||
if _name_matches(exc, ("abort", "drain", "shutdown")):
|
||||
return cls(reason="aborted", output=output)
|
||||
return cls(reason="failed", output=output, error=str(exc))
|
||||
|
||||
|
||||
def _name_matches(exc: BaseException, needles: tuple) -> bool:
|
||||
name = type(exc).__name__.lower()
|
||||
return any(n in name for n in needles)
|
||||
Loaded 100 of 1406 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user