docs(HYBIM-840): add galileo → splunk-ao migration guide

[adityamehra]

Summary

• Adds docs/MIGRATION_GUIDE.md — a comprehensive customer-facing migration guide for moving Python applications from the Galileo SDK (galileo) to Splunk Agent Observability (splunk-ao)
• Documents all breaking changes consolidated from the HYBIM-697 epic work already landed in main
• Covers install options (GitHub install + local clone) since splunk-ao is not yet on PyPI

Changes

New file: docs/MIGRATION_GUIDE.md

Sections:

1. Dependency changes — GitHub install (Option A) and local editable install (Option B); extras; Python 3.11 floor; Protect legacy note
2. Import path changes — from galileo import … → from splunk_ao import …
3. Class & symbol renames — 10 public renames (Logger, Decorator, context, exceptions, metrics, handlers, ADK, satellite packages)
4. Environment variable changes — 19 GALILEO_* → SPLUNK_AO_* renames with bridge explanation
5. Removed features — Protect API, GalileoScorers
6. HTTP tracing headers — X-Galileo-* → Splunk-AO-*
7. Full before/after code example
8. Jira tickets covered (HYBIM-713, 716, 717, 718, 719, 725, 727, 728, 800, 804, 807, 823)
9. What you do NOT need to change — galileo_core imports, @log, TracingMiddleware, on-disk config, default URLs
10. Migration checklist — 20-item actionable checklist

Jira

HYBIM-840

Test plan

• Review docs/MIGRATION_GUIDE.md for accuracy against current main
• Verify all class renames match src/splunk_ao/__init__.py exports
• Verify all env var renames match src/splunk_ao/config.py bridge table
• Verify GitHub install command works: pip install "splunk-ao @ git+https://github.com/splunk/splunk-ao-python.git"

Made with Cursor

[fercor-cisco]

@adityamehra I used Claude to review this PR. I won't have time right now to double-check the results for correctness, but I wanted to go ahead and share them with you:

Analysis of docs/MIGRATION_GUIDE.md

Reviewed: commit dad821f on branch docs/HYBIM-840-migration-guide
Method: Every factual claim in the guide was checked against the actual source of ~/projects/splunk-ao-python (current repo) and ~/projects/galileo-python (the fork origin), plus git history/CHANGELOG in both repos.

Verdict

The guide is highly accurate. Every rename table, import-path table, env-var table, and removed-feature claim was verified against real source code and matches exactly. No fabricated symbols, no wrong tickets tied to nonexistent commits (bar one soft mismatch, see below). The two real defects are: a broken code example (§7) and an overstated/incomplete claim about the env-var bridge (§4). There are also a few completeness gaps worth adding.

---

Bugs (should fix before merge)

1. The "Complete Before/After Code Example" (§7) does not run — TypeError on both sides

Lines 384-387 and 411-414 call:

logger.start_session(project="my-project")
...
logger.conclude(flush=True)

Actual signatures (identical in both galileo and splunk_ao, so this is not a migration-induced regression, it's a bug in the guide's own example):

• SplunkAOLogger.start_session(name=None, previous_session_id=None, external_id=None, metadata=None) — src/splunk_ao/logger/logger.py:2343. There is no project kwarg.
• SplunkAOLogger.conclude(output=None, redacted_output=None, duration_ns=None, status_code=None, conclude_all=False) — src/splunk_ao/logger/logger.py:1880. There is no flush kwarg.

Both the "Before" and "After" blocks reuse this same invalid pattern, so a customer copy-pasting either snippet gets an exception immediately. Fix by removing project=/flush=True or replacing with a working example (e.g. set project via SplunkAOLogger(project=..., log_stream=...) at construction, or via splunk_ao_context; flush via logger.flush() / context-manager exit).

2. §4's "Internal bridge" claim is overstated — only 13 of 22 vars are actually bridged

Guide text (line 263): "The SDK automatically propagates SPLUNK_AO_* values to their GALILEO_* equivalents at startup... This bridge is transparent to SDK consumers and does not require any action."

SplunkAOConfig._bridge_env_vars() (src/splunk_ao/config.py:35-62) only bridges these 13 (auth/identity) pairs:
API_KEY, API_URL, CONSOLE_URL, PROJECT, PROJECT_ID, LOG_STREAM, LOG_STREAM_ID, JWT_TOKEN, SSO_ID_TOKEN, SSO_PROVIDER, USERNAME, PASSWORD, MODE.

The remaining 9 vars the guide lists in its env-var table (LOG_LEVEL, LOGGING_DISABLED, INGEST_BETA_DISABLED, DEFAULT_SCORER_MODEL, DEFAULT_SCORER_JUDGES, and the 4 CODE_VALIDATION_* vars) are not bridged — they're consumed directly by splunk_ao code (configuration.py:98-152, logger/logger.py:402, utils/decorators/telemetry_toggle.py:26) and have no GALILEO_* counterpart read anywhere. That's fine in practice (no bridge is needed for them), but the guide's blanket "propagates SPLUNK_AO_* values to their GALILEO_* equivalents" reads as if it applies to the whole table right above it. Recommend scoping the sentence to "the auth/identity-related variables" or listing which 13 are bridged.

3. Env-var table is missing SPLUNK_AO_API_URL as a new variable, not a rename

SPLUNK_AO_API_URL exists in splunk_ao (bridged to GALILEO_API_URL at config.py:47), but galileo-python has no GALILEO_API_URL env var anywhere in its source — it's not a real user-facing var upstream (confirmed by the feat(config) commit 5e4440d's own message: "GALILEO_API_URL is a real pydantic env var on GalileoConfig... The previous PR review incorrectly removed it under the assumption it was internal-only"). So for a customer migrating from galileo, there is nothing to rename — SPLUNK_AO_API_URL is a new capability, not present in the old SDK's public surface. The guide's §4 table implies a 1:1 rename for every row; this one row should be called out separately as "new."

---

Minor / cosmetic issues

4. Ticket attribution mismatch: HYBIM-729 vs HYBIM-804

Guide's §4 (line 298) and §8 table (line 432) cite HYBIM-729 for "Rename GALILEO_HEADER_PREFIX (separate ticket)". No commit in git log --all references HYBIM-729. The actual header-rename commit is ff9c72a "HYBIM-804 Renaming galileo headers to splunk-ao (#45)", which is already correctly cited elsewhere in the guide (§6, §8 line 438) for the same change. HYBIM-729 may be a real but not-yet-merged/separately-tracked ticket, or a copy-paste mistake — worth double-checking with the ticket tracker before merge.

5. README.md still advertises pip install splunk-ao without the GitHub-URL caveat

README.md:23 says pip install splunk-ao — this doesn't match the migration guide's §1.1 framing that the package isn't yet on PyPI and must be installed via git+https://.... Not a guide error per se, but the guide and the README now disagree; worth reconciling (either the README needs the GitHub-install caveat too, or this is a sign PyPI publication is imminent and the guide should say so).

---

Completeness gaps (not incorrect, just not mentioned)

6. DatasetRecord.generated_output / ground_truth naming (CHANGELOG "Unreleased" section)

CHANGELOG.md (identical in both repos — inherited from the fork, not yet updated for the rebrand) documents two real, already-implemented changes not mentioned anywhere in the migration guide:

• New generated_output field on DatasetRecord (src/splunk_ao/schema/datasets.py:50).
• ground_truth as an alternate name for output on DatasetRecord, both normalized internally.

These are additive/feature changes rather than renames, so they're arguably out of scope for a rename-focused migration guide — but since the guide claims to document "every breaking change," and a customer diffing DatasetRecord usage might notice the new field, a one-line mention (or explicit note that it's out of scope) would tighten completeness.

7. No CLI entry points / scripts in either package

Checked for [project.scripts] / [tool.poetry.scripts] in both pyproject.toml files — neither repo defines any, so there's nothing to add to the guide here. (Confirms the guide isn't missing a CLI-rename section.)

8. No deprecation warnings reference galileo in splunk_ao source

Grepped for warnings.warn calls in src/splunk_ao/ mentioning "galileo" — none found. So there's no runtime deprecation-warning UX guiding users through the migration; the guide is effectively the only migration aid. (Not a defect, just confirms the guide's importance — no need to add anything here.)

---

Everything independently confirmed correct

The following were spot-checked directly against source in both repos and all match the guide exactly, with no discrepancies:

• Package/install: name = "splunk-ao" (pyproject.toml:2), repo URL github.com/splunk/splunk-ao-python (pyproject.toml + git remote), no PyPI publish workflow yet.
• Extras unchanged: langchain, openai, crewai, middleware, otel, all — identical between repos.
• New grpcio>=1.80.0,<2.0.0 added only to otel/all extras in splunk-ao-python, absent in galileo-python.
• Python floor 3.10 → 3.11: requires-python confirmed in both pyproject.tomls.
• Protect feature removal: galileo-python/src/galileo/__init__.py exports all 12 named Protect symbols (from protect.py, stages.py, galileo_core.schemas.protect); splunk_ao has zero references to any of them (only unrelated autogenerated REST-client leftovers under resources/models/protect_*.py).
• GalileoScorers removal: confirmed removed in commit d2ad301 "Removing GalileoScorers (#39)"; SplunkAOMetrics retains the same enum members (e.g. completeness = "Completeness").
• All 22 GALILEO_* → SPLUNK_AO_* env vars: 1:1 rename confirmed by grepping configuration.py, config.py, logger.py, telemetry_toggle.py in both repos.
• Config file name unchanged: galileo-python-config.json literal in both config.py:15 files.
• Default URLs unchanged: https://api.galileo.ai/ / https://app.galileo.ai/ in splunk_ao/constants/__init__.py:7-8.
• All class/symbol renames (§3.1–3.7): every single pair — GalileoLogger/SplunkAOLogger, GalileoDecorator/SplunkAODecorator, galileo_context/splunk_ao_context, all 3 exception classes, GalileoMetric(s)/SplunkAOMetric(s), all 11 handler/middleware classes, convert_to_galileo_message/convert_to_splunk_ao_message, setup_agent_control_bridge (name genuinely unchanged, only its param/return types renamed — guide correctly implies this), GalileoPythonConfig/SplunkAOConfig, Configuration.galileo_api_key/splunk_ao_api_key, the ADK plugin/callback/retriever trio, and both satellite package renames (galileo-a2a→splunk-ao-a2a, galileo-adk→splunk-ao-adk) — verified with matching file:line locations in both repos.
• All 10 sub-module import paths (§2.2): every listed module exists at the matching path in src/splunk_ao/.
• HTTP tracing headers (§6): X-Galileo-Trace-ID/X-Galileo-Parent-ID → Splunk-AO-Trace-ID/Splunk-AO-Parent-ID, exact casing confirmed in constants/tracing.py and asserted in both repos' test_logger_distributed.py; get_tracing_headers() returns the new names.
• Jira tickets (§8): every ticket ID (except the HYBIM-729 mismatch above) traces to a real, matching commit — HYBIM-790 (03d4cc3), HYBIM-793 (9fe5710), HYBIM-796 (5e95b7a), HYBIM-777 (e121f41), HYBIM-800 (b88b1d6, d2ad301), HYBIM-804 (ff9c72a), HYBIM-807 (33949d8), HYBIM-823/822/725/etc. all confirmed.
• §9 "unchanged" list: galileo_core imports, @log decorator, extras names, TracingMiddleware, OPENAI_API_KEY, config filename, default URLs — all independently confirmed unchanged.

---

Recommendations, ranked

1. Fix the broken code example (§7) — highest priority, this is the one piece of code a customer would actually copy-paste, and it throws TypeError as written.
2. Scope the "internal bridge" claim (§4) to the 13 vars actually bridged, or note that logging/scorer/validation vars are consumed natively and don't need bridging.
3. Flag SPLUNK_AO_API_URL as new, not a rename, in the env-var table.
4. Verify HYBIM-729 against the ticket tracker — likely should just cite HYBIM-804 consistently.
5. (Optional, low priority) Add a one-line pointer to the DatasetRecord.generated_output/ground_truth change, or an explicit note that additive feature changes are out of scope for this guide.