feat: capability module declare compile time type checking

[ktn1234]

Description

Improves the type safety of the capabilities system by enforcing proper input/output type structure and preventing usage of undefined capabilities. This change makes the type system more robust by adding a module augmentation pattern. now plugin developers and model developers explicitly declare the capabilities they will be consuming/producing respectively.

Related Issues

resolves #53

Core Changes

// packages/core/src/models/types.ts

/**
 * This is the base interface for all capabilities.
 * Model providers and plugins will extend ICapabilities with the input and output types
 */
export interface BaseCapability {
     input: unknown;
     output: unknown;
 }

/**
 * This is the base interface for all capabilities.
 * Model providers and plugins can extend this interface
 * to add their own capabilities.
 */
// eslint-disable-next-line @typescript-eslint/no-empty-interface
export interface ICapabilities {}

/**
 * This is how model providers and plugins can extend the ICapabilities interface
 * to add their own capabilities.
 */
declare module "../models/types" {
    interface ICapabilities {
        "text-generation": {
            input: string;
            output: string;
        };
    }
}

Changes Made

• Feature added
• Code refactored
• Documentation updated

How to Test

1. Try to use an undefined capability in a plugin:

await this.runtime.executeCapability(
  "fake-capability", // TypeScript should error: Argument of type '"fake-capability"' is not assignable to parameter of type 'keyof ICapabilities'
  "test input"
);

2. Verify that existing capabilities still work:

await this.runtime.executeCapability(
  "text-generation",
  "test input"
); // Should compile successfully

3. Try to extend capabilities without proper input/output structure:

declare module "@maiar-ai/core" {
  interface ICapabilities {
    "invalid-capability": {
      // Should error: missing input/output properties
    };
  }
}

Checklist

• Code follows project style guidelines
• Tests have been added/updated if needed
• Documentation has been updated if necessary
• Ready for review 🚀