docs: fix broken `_astructured_completion` example in thread-safety.mdx (removed by PraisonAI PR #3991)

[MervinPraison]

Summary

PraisonAI PR #3991 (merged 2026-08-16, closes #3990) removed the dead private method BaseAutoGenerator._astructured_completion from src/praisonai/praisonai/auto.py. The method had zero call sites in the SDK — but docs/features/thread-safety.mdx still teaches users to call it directly in a copy-paste code example, and mentions it in two behaviour-change notes. The code example will now raise AttributeError on any current install.

This is a small, well-scoped fix — one file, three edits.

Upstream source of truth:

• Removed in: fix: remove dead private method _astructured_completion PraisonAI#3991 (merged 2026-08-16T17:07:33Z)
• Root issue: Dead private method _astructured_completion in wrapper auto.py (unreferenced duplicate of async completion path) PraisonAI#3990
• Head SHA: 33d8aaf5cb7c605a09e0013c7f2020e947303257
• Diff: only src/praisonai/praisonai/auto.py:697-716 removed (verified against the PR diff)

---

Edits required — all in docs/features/thread-safety.mdx

Edit 1 · Fix the broken async code example

Current (broken — method no longer exists):

# Async context manager
async with BaseAutoGenerator(config_list=[{
    "model": "gpt-4o-mini",
    "api_key": os.getenv("OPENAI_API_KEY"),
    "base_url": None,
}]) as gen:
    result = await gen._astructured_completion(MyModel, messages=[...])

Replace the last line with the live async path (verified against src/praisonai/praisonai/auto.py:718-732 on main):

    result = await gen._structured_completion_async(MyModel, messages=[...], is_async=True)

_structured_completion_async(..., is_async=True) is what _astructured_completion internally delegated to. Issue #3990 explicitly states its behaviour is "fully covered by _structured_completion_async(is_async=True)".

Edit 2 · Remove the stale reference in the PR #1736 warning

Current:

Behaviour change in PR #1736: __del__ was removed and async support was added. New methods include aclose, __aenter__/__aexit__, and _astructured_completion. Use context managers or explicit cleanup instead of relying on destructors.

Update to:

Behaviour change in PR #1736: __del__ was removed and async support was added. New methods include aclose, __aenter__/__aexit__, and _structured_completion_async (originally added as _astructured_completion, renamed and consolidated on the live path — the shorter alias was removed as dead code in PR #3991). Use context managers or explicit cleanup instead of relying on destructors.

Edit 3 · Remove the stale reference in the PR #2963 warning

Current:

Behaviour change in PR for #2963: BaseAutoGenerator now owns a single _core_client: OpenAIClient (the core-owned client) instead of separate _openai_client / _async_openai_client attributes. The methods _get_openai_client() and _get_async_openai_client() were consolidated into _get_core_client(). The public surface (close, aclose, __enter__/__exit__, __aenter__/__aexit__, _structured_completion, _astructured_completion) is unchanged.

Update to (drop the stale name from the surface list; keep the sentence's meaning intact):

Behaviour change in PR for #2963: BaseAutoGenerator now owns a single _core_client: OpenAIClient (the core-owned client) instead of separate _openai_client / _async_openai_client attributes. The methods _get_openai_client() and _get_async_openai_client() were consolidated into _get_core_client(). The public surface (close, aclose, __enter__/__exit__, __aenter__/__aexit__, _structured_completion, _structured_completion_async) is unchanged as of PR #2963. _astructured_completion was later removed as dead code in PR #3991 — call _structured_completion_async instead.

---

Why this matters

• docs/features/thread-safety.mdx is a "power user" page, and the example lives under the deliberate heading "For power users building generators directly". Any user who copies it will hit AttributeError: 'BaseAutoGenerator' object has no attribute '_astructured_completion' on the very next release.
• The two behaviour-change notes are documentation of intent — leaving a removed symbol in the "new methods" and "public surface" lists misleads maintainers about what the API actually is today.
• Both fixes are additive text-only edits in a single existing page; no new page, no docs.json change, no diagram rework.

---

Placement checklist (per repo AGENTS.md)

• Edits stay in docs/features/thread-safety.mdx — do not migrate the page or split it.
• Do not touch docs/concepts/ (human-approved only).
• Do not modify auto-generated docs/sdk/reference/** — those regenerate from source.
• Re-verify the replacement signature against src/praisonai/praisonai/auto.py at head SHA 33d8aaf5cb7c605a09e0013c7f2020e947303257 before pushing.

Out of scope

• Do not rewrite the surrounding "Per-instance OpenAI client lifecycle" section — its structure and the _get_core_client() guidance remain correct after PR #3991.
• Do not remove either PR Docs alignment sweep: enforce AGENTS.md guidelines across feature pages (interaction flows, decision diagrams, agent-centric intros) #1736 or PR docs: cover three reliability fixes from PraisonAI PR #3960 #2963 warning block — both remain historically accurate for the changes they describe; only the mention of _astructured_completion needs updating.

---

Filed by the docs-triage scheduled routine on 2026-08-16, triggered by the pull_request.closed webhook for PraisonAI PR #3991. Verified against upstream diff at head SHA 33d8aaf5cb7c605a09e0013c7f2020e947303257.

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job • claude/issue-2961-20260816-1715 • [Create PR ➔](https://github.com/MervinPraison/PraisonAIDocs/compare/main...claude/issue-2961-20260816-1715?quick_pull=1&title=Issue%20%232961%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%232961%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Fixed broken _astructured_completion example in thread-safety.mdx

• Read docs/features/thread-safety.mdx
• Verify replacement signature in SDK source (_structured_completion_async(self, response_model, messages, *, is_async, **kwargs) confirmed in praisonai/auto.py:713)
• Edit 1: Fix broken async code example
• Edit 2: Update PR Docs alignment sweep: enforce AGENTS.md guidelines across feature pages (interaction flows, decision diagrams, agent-centric intros) #1736 warning note
• Edit 3: Update PR docs: cover three reliability fixes from PraisonAI PR #3960 #2963 warning note
• Commit and push changes
• Open PR

Summary

Fixed the broken code example and two stale references in docs/features/thread-safety.mdx:

1. Code example (line 581) — replaced await gen._astructured_completion(MyModel, messages=[...]) with the live async path await gen._structured_completion_async(MyModel, messages=[...], is_async=True). Signature verified against local praisonai/auto.py:713.
2. PR Docs alignment sweep: enforce AGENTS.md guidelines across feature pages (interaction flows, decision diagrams, agent-centric intros) #1736 warning (line 587) — "new methods" list now names _structured_completion_async, noting the removed _astructured_completion alias.
3. PR docs: cover three reliability fixes from PraisonAI PR #3960 #2963 warning (line 589) — public-surface list now lists _structured_completion_async, with a note that _astructured_completion was removed as dead code in PR #3991.

Single-file, text-only edits. No docs.json, docs/concepts/, or docs/sdk/reference/** changes.

PR: #2962

Job run · Branch