Sprint 23a.5 (akiva-ai-framework) — Migration to akiva 0.2.0

[adii2025]

Sprint 23a.5 (akiva-ai-framework) — Migration to akiva 0.2.0

What changed

The akiva-ai-framework repository's Python namespace renamed from
akiva_ai to akiva and the single-wheel monolith split into 4 wheels
(akiva-core, akiva-runner, akiva-memory, meta-wheel akiva) at
version 0.2.0. This is a breaking change for this consumer repo.

Per workspace CLAUDE.md cross-system correction (feedback_optional_cross_repo_imports),
this repo depends on the framework via optional cross-repo try/except ImportError guards with _HAS_FRAMEWORK flag. The migration window is
roughly the same regardless: every from akiva_ai.X import Y must become
from akiva.X import Y to keep _HAS_FRAMEWORK = True once the consumer
upgrades.

Estimated effort for this repo: ~0.5-1 day (per spec v3.1 Component 4).

Action items

1. Pin akiva>=0.2.0 (or akiva-core>=0.2.0 for slim consumers) in your
   requirements.txt / pyproject.toml. Drop the old akiva-ai pin.
2. Run the libcst-based import rewrite. Vendor the transformer from
   akiva-ai-framework/scripts/_rename/rename_imports.py:

   python scripts/rename_imports.py --apply src/  # adapt path to repo

3. Watch for these 2 deprecated re-exports (each emits DeprecationWarning):
   • from akiva.guardrails import PolicyEngineGuardrail (will remove in
     akiva-ai-framework Sprint 23a.12; ~10-12 weeks runway). Update to
     from akiva.policy.guardrail import PolicyEngineGuardrail.
   • from akiva.llm_providers import LLMMessage, LLMResponse, LLMTool, LLMConfig, LLMProvider
     (will remove in Sprint 23a.6; ~1-2 weeks runway). Update to
     from akiva.core.llm_protocols import LLMMessage, LLMResponse, LLMTool, LLMConfig, LLMProvider.
4. NOTE: the new akiva.core.llm_protocols.LLMClientProtocol is NOT
   re-exported from akiva.llm_providers — it is exclusively at
   akiva.core.llm_protocols. New consumer code that types LLM-access
   against the structural Protocol must depend on akiva-core directly.
5. NOTE: akiva.plugins.load_tool_plugins(group="akiva_ai.tools") retains
   the old entry-point group as default for back-compat. New tool plugins
   should register under akiva.tools.
6. Run your test suite. Verify no akiva_ai references remain in active
   imports (docstring/comment references can stay; libcst rename only
   touches AST imports).
7. Reply to this issue with your migration owner + planned completion date.

Suggested deadline: within 30 days of issue creation.

Reference

• Spec: akiva-ai-framework/docs/superpowers/specs/2026-04-27-sprint-23a5-substrate-and-pilot-design.md (v3.1 SHIPPED 2026-04-27)
• Migration guide: akiva-ai-framework/docs/MIGRATION_0.2.md
• Decomposition roadmap: akiva-ai-framework/docs/DECOMPOSITION_ROADMAP.md
• libcst transformer (vendor source): akiva-ai-framework/scripts/_rename/rename_imports.py
• Sprint 23a.5 closeout: akiva-ai-framework/docs/sprints/23a5_FINAL_ACCEPTANCE.md