Refactor: slim akd-core — Protocols, ConfigBindingMixin, drop bloat

[NISH1001]

Flattens the akd-core base class hierarchy, removes dead abstraction layers, and introduces opt-in type protocols so future framework adapters (pydantic-ai, etc.) can inherit their framework class directly and still satisfy akd's contract without paying a proxy tax.

~1200 lines deleted, ~200 added. No runtime behavior changes for existing agent/tool subclasses.

Major Changes

• Type Protocols — new AKDExecutable, AKDTool, RunContextProtocol structural contracts. Downstream framework adapters can satisfy these without inheriting BaseAgent / BaseTool. Backend code can annotate against the contract instead of the concrete class.
• ConfigBindingMixin — one mixin now owns config property binding (agent.x → agent.config.x) plus name / description / IO-hint wiring via __init_subclass__ + _bind_metadata(). Collision-aware so it plays nicely with framework classes that declare conflicting attributes.
• AbstractBaseMeta removed — schema validation moved to __init__ time (instantiation), eliminating the hardcoded class-name skip list that akd-core had to maintain for every intermediate base class (including those in downstream packages).
• MRO reorder in AbstractBase — Generic[In, Out] now comes before ABC in the bases, matching the layout used by pydantic-ai and most typing-era libraries. Unlocks multi-inheritance with framework classes.
• Dropped UnrestrictedAbstractBase — sole consumer (_DoclingMetadataExtractor) migrated to a plain utility class.
• Removed ParamExposureMixin / exposed_param — backend no longer uses runtime parameter exposure; ConfigBindingMixin covers the remaining use case.
• Folded mandatory mixins into AbstractBase — StreamingMixin + AsyncRunMixin merged in (zero standalone users). ToolCallingMixin folded into AKDAgent (its only consumer).

Minor Changes

• effective_system_prompt property on BaseAgent — explicit name for the computed prompt (config.system_prompt + description). _system_prompt kept as a backward-compat alias.
• AKDBaseAgent = BaseAgent alias for naming symmetry with framework adapters (OpenAIBaseAgent, PydanticAIBaseAgent).
• _format_schema_fields now handles union output schemas uniformly — removes the BaseAgent._output_schema_info override previously needed for that case.
• validate_input validate_output validate_schema standalone functions exported from akd._base for non-inheriting adapters.
• Docs updated — CLAUDE.md, docs/specs/AKD_BASE.md, docs/specs/TOOL_CALLING.md, docs/specs/STREAMING.md rewritten to match the new state (no more references to AbstractBaseMeta, UnrestrictedAbstractBase, ToolCallingMixin, etc.).

Bugfixes

• Granite guardian tests now skip per specific Ollama model availability instead of matching any "granite" substring. Partial model setups (e.g., only one of the required models pulled) no longer mark tests as runnable only to fail mid-call.
• Union output schemas now produce correct `OUTPUT FIELD DESCRIPTIONS` in agent descriptions.

Dead code removed

• akd/nodes/ package (zero external consumers; backend has its own copy)
• akd/agents/extraction.py (zero external consumers)
• common_types.py: ToolType, `AnyCallable(unused);CallableSpec` kept (backend still imports it)
• Dead _input_schema_info / _output_schema_info properties
• Orphaned test cases for removed features

Framework-adapter usage

Any class satisfying the shared contract works out of the box — no inheritance from akd-core required:

from akd._base import AKDExecutable, ConfigBindingMixin
import pydantic_ai

# Adapter skipping BaseAgent entirely — only inherits the framework class
class PydanticAIAgent(ConfigBindingMixin, pydantic_ai.Agent):
    input_schema = MyIn
    output_schema = MyOut
    config_schema = MyConfig

    async def arun(self, params, run_context=None, **kw): ...
    async def astream(self, params, run_context=None, **kw): ...

# Structural conformance check — no inheritance required
assert isinstance(PydanticAIAgent(...), AKDExecutable)

Test plan

• uv run pytest tests/ — 554 passed, 6 skipped (pre-existing unrelated skips only)
• akd-ext OpenAIBaseAgent verified against this branch: isinstance(agent, AKDExecutable) passes, MRO resolves cleanly, effective_system_prompt works, name/description binding works
• Protocol conformance checks pass for BaseAgent BaseTool concrete subclasses

---

Next Steps

• Remove unnecessary/unused modules like Deep search agent, code search agent. etc

[github-actions]

❌ Tests failed (exit code: 1)

📊 Test Results

• Passed: 550
• Failed: 2
• Skipped: 39
• Warnings: 178
• Coverage: 76%

Branch: refactor/akd-protocols
PR: #426
Commit: 4447cd9

📋 Full coverage report and logs are available in the workflow run.

[sanzog03]

Approving with grace