Skip to content

Affordance Kb

Affordance Knowledge Base component.

Cluster: Knowledge & Grounding | Type: component | MCP Tools: 14

Overview

Affordance KB is a small simulation/demo knowledge base for object affordance examples. It ships with 20 seed objects and stores material properties, mass, fragility, grip force ranges, affordances, constraints, and optional interaction history. It is useful for workflow demos, simulation planning, and tests where an agent needs structured facts about common objects without calling an external service. It is not a full production adapter and is not production robotics control.

The block supports 12 operations: lookup, add_entry, update_entry, remove_entry, list_entries, search_by_affordance, search_by_material, get_grip_params, get_constraints, record_interaction, get_interaction_stats, and reset.

Reliability and simulation hardening:

  • Plain object names are normalized, so "Glass Cup", "glass-cup", and "glass_cup" resolve to the same seed entry.
  • fragility and surface_friction are clamped to [0.0, 1.0]; mass_kg, force_used, and grip forces are clamped to non-negative values.
  • Affordance and material search accept case-insensitive partial terms such as "pour" or "glass".
  • Interaction history is accepted only for known objects with a non-empty action and outcome.
  • Grip output includes recommended_force and narrows force ranges from successful simulated interactions rather than expanding them.
  • Optional SQLite persistence is available through db_path; without it, state is local to the block instance.
  • Resolver fallback, missing optional LLM capability, and persistence failures are surfaced through top-level degraded, degradation_reason, completion_state, warning_card, and evidence fields. Resolver fallback uses completion_state="qualified-draft".
  • The MCP wrapper exists and exposes read/inspection operations plus constrained source operations: source_capabilities, source_op_schema, source_dry_run, and source_call.
  • Source operations are allowlisted and auditable; they do not expose arbitrary SQL, raw prompts, native execution, or production control-like behavior.

When to use:

  • Looking up example object properties during a simulated manipulation workflow
  • Filtering objects by material or affordance during task planning
  • Recording simulated interaction outcomes so later grip suggestions can reflect local history
  • Demonstrating G6's grounding pattern with a deterministic, no-network component
  • Discovering simulation-only source capabilities without treating the component as a production adapter

Example:

from mvp.affordance_kb import AffordanceKBBlock, AffordanceKBInput

block = AffordanceKBBlock(name="kb")

result = block.infer(AffordanceKBInput(op="lookup", object_class="Glass Cup"))
# result.value.entry["object_class"] == "glass_cup"

search = block.infer(AffordanceKBInput(op="search_by_affordance", query="pour"))
# search.value.entries includes glass_cup, plastic_bottle, and glass_bottle.

grip = block.infer(AffordanceKBInput(op="get_grip_params", object_class="egg"))
# grip.value.grip_params includes min_force, max_force, mode, and recommended_force.

Works well with: context_engine, adapt_physical_ai, adapt_synthetic_world

Public API

AffordanceKBBlock(AIBlock[AffordanceKBInput, AffordanceKBOutput, dict])

Affordance knowledge base block with 12 operations.

Field Type Default
name str 'affordance_kb'
state dict field(default_factory=dict)
db_path str ''
resource_bounds ResourceBounds field(default_factory=ResourceBounds)
usage ResourceUsage field(default_factory=ResourceUsage)

Methods:

infer(data: AffordanceKBInput) -> Result[AffordanceKBOutput]

close() -> None

ObjectResolutionDecision

Outcome of resolving a free-text object reference to a known KB key.

Field Type Default
object_class str ''
rationale str ''
signals list[str] field(default_factory=list)
confidence float 0.0
completion_state str 'qualified-draft'
degraded bool False
raw_response str ''

AffordanceKbPlanner

Runtime-first object-resolution facade with a real deterministic fallback.

Constructor:

Parameter Type Default
runtime AffordanceKbRuntime \| None None

Methods:

resolve_object_class(query: str, known_keys: frozenset[str]) -> ObjectResolutionDecision

AffordanceEntry

A single object affordance entry.

Field Type Default
object_class str ''
material str ''
mass_kg float 0.0
fragility float 0.0
grip_force_range tuple[float, ...] ()
surface_friction float 0.5
deformable bool False
temperature_sensitive bool False
affordances tuple[str, ...] ()
constraints tuple[str, ...] ()
provenance Provenance 'demo_seed'

Methods:

to_dict() -> dict

Convert entry to a plain dictionary.

AffordanceKBInput(BaseModel)

Input schema for affordance knowledge base operations.

Field Type Default
op AffordanceOp 'lookup'
object_class str ''
material str ''
mass_kg float 0.0
fragility float 0.0
grip_force_range list[float] Field(default_factory=list)
surface_friction float 0.5
deformable bool False
temperature_sensitive bool False
affordances list[str] Field(default_factory=list)
constraints list[str] Field(default_factory=list)
action str ''
outcome str ''
force_used float 0.0
query str ''
metadata dict Field(default_factory=dict)

AffordanceKBOutput(BaseModel)

Output schema for affordance knowledge base operations.

Field Type Default
op str required
entry dict Field(default_factory=dict)
entries list[dict] Field(default_factory=list)
grip_params dict Field(default_factory=dict)
constraints list[str] Field(default_factory=list)
interaction_stats dict Field(default_factory=dict)
found bool False
count int 0
metadata dict Field(default_factory=dict)
degraded bool False
degradation_reason str ''
completion_state Literal['verified', 'qualified-draft', 'blocked-escalated'] 'qualified-draft'
warning_card dict Field(default_factory=dict)
evidence dict Field(default_factory=dict)
request_id str ''
task_id str ''
run_id str ''
agentic_evidence dict \| None None
simulation_only Literal[True] True
review_pending Literal[True] True

AffordanceKbMCPBlock(AIBlock[AffordanceKbMCPInput, AffordanceKbMCPOutput, dict])

Dispatcher for 9 operations.

Field Type Default
name str 'affordance_kb_mcp'
resource_bounds ResourceBounds \| None None
usage ResourceUsage field(default_factory=ResourceUsage)

Methods:

infer(data: AffordanceKbMCPInput) -> Result[AffordanceKbMCPOutput]

Functions

agentic_planner_enabled(default_enabled: bool) -> bool

Decide whether the agentic affordance_kb planner should be used.

MCP Tools

Operation Source
ops affordance_kb_mcp
help affordance_kb_mcp
lookup affordance_kb_mcp
inspect_resolution affordance_kb_mcp
get_constraints affordance_kb_mcp
list_strategies affordance_kb_mcp
list_patterns affordance_kb_mcp
source_capabilities affordance_kb_mcp
source_op_schema affordance_kb_mcp
source_dry_run affordance_kb_mcp
source_call affordance_kb_mcp
verified affordance_kb_mcp
qualified-draft affordance_kb_mcp
blocked-escalated affordance_kb_mcp

Seed Objects

glass_cup, steel_beam, rubber_ball, wooden_block, ceramic_plate, plastic_bottle, egg, sponge, metal_can, paper_sheet, concrete_block, fabric_cloth, lightbulb, foam_cup, knife, banana, screwdriver, glass_bottle, cardboard_box, silicon_wafer

Grip Output

get_grip_params returns:

Key Meaning
k Stiffness-like coefficient derived from fragility
c Damping-like coefficient derived from fragility
mode soft, adaptive, or rigid
min_force Lower force bound in Newtons
max_force Upper force bound in Newtons
recommended_force min + (max - min) * (1 - fragility) * 0.5