Feature/annotation exposed params

[NISH1001]

Summary 📝

This PR implements a comprehensive Parameter Exposure System, providing a unified interface for agents and tools to expose their internal parameters for external configuration, introspection, and UI integration. It replaces the previous exposure logic with a modular package that supports three complementary strategies: Decorators, Type Annotations, and a new Pipe Operator syntax.

For full documentation refer to docs/specs/AKD_EXPOSURE_SYSTEM.md.

Details

Refactoring & Core Logic

1. Modular Structure: Replaced akd/_base/exposure.py with a modular package akd/_base/exposure/ containing core logic, structures, and utilities.
2. ParamExposureMixin: Implemented the central mixin that handles parameter discovery, registry management, and runtime scanning.
3. Recursive Access: Added rgetattr and rsetattr utilities to akd/utils.py to enable dot-notation access for nested configurations (e.g., agent["component.config.temp"]).

Exposure Strategies

1. Decorator Support: Implemented @exposed_param with ValidatedProperty to enforce type safety on setters automatically.
2. Annotation Support: Added support for Annotated[T, Exposed()] to automatically create properties for nested config schema fields at class creation time.
3. Pipe Operator: Introduced value | Exposed() syntax for dynamic parameter exposure within __init__, enabling support for runtime components where annotations are erased.

Documentation & Testing

1. Specification: Added full documentation in docs/specs/AKD_EXPOSURE_SYSTEM.md.
2. Tests: Added comprehensive tests covering all three strategies, nested components, and mixed usage scenarios.

---

Usage Section

This system allows you to expose parameters using three complementary methods. You can mix and match these strategies within the same agent.

1. Annotated (Static/Schema Level)

Best for: Config schemas, DataClasses, and static settings.
Use standard Python Annotated type hints. The system automatically creates accessors (getters/setters) for these fields, even if they are nested deep in a config object.

from typing import Annotated
from akd._base.exposure import Exposed
from akd.agents import BaseAgentConfig

class ResearchConfig(BaseAgentConfig):
    # Declarative, visible in class definition
    temperature: Annotated[float, Exposed(description="LLM Sampling Temperature")] = 0.7
    model_name: Annotated[str, Exposed(description="Model Identifier")] = "gpt-4"

2. Pipe Operator (Runtime/Init Level)

Best for: Dynamic components, calculated values, or objects created in __init__.
Since Python erases variable annotations at runtime, we use the | operator to attach metadata to values directly.

We use this mechanism because python doesn't attach type/annotation information at runtime. (I had experimented with other processes like parsing ast, but this seems to be more interpretable)

class ToolComponent:
    def __init__(self):
        # "Pipes" metadata into the value at runtime
        self.rate_limit = 5.0 | Exposed(description="API calls per second")
        self.is_enabled = True | Exposed(description="Toggle tool usage")

3. Decorator (Logic Level)

Best for: Computed properties, read-only status, or parameters requiring custom validation logic.
Use @exposed_param on standard property methods.

from akd._base import exposed_param

class MyAgent(ParamExposureMixin):
    def __init__(self):
        self._max_steps = 10

    @exposed_param(description="Maximum steps before termination", min=1, max=50)
    def max_steps(self) -> int:
        return self._max_steps

    @max_steps.setter
    def max_steps(self, value: int):
        if value < 1:
            raise ValueError("Steps must be positive")
        self._max_steps = value

---

Full Example: Putting it all together

Here is a complete agent definition showing how all three methods integrate seamlessly.

from typing import Annotated
from akd._base import exposed_param, Exposed
from akd.agents._base import LiteLLMInstructorBaseAgent, BaseAgentConfig

# 1. Annotated Strategy (Config)
class AgentConfig(BaseAgentConfig):
    temperature: Annotated[float, Exposed(description="LLM temperature")] = 0.7

class ResearchAgent(LiteLLMInstructorBaseAgent):
    config_schema = AgentConfig

    def __init__(self, config=None):
        super().__init__(config)
        
        # 2. Pipe Strategy (Runtime)
        self.rate_limiter = 5.0 | Exposed(description="API Rate Limit")
        self._status = "idle"

    # 3. Decorator Strategy (Custom Logic)
    @exposed_param(description="Current agent status (Read-Only)")
    def status(self) -> str:
        return self._status

Accessing & Introspection

External systems (UI/API) can interact with these parameters uniformly:

agent = ResearchAgent()

# 1. Introspection (Get all params + metadata)
# Returns list of ExposedParamRuntimeInfo objects
params = agent.get_exposed_params(include_values=True, scan_runtime=True)

# 2. Unified Dict-Like Access (Dot notation works for nested configs!)
agent["config.temperature"] = 0.9      # Modifies Annotated config
agent["rate_limiter"] = 10.0           # Modifies Pipe value
# agent["status"] = "busy"             # Raises Error (Read-Only decorator)

# 3. Safe Access
val = agent.get("config.temperature", default=0.5)

---

Checks

• Tested Changes
• Stakeholder Approval

[github-actions]

❌ Tests failed (exit code: 1)

📊 Test Results

• Passed: 609
• Failed: 5
• Skipped: 7
• Warnings: 239
• Coverage: 81%

Branch: feature/annotation-exposed-params
PR: #288
Commit: e55670a

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

[github-actions]

❌ Tests failed (exit code: 1)

📊 Test Results

• Passed: 609
• Failed: 5
• Skipped: 7
• Warnings: 239
• Coverage: 81%

Branch: feature/annotation-exposed-params
PR: #288
Commit: b8d15be

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

[github-actions]

❌ Tests failed (exit code: 1)

📊 Test Results

• Passed: 609
• Failed: 5
• Skipped: 7
• Warnings: 238
• Coverage: 81%

Branch: feature/annotation-exposed-params
PR: #288
Commit: 2b4464c

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

[github-actions]

❌ Tests failed (exit code: 1)

📊 Test Results

• Passed: 609
• Failed: 5
• Skipped: 7
• Warnings: 236
• Coverage: 81%

Branch: feature/annotation-exposed-params
PR: #288
Commit: d03736e

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

[github-actions]

❌ Tests failed (exit code: 1)

📊 Test Results

• Passed: 608
• Failed: 6
• Skipped: 7
• Warnings: 238
• Coverage: 81%

Branch: feature/annotation-exposed-params
PR: #288
Commit: 0457226

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

[github-actions]

❌ Tests failed (exit code: 1)

📊 Test Results

• Passed: 609
• Failed: 5
• Skipped: 7
• Warnings: 239
• Coverage: 81%

Branch: feature/annotation-exposed-params
PR: #288
Commit: ecbf13e

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

[github-actions]

❌ Tests failed (exit code: 1)

📊 Test Results

• Passed: 609
• Failed: 5
• Skipped: 7
• Warnings: 239
• Coverage: 81%

Branch: feature/annotation-exposed-params
PR: #288
Commit: 6bc4014

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

[github-actions]

❌ Tests failed (exit code: 1)

📊 Test Results

• Passed: 609
• Failed: 5
• Skipped: 7
• Warnings: 237
• Coverage: 81%

Branch: feature/annotation-exposed-params
PR: #288
Commit: cc3c219

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