[parity][P3] Export `is_sticky` in praisonai-ts

Aperta
#5,297 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

  • #5299 di @praisonai-triage-agent — chiusa senza merge

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
python, typescript
Ambito
ai

Direzione di ricerca

Read is_sticky, _STICKY_SOURCES and merge_run_terminal in src/praisonai-agents/praisonaiagents/run_outcome.py, and the cases in tests/unit/test_run_outcome.py. Port the RunTerminal shape and is_sticky into src/praisonai-ts, then export it from the root src/index.ts barrel. Done when a TypeScript test imports is_sticky from the package entry and passes, and the parity generator --check reports is_sticky as present. A closed, unmerged pull request (#5299) already targets this issue, so check why it was closed first.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

claude documentation enhancement javascript

Executive summary

Python exposes is_sticky as part of the public SDK surface. TypeScript does not yet
export an equivalent symbol, so cross-language examples, mobile/Node clients, and parity
tests cannot rely on the same API shape.

Field Value
Feature is_sticky
Priority P3
Effort (generator estimate) low
Category other
Gap bucket P3_Advanced
Python present
TypeScript missing
Source of truth Python praisonaiagents
Why this matters
  • Cross-SDK parity: Teams porting Python agent code to TypeScript hit import errors or silent
    behavior drift when is_sticky is absent.
  • Downstream products: Runtimes that embed praisonai-ts (CLI, mobile shell, server adapters)
    cannot enable features guarded by this export.
  • Tracker integrity: The parity checker keeps gapCount elevated until TypeScript exports
    match Python for this symbol.
Out of scope for a minimal fix
  • Renaming Python exports (Python remains canonical).
  • Partial stubs that do not match Python semantics — parity tests should fail loudly until behavior matches.

Core issue deep dive — is_sticky

_STICKY_SOURCES = frozenset({"external", "run_budget", "superseded"})

def is_sticky(outcome: RunTerminal) -> bool:
    return outcome.source in _STICKY_SOURCES

Sticky terminals must never be overwritten by later weaker observations in merge_run_terminal.

Source stickiness table
TerminalSource Sticky?
external Yes
run_budget Yes
superseded Yes
completion, idle, provider No
Tests
  • test_hard_timeout_is_sticky
  • test_superseded_is_sticky
  • Sticky promotion cases in test_equal_kind_sticky_promotes_over_nonsticky

Export as is_sticky at package boundary.

Parity checker evidence

The official generator compares Python (praisonaiagents) exports against
praisonai-ts public surface and writes FEATURE_PARITY_TRACKER.json plus PARITY.md.

Regenerate and verify (from repository root)
cd src/praisonai
export PYTHONIOENCODING=utf-8
python -m praisonai._dev.parity.generator --target ts --check

On Windows PowerShell:

$env:PYTHONIOENCODING = 'utf-8'
cd src/praisonai
python -m praisonai._dev.parity.generator --target ts --check

When the tracker is not up to date, --check exits non-zero after rewriting files.
When up to date, output includes confirmation that src/praisonai-ts/FEATURE_PARITY_TRACKER.json
and src/praisonai-ts/PARITY.md match extracted exports.

Inspect this gap programmatically
python - <<'PY'
import json
from pathlib import Path
data = json.loads(Path("src/praisonai-ts/FEATURE_PARITY_TRACKER.json").read_text())
print("gapCount:", data["summary"]["gapCount"])
print("priority P0:", data["summary"]["priorityP0"])
for bucket, rows in data["gapMatrix"].items():
    for row in rows:
        if row.get("feature") == "is_sticky":
            print("bucket:", bucket)
            print(json.dumps(row, indent=2))
PY
Snapshot at issue generation time
Metric Value
Total open export gaps 4
P0 gaps 0
P3 gaps 4
TypeScript tracked features 2082
Python core features 421

This issue: is_sticky is marked python: true, typescript: false, status: TODO
in gapMatrix.

Architecture context

flowchart TB
  subgraph python [Python SDK — source of truth]
    PA[praisonaiagents public exports]
    F["is_sticky"]
    PA --> F
  end
  subgraph ts [praisonai-ts]
    IDX[src/index.ts barrel]
    MOD[domain modules]
    IDX --> MOD
    GAP["is_sticky — missing export"]
    MOD -.-> GAP
  end
  subgraph chk [Parity tooling]
    GEN[praisonai._dev.parity.generator]
    TR[FEATURE_PARITY_TRACKER.json]
    GEN --> TR
  end
  F --> GEN
  MOD --> GEN
  TR --> ISSUE[GitHub issue / CI gate]

Category other indicates where the implementation likely lives in both trees
(agent, app, config, bots, ui, other). Start discovery in the matching package area before
adding a top-level re-export.

Python references (sample)
File Line Snippet
src/praisonai-agents/praisonaiagents/run_outcome.py 398 def is_sticky(outcome: RunTerminal) -> bool:
src/praisonai-agents/praisonaiagents/run_outcome.py 436 if is_sticky(current):
src/praisonai-agents/praisonaiagents/run_outcome.py 442 if observed_rank == current_rank and is_sticky(observed):
src/praisonai-agents/praisonaiagents/run_outcome.py 467 "is_sticky",
src/praisonai-agents/praisonaiagents/__init__.py 151 'is_sticky': ('praisonaiagents.run_outcome', 'is_sticky'),
src/praisonai-agents/tests/unit/test_run_outcome.py 225 def test_hard_timeout_is_sticky(self):
src/praisonai-agents/tests/unit/test_run_outcome.py 226 from praisonaiagents.run_outcome import RunTerminal, merge_run_terminal, is_sticky, collapse
src/praisonai-agents/tests/unit/test_run_outcome.py 230 assert is_sticky(timeout)
src/praisonai-agents/tests/unit/test_run_outcome.py 269 def test_superseded_is_sticky(self):
src/praisonai-agents/tests/unit/test_run_outcome.py 270 from praisonaiagents.run_outcome import RunTerminal, merge_run_terminal, is_sticky
Code excerpt (src/praisonai-agents/praisonaiagents/run_outcome.py)
  390|         """Rehydrate from a plain dict produced by :meth:`to_dict`."""
  391|         return cls(
  392|             kind=data["kind"],
  393|             source=data["source"],
  394|             detail=data.get("detail"),
  395|         )
  396| 
  397| 
  398| def is_sticky(outcome: RunTerminal) -> bool:
  399|     """Whether ``outcome`` can never be overwritten by a later observation.
  400| 
  401|     Deliberate cancellations (``external``), hard run-budget timeouts
  402|     (``run_budget``), and supersedes (``superseded``) are intentional
  403|     terminals: once recorded they are authoritative.
  404|     """
  405|     return outcome.source in _STICKY_SOURCES
  406| 
  407| 
  408| def merge_run_terminal(
  409|     current: Optional[RunTerminal], observed: RunTerminal
  410| ) -> RunTerminal:
  411|     """Fold a newly-observed terminal into the current one (refine-only).
  412| 
  413|     Pure, deterministic, and **order-independent**: folding the same set of
  414|     observations always yields the same authoritative outcome regardless of the
  415|     sequence in which they arrive. Rules, in order:
  416| 
  417|     1. No current outcome — the observation becomes authoritative.
  418|     2. Current is sticky — it can never be downgraded; keep it.
  419|     3. Observation has strictly stronger attribution
  420|        (``aborted`` > ``timeout`` > ``failed`` > ``ok``) — refine to it.
  421|     4. Equal attribution strength but the observation is sticky while the
  422|        current writer is not — promote to the sticky observation so a later
  423|        ``run_budget`` / ``external`` / ``superseded`` of the same kind can no
TypeScript references (sample)

No matches under src/praisonai-ts — confirms the export gap is real (not just a barrel omission).

Implementation plan (TypeScript)

Phase 1 — Discovery
  1. Locate Python definition(s) for is_sticky (see tables above).
  2. Identify dependent types, protocols, and exceptions referenced by the implementation.
  3. Search src/praisonai-ts for partial implementations under different names (is_sticky, camelCase variants).
Phase 2 — API design
  1. Mirror Python names at the package boundary (PascalCase types, camelCase functions) per existing TS conventions.
  2. Add types to the closest module (avoid any; prefer strict structs matching Python dataclasses/TypedDicts).
  3. Export from the module index and root src/index.ts if Python exports from top-level praisonaiagents.
Phase 3 — Implementation
  1. Port logic incrementally; keep I/O boundaries explicit (async vs sync parity with Python).
  2. Reuse existing utilities (logging, config, agent runtime) instead of duplicating parallel stacks.
  3. Guard feature flags if Python gates behavior behind config objects.
Phase 4 — Tests
  1. Add unit tests under src/praisonai-ts/tests/ mirroring Python test scenarios where they exist.
  2. Add a parity-focused test asserting is_sticky is exported from the package entry used by consumers.
  3. Run npm test / pnpm test in src/praisonai-ts.
Phase 5 — Tracker refresh
cd src/praisonai
PYTHONIOENCODING=utf-8 python -m praisonai._dev.parity.generator --target ts
git diff src/praisonai-ts/FEATURE_PARITY_TRACKER.json src/praisonai-ts/PARITY.md

Expect is_sticky to move to typescript: true / DONE in its bucket row.

Suggested file touch list (adjust after discovery)
Area Likely paths
Implementation src/praisonai-ts/src/**/is_sticky.ts or nearest domain folder
Barrel export src/praisonai-ts/src/index.ts
Types collocated *.types.ts or module index
Tests src/praisonai-ts/tests/unit/**/is_sticky.test.ts
Docs src/praisonai-ts/PARITY.md (auto-generated)

Detailed test scenarios

    ### TS-is_sticky-001 — Export surface

    - **Given** a clean install of `praisonai-ts`
    - **When** importing `is_sticky` from the package root
    - **Then** the symbol is defined and typed (not `any`)

    ### TS-is_sticky-002 — Runtime smoke

    - **Given** minimal valid configuration mirrored from Python docs
    - **When** executing the primary API path
    - **Then** outputs match Python shape (fields, enums, error types)

    ### TS-is_sticky-003 — Failure semantics

    - **Given** invalid inputs used in Python tests
    - **When** invoking TypeScript API
    - **Then** reject with equivalent error class / message pattern

    ### TS-is_sticky-004 — Concurrency / async

    - **Given** parallel callers (if applicable)
    - **When** stress-testing async entrypoints
    - **Then** no lost errors; bounded concurrency matches Python defaults

    ### TS-is_sticky-005 — Regression guard

    - Add a unit test that fails if `is_sticky` disappears from exports (meta-test scanning `index.ts`).

    | ID | Scenario | Verification |

|----|----------|--------------|
| export-present | import { is_sticky } from 'praisonai-ts' resolves | package exports map |
| types-compile | TypeScript strict build passes | tsc / build script |
| python-parity-smoke | Behavior matches Python reference for happy path | unit + manual script |
| error-paths | Validation errors align with Python exception types | unit tests |
| async-contract | Async functions return awaited types consistent with Python | unit tests |
| config-guards | Config flags disable/enable feature like Python | unit tests |
| tracker | Parity generator marks feature DONE | generator --target ts |
| docs | PARITY.md no longer lists gap for this feature | generated markdown |
| tree-shaking | Export does not pull unintended heavy deps | bundle size spot check |
| mobile-shell | Consumers (e.g. mobile) compile against new export | integration build |

    ## Acceptance criteria

    - [ ] `is_sticky` exported from `praisonai-ts` public API
    - [ ] Unit tests cover happy path + primary error paths
    - [ ] `python -m praisonai._dev.parity.generator --target ts --check` passes
    - [ ] `FEATURE_PARITY_TRACKER.json` marks `is_sticky` as TypeScript complete
    - [ ] No breaking change to unrelated exports (semver note in PR if needed)

Risks and rollout notes

Risk Mitigation
Behavior drift vs Python Port tests from Python; compare JSON snapshots
Bundle size increase Lazy import heavy deps; keep core export thin
Partial stub shipped Block merge until parity test green
Naming mismatch Follow existing TS naming table in adjacent modules

Related gaps

See src/praisonai-ts/PARITY.md for neighboring TODO rows in the same bucket. Closing is_sticky
may unblock downstream exports that depend on shared protocols or event types.

Definition of Done

  1. Implementation merged to main.
  2. Parity tracker regenerated in the same PR (or immediately follow-up) so CI reflects closure.
  3. Release notes mention is_sticky for TypeScript consumers.

Appendix A — Parity workflow diagram

sequenceDiagram
  participant Dev as Contributor
  participant Py as Python SDK
  participant Gen as parity.generator
  participant TS as praisonai-ts
  participant CI as CI check
  Dev->>Py: Read canonical API
  Dev->>TS: Implement export
  Dev->>Gen: --target ts
  Gen->>TS: Refresh FEATURE_PARITY_TRACKER.json
  Dev->>CI: --check must pass

Appendix B — FAQ

Q: Can we mark DONE without implementation?
A: No — extractor validates public exports, not comments.

Q: Should mobile re-implement is_sticky?
A: No — consume via praisonai-ts once exported.

Q: Effort says is_sticky is high — can we split?
A: Yes, use sub-PRs behind a tracking issue, but keep parity row IN_PROGRESS until complete.

Appendix C — Checklist (copy into PR)

  • Read Python source for is_sticky
  • Map types 1:1 (names + optional/required)
  • Implement module + export
  • Unit tests
  • Run parity generator
  • Update release notes

Sibling gaps in this parity slice

Related exports still tracked separately: RunTerminal, merge_run_terminal, collapse. Implement in coordinated PRs or one PR closing multiple tracker rows.


Filed 2026-09-24 from current parity pack (gapCount: 4 on main). Pre-flight: praisonai._dev.parity.generator --target ts --check.

Lingua principale
Python
Stelle
9.3k
Fork
1.5k
Merge medio
1g 5h
PR unite (30g)
520

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di MervinPraison/PraisonAI

Tutte le issue di MervinPraison/PraisonAI

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.