Capability Metadata

Data structures for capability metadata

CapabilityMeta

The CapabilityMeta dataclass stores metadata about a capability, including its name, version, and runtime state.

ResourceRequirements


def ResourceRequirements(
    requires_gpu:bool=False, platforms:List=<factory>, accelerators:List=<factory>
)->None:

Binary hard-facts about what a capability needs to run (Phase 5a).

Quantitative resource amounts (min_vram_mb, etc.) deliberately omitted per CR-7’s reactive resource management reframing — capability authors can’t reliably estimate model × dtype × quantization combinatorics, and Blender- style variable-render capabilities can’t estimate at all. The substrate uses these binary hard-facts purely for discovery filtering; actual resource contention is handled reactively by CR-7’s eviction + retry flow.

  • requires_gpu: True if the capability needs any GPU; the substrate gates execution on a system monitor reporting one is present.
  • platforms: e.g., [“linux-x64”, “darwin-arm64”]. Empty list means no platform constraint declared (assume universal compatibility).
  • accelerators: e.g., [“cuda”, “mps”, “cpu”]. Informational; substrate doesn’t auto-select but consumers can filter on the values.

CapabilityMeta


def CapabilityMeta(
    name:str, version:str, description:str='', resources:Optional=None, config_schema:Optional=None,
    instance:Optional=None, enabled:bool=True, last_executed:float=0.0, config_schema_drift:bool=False,
    live_config_schema:Optional=None, structural_surface_drift:bool=False
)->None:

Metadata about a capability.

CapabilityInstance (CR-10)

CR-10 introduces multi-instance capability support: a single discovered capability can have multiple loaded instances differing by configuration. CapabilityInstance is the per-instance runtime state, keyed by instance_id in CapabilityManager._instances / CapabilityManager.instances.

The CapabilityMeta continues to hold per-capability (per-name) discovery + canonical-instance state; CapabilityInstance covers what differs across multiple loads of the same capability: the proxy, the config that initialized it, the enabled flag, last-executed timestamp, and creation time.

Naming conventions (constrained-pattern, per CR-10 Q-resolution):

  • Default: instance_id == capability_name — backward-compat for single-instance code paths.
  • Named: caller passes a constrained string ({alphanumeric, _, -}+, len ≤ 64).
  • Auto-generated: caller passes new_instance=True and the substrate produces {capability_name}-{6-char hex}.

The first instance loaded for a capability (default instance_id == capability_name) is the “canonical” instance — code reading CapabilityMeta.instance continues to see it. Multi-instance loads after the first don’t disturb that canonical reference.

CapabilityInstance


def CapabilityInstance(
    instance_id:str, capability_name:str, config:Dict=<factory>, proxy:Optional=None, enabled:bool=True,
    last_executed:float=0.0, created_at:datetime=<factory>, config_hash:str='',
    max_concurrent_requests:Optional=None
)->None:

Per-instance runtime state for a loaded capability (CR-10 multi-instance).

Differs from CapabilityMeta in scope: - CapabilityMeta is per-capability-name discovery + canonical-instance state. - CapabilityInstance is per-load-call runtime state.

A capability loaded with no instance_id (default) gets instance_id == capability_name and is the canonical instance referenced by CapabilityMeta.instance. Multi-instance loads (instance_id != capability_name) add entries to CapabilityManager.instances without changing the canonical reference.

CapabilityLoadSpec


def CapabilityLoadSpec(
    meta:Any, config:Optional=None, instance_id:Optional=None, new_instance:bool=False
)->None:

One entry in CapabilityManager.load_capabilities_concurrent’s batch input (CR-10).

Mirrors the positional arguments of load_capability so the concurrent helper can fan out load calls without repeating the per-spec instance_id / new_instance plumbing.

  • meta: the discovered CapabilityMeta to load (must have a .manifest attached).
  • config: initial configuration; falls through to persisted-or-schema-defaults when None (default-instance only; multi-instance starts fresh).
  • instance_id: explicit instance_id (validated against [A-Za-z0-9_-]{1,64}). None defaults to capability_name (single-instance backward compat).
  • new_instance: when True with instance_id=None, auto-generate {capability_name}-{6-hex}.

Example: Creating Capability Metadata

# Create capability metadata
meta = CapabilityMeta(
    name="example_capability",
    version="1.0.0",
    description="An example capability",
    config_schema={
        "type": "object",
        "properties": {
            "model": {"type": "string", "default": "base"},
            "device": {"type": "string", "enum": ["cpu", "cuda"]}
        }
    }
)

print("CapabilityMeta instance:")
print(meta)
print(f"\nName: {meta.name}")
print(f"Version: {meta.version}")
print(f"Config Schema: {meta.config_schema}")
print(f"Enabled: {meta.enabled}")
print(f"Instance: {meta.instance}")
# Test with minimal arguments
minimal_meta = CapabilityMeta(name="minimal", version="0.1.0")
print(f"Minimal CapabilityMeta: {minimal_meta}")

# Test equality
meta_copy = CapabilityMeta(name="minimal", version="0.1.0")
print(f"\nEquality test: {minimal_meta == meta_copy}")
Minimal PluginMeta: PluginMeta(name='minimal', version='0.1.0', description='', author='', package_name='', category='', interface='', config_schema=None, instance=None, enabled=True, last_executed=0.0)

Equality test: True
# Phase 5a: ResourceRequirements round-trips cleanly, and CapabilityMeta
# accepts it as an optional field (None for capabilities declaring no constraints).
res = ResourceRequirements(
    requires_gpu=True,
    platforms=["linux-x64", "darwin-arm64"],
    accelerators=["cuda", "mps"],
)
assert res.requires_gpu is True
assert "linux-x64" in res.platforms

# ResourceRequirements defaults: no GPU, empty platforms (universal), empty accelerators.
default_res = ResourceRequirements()
assert default_res.requires_gpu is False
assert default_res.platforms == []
assert default_res.accelerators == []

# CapabilityMeta accepts resources; defaults to None when unconstrained.
typed_meta = CapabilityMeta(
    name="whisper-local",
    version="1.0.0",
    description="Local Whisper-based STT",
    resources=res,
)
assert typed_meta.resources.requires_gpu is True

legacy_meta = CapabilityMeta(name="legacy", version="0.0.1")
assert legacy_meta.resources is None

print("✓ ResourceRequirements + CapabilityMeta integration")