fix(docs): replace stale log_stream references in published docstrings

[etserend]

Summary

Fixes stale log_stream.* variable references and param documentation in published docstrings — left over from the LogStream → AgentStream rename. These are docstring-only changes; no runtime behaviour is affected.

Source: Codex review findings from agent-observability-docs PR #41. The SDK's docstrings are auto-published via .github/workflows/publish-docs.yaml / scripts/create_docs.py — the generated .mdx files in that repo must not be manually patched; the fix belongs here.

Files changed

File	Change
src/splunk_ao/agent_stream.py	Example blocks: log_stream.* → agent_stream.*
src/splunk_ao/agent_streams.py	enable_evaluators example blocks updated
src/splunk_ao/utils/singleton.py	Param docs + prose in get(), reset(), flush()
src/splunk_ao/decorator.py	Param docs in get(), flush(), reset() methods

Note: This PR covers the identifiers and param docs flagged in the initial Codex review. Remaining stale prose (shared/column.py, shared/query_result.py, evaluator.py, and broader "log stream" prose throughout published docstrings) is out of scope here and will be addressed in a follow-up.

Test plan

• No runtime code changed — existing test suite passes
• grep -r "log_stream\." src/splunk_ao/agent_stream.py returns only retrieved_log_stream.* / created_log_stream.* (internal API response variables, correct)
• After merge, trigger SDK docs publish → re-run Codex review on the new autogenerated PR in agent-observability-docs

🤖 Generated with Claude Code

[etserend]

This PR supersedes #213, which was closed when the branch was renamed to decouple it from the incorrectly linked HYBIM-941 ticket (that ticket tracks a separate, currently-blocked URL placeholder rebrand with no overlap with this change).

All three inline comments from #213 are addressed here:

• decorator.py:215 — malformed agent_stream param fixed: collapsed from inline name: description style with duplicated sentence to standard NumPy convention (name on one line, indented description on the next)
• agent_stream.py:333–342 — log_streams result variable renamed to agent_streams in all four list() example assignments; caption updated from "log streams" to "agent streams"
• agent_streams.py:65–67 — log_streams variable and "Log Stream: ..." log message in the class docstring updated to agent_streams / "Agent Stream: ..."

[fercor-cisco]

🤖 This review was generated by the Astra agent (claude-opus-5). It may contain mistakes.

Verdict: request_changes — The agent_stream.py:82 rename produces a published example that calls a method which does not exist on that class, and several docstrings the PR edited were only partially updated.

General Comments

• 🟡 minor (documentation): Partial coverage within the docstrings this PR edited. The PR fixes one sentence in a docstring but leaves an adjacent stale sentence in the same docstring, so the published output will still be internally inconsistent:

• decorator.py:1404 — short description still says "a project and log stream" while line 1407-1408 in the same docstring was updated to "agent stream".

• decorator.py:1223 — the Returns section still says "specified project and log stream" while the Parameters block directly above it was renamed.

• singleton.py:21 — the class docstring still says "the given 'project' and 'log_stream' parameters", the exact phrasing that was fixed in get() at line 168.

These are all published (scripts/create_docs.py emits class docstrings and all non-underscore methods), so the Codex re-review in the test plan will flag them again. They're cheap to include here.

• 🟡 minor (design): Scope question on the deferral. The description defers shared/column.py, shared/query_result.py, and evaluator.py to a follow-up, but those files contain the same class of defect this PR is fixing — undefined log_stream.* identifiers in published example blocks (e.g. column.py:65-70, query_result.py:66, evaluator.py:1245). project.py:61 also has a stale log_streams = project.list_agent_streams() identifier, which falls under the "identifiers" bucket this PR claims to cover.

Since the stated success criterion is "re-run Codex review on the new autogenerated PR and get a clean result", splitting mechanically-identical one-line fixes across two PRs means a second publish cycle before that criterion can be met. Is there a reason not to fold them in? If the split is deliberate to keep the diff reviewable, that's reasonable — but please open the follow-up issue before merge so it doesn't get dropped.

Follow-ups

Suggested follow-up work that could be tracked as Jira tickets:

• src/splunk_ao/shared/column.py:65-70: Stale log_stream.* identifiers in published example blocks (also lines 171, 174, 456, 476, 528, 531, 535, 539). Same defect class as this PR; acknowledged as out of scope. Note these are undefined names, so the examples are not copy-pasteable — and unlike agent_stream.py:82, the receiver here is the object-centric AgentStream, so the correct rename target is agent_stream with get_traces/trace_columns (which do exist on it).
• src/splunk_ao/shared/query_result.py:66-105: Stale log_stream.get_spans(...) / log_stream.query identifiers in published docstrings (lines 66, 81, 105, 193, 199, 246, 273).
• src/splunk_ao/evaluator.py:1244-1245: Stale # Use with log stream comment and log_stream.set_metrics([local_metric]) identifier in a published docstring.
• src/splunk_ao/project.py:57-61: Stale log_streams = project.list_agent_streams() identifier and "# Create a log stream for the project" / "# List log streams for the project" comments in the published Project class docstring. This is an identifier rather than prose, so it arguably belongs in this PR's stated scope.
• src/splunk_ao/utils/singleton.py:180-180: Unrelated stale type name from a different rename: the docstring says local_metrics (Optional[list[LocalScorerConfig]]) but the signature at line 160 is list[LocalMetricConfig] | None. LocalScorerConfig no longer exists anywhere in src/. The prose below it also still says "Local scorers".
• src/splunk_ao/decorator.py:1219-1219: get_logger_instance accepts an ingestion_hook parameter (line 1201) that is undocumented in its Parameters block. Same gap in SplunkAOLoggerSingleton.get, whose docstring omits project_id, agent_stream_id, mode, trace_id, span_id, and ingestion_hook.

[etserend]

Thanks for the detailed review, @fercor-cisco.

Fixed in this PR (pushed in the follow-up commit 00f4df2):

From the three inline comments carried over from #213:

• decorator.py:215 — malformed agent_stream param collapsed to standard NumPy convention
• agent_stream.py list() examples — log_streams variable renamed to agent_streams; caption updated
• agent_streams.py class docstring — log_streams variable and "Log Stream: ..." log message updated

From this review's partial-coverage findings:

• decorator.py:1404 — short description updated from "a project and log stream" to "a project and agent stream"
• decorator.py:1223 — Returns section updated from "specified project and log stream" to "specified project and agent stream"
• singleton.py:21 — class docstring 'log_stream' → 'agent_stream'

On the deferred files (shared/column.py, shared/query_result.py, evaluator.py, project.py): the split is deliberate to keep this diff reviewable, but the follow-up is tracked in the PR description and will be filed as a Jira ticket before merge so it doesn't get dropped.

Acknowledged as follow-ups:

• singleton.py:180 stale LocalScorerConfig type (signature uses LocalMetricConfig; prose says "Local scorers") — will file ticket
• decorator.py get_logger_instance undocumented ingestion_hook param (and the broader SplunkAOLoggerSingleton.get omissions) — will file ticket

[fercor-cisco]

duplicate lines added by botched suggestion applies

[fercor-cisco]

same problem, botched suggestion applies