Building-flow mapping

Material Mapper

agents.ecoservices.material_mapper

Maps a design strategy into extracted materials, building metabolism flows, connected ecosystem services, relevant building roles, place-aware opportunity gaps, and system/role/stage lenses. It is built for early design review, educational exploration, circularity workflows, and ecosystem-service framing before a team commits to detailed engineering or procurement decisions.

POST /v1/agents/agents.ecoservices.material_mapper/invokeagents:invoke

When to use it

Good fit

Turning early building, landscape, campus, retrofit, or public-realm strategies into structured material-flow and ecosystem-service maps.
Helping design tools show how materials, water, energy, vegetation, waste, and maintenance inputs relate to ecosystem-service categories.
Building exploratory dashboards for regenerative design, architecture education, material circularity, climate adaptation, and interdisciplinary workshops.
Finding opportunity areas such as water regulation, habitat support, thermal regulation, material cycling, or soil-related services that a strategy might strengthen.
Translating design language into flow categories that downstream tools can compare, filter, visualize, or route into human review.

Use something else when

Life-cycle assessment, embodied-carbon accounting, code compliance, structural engineering, or procurement approval.
Final environmental-performance claims. The output is an interpretive map, not proof that a project provides an ecosystem service.
Replacing local ecological assessment, civil engineering, landscape architecture, construction documentation, or professional review.
Generic product material analysis when the strategy has no building, site, infrastructure, landscape, or spatial design context.
Assuming every component in a bill of materials is present. The extraction is a design-reading step, not a quantity takeoff.

Use when a workflow has a building, landscape, infrastructure, or spatial design strategy and needs to understand the material flows, ecosystem-service relationships, and design roles implied by that strategy.

Required inputs

strategy_description: Required natural-language description of the design strategy, system, intervention, retrofit, or concept to map. Include materials, assemblies, flows, site features, and design intent when known.

Optional inputs

context: Short project or place context such as building type, climate condition, program, user group, implementation stage, or constraints. This improves framing but does not replace site assessment.
biome: Optional biome or eco-region label used to compare the strategy with place-relevant ecosystem-service possibilities.
include_implied: Boolean accepted by the endpoint. Leave true for exploratory mapping where obvious secondary components should be considered; use false only when your product wants a stricter reading of the submitted text.
configuration.metadata: Caller-owned metadata for connecting the job to your project, user session, workflow step, report section, or review queue.

What comes back

The completed job result is structured for integration. Preserve citations, warnings, confidence fields, and source context when the agent returns them.

Representative output fields

job_id: Identifier used to poll GET /v1/jobs/{job_id}.
status: Job state, such as queued, running, completed, or failed.
agent_id: The invoked agent, here agents.ecoservices.material_mapper.
poll_url: Relative polling URL for the job result.
estimated_cost_usd: Preflight estimate used before the job runs. The final charge can differ.
result.strategy_description: Echoed strategy description after validation.
result.extracted_materials[]: Materials, components, assemblies, resources, or site elements identified from the submitted strategy.
result.matched_bmfs[]: Building metabolism flow matches. These are standardized flow categories for materials, water, energy, biological resources, and other inputs or outputs moving through a built system.
result.unmatched_materials[]: Extracted items that did not map cleanly to a flow category.
result.ecosystem_connections[]: Connections between matched flow categories and ecosystem-service categories.
result.ecosystem_services[]: Unique ecosystem services connected to the matched flows.
result.ecosystem_service_details: Descriptions and relationship notes for returned ecosystem services when available.
result.role_analyses[]: Relevant building or project roles and how they may touch the extracted materials.
result.place_profile: Place-aware summary built from the optional context, biome, matched flows, and connected services.
result.current_state: Directional view of matched inflows and outflows, plus connected services and coverage notes.
result.opportunity_gaps[]: Place-relevant ecosystem-service opportunities not yet supported by the current matched-flow evidence.
result.system_lenses[] / role_lenses[] / stage_lenses[]: Grouped views that help products render the same evidence by building system, role, or project stage.
result.inflow_count / outflow_count: Counts of matched inflow and outflow categories.
result.charge_usd: Customer-visible amount charged for the completed public API call when billing applies.

Result card fields

matched_bmfs[].confidence: Confidence describes the material-to-flow mapping strength. It is not a measure of environmental benefit, feasibility, or source certainty.
matched_bmfs[].flow_type: Directional category for the matched flow: inflow, outflow, or both. Use it to separate what a design draws in from what it releases, reuses, or generates.
ecosystem_connections[].relationship_type: Relationship label for how a flow is associated with an ecosystem-service category. Treat it as map structure, not a quantified effect size.
current_state.coverage_note: Short note about evidence coverage. Sparse output means the current mapped evidence is limited, not that the project has no impacts or opportunities.
opportunity_gap_status: Explains whether a biome comparison was completed, unavailable, or skipped because no biome was supplied.

How output is produced

Authenticates the API key and confirms permission to invoke agents.
Checks whether the account can start a billable mapping job before work begins.
Accepts the request as an asynchronous job and returns job_id, status, agent_id, poll_url, estimated_cost_usd, and created_at.
Validates and normalizes strategy_description, context, biome, and include_implied. Long optional context fields are capped before analysis.
Extracts explicit materials, assemblies, resources, and building or site components from the submitted strategy. In exploratory mode, it also includes clear secondary components that a design team would usually need to consider.
Compares extracted items with a curated building metabolism flow vocabulary. The vocabulary covers categories such as water, vegetation, soils, aggregates, metals, timber, plastics, energy, waste, and maintenance resources.
Deduplicates matched flow categories and classifies each one as an inflow, outflow, or both where directional evidence is available.
Connects matched flow categories to ecosystem-service categories and returns service descriptions and relationship notes when available.
Analyzes which building roles, systems, and project stages are most likely to handle, specify, maintain, or be affected by the mapped materials and flows.
Uses optional place context and biome to summarize current-state evidence and identify opportunity gaps between the returned flow-service map and place-relevant services.
Returns the completed mapping with customer-facing fields and charge_usd when the job is billable.

Trust and caution

This endpoint produces an interpretive design map. It helps users ask better questions; it does not certify performance.
Building metabolism flows are categories, not a bill of materials. They are useful for comparison, visualization, and review, but not for quantity takeoff.
Ecosystem-service connections indicate relevant relationships in the curated knowledge surface. They do not quantify how much service a specific project will provide.
Opportunity gaps are prompts for design investigation. A gap may disappear or change after local site data, engineering constraints, or expert review are added.
Vague strategies produce vague mappings. Include actual assemblies, flows, landscape elements, climate context, or design intent when your product needs useful output.
Review outputs before public environmental claims, regulatory decisions, construction decisions, procurement, or customer-facing sustainability scoring.

Runtime

Treat this endpoint as asynchronous. Many mappings complete quickly, but broad strategies with many implied components and enrichment layers can take longer. Show queued or running state and poll with backoff until the job is completed or failed.

Cost behavior

Use concise but specific strategy descriptions for predictable cost. Longer context, more extracted materials, and broad implied-component mapping can increase work. Use estimated_cost_usd for preflight display and charge_usd from the completed result for final accounting.

Billing notes

The queued response includes estimated_cost_usd as a preflight estimate.
Completed billable jobs include charge_usd in result. Treat charge_usd as the customer-visible final charge.
Cost varies with strategy length, extracted material count, breadth of matched flow categories, and the amount of role/lens enrichment performed.
Exploratory requests that include implied components can do more work than strict, concise requests.

Representative input

{
  "inputs": {
    "strategy_description": "Retrofit a public school with mass timber interior partitions, planted roof trays, rainwater-fed irrigation, and removable acoustic panels made from agricultural fiber.",
    "context": "Urban school retrofit in a humid temperate climate. The design team wants circular material choices, visible learning features, and lower stormwater load.",
    "biome": "temperate deciduous forest",
    "include_implied": true
  },
  "configuration": {
    "metadata": {
      "project_id": "school-retrofit-042",
      "workflow_step": "material-flow-map"
    }
  }
}

Queued response

{
  "job_id": "b724e32a40f6472f9b8d4ff7d1111111",
  "status": "queued",
  "agent_id": "agents.ecoservices.material_mapper",
  "poll_url": "/v1/jobs/b724e32a40f6472f9b8d4ff7d1111111",
  "estimated_cost_usd": 0.07,
  "created_at": "2026-05-27T03:05:00Z"
}

Representative completed result

{
  "job_id": "b724e32a40f6472f9b8d4ff7d1111111",
  "agent_id": "agents.ecoservices.material_mapper",
  "status": "completed",
  "created_at": "2026-05-27T03:05:00.000000+00:00",
  "started_at": "2026-05-27T03:05:01.000000+00:00",
  "completed_at": "2026-05-27T03:05:34.000000+00:00",
  "result": {
    "strategy_description": "Retrofit a public school with mass timber interior partitions, planted roof trays, rainwater-fed irrigation, and removable acoustic panels made from agricultural fiber.",
    "extracted_materials": [
      "mass timber interior partitions",
      "planted roof trays",
      "rainwater-fed irrigation",
      "agricultural fiber acoustic panels",
      "growing medium",
      "waterproof roof membrane",
      "fasteners and mounting hardware"
    ],
    "matched_bmfs": [
      {
        "bmf_name": "Timber products",
        "flow_type": "inflow",
        "confidence": "high",
        "matched_materials": ["mass timber interior partitions"],
        "reason": "Mass timber partitions are a direct timber-based construction inflow."
      },
      {
        "bmf_name": "Seeds and plants",
        "flow_type": "inflow",
        "confidence": "high",
        "matched_materials": ["planted roof trays"],
        "reason": "Planted roof trays require vegetation as a biological input."
      },
      {
        "bmf_name": "Rainwater",
        "flow_type": "both",
        "confidence": "high",
        "matched_materials": ["rainwater-fed irrigation"],
        "reason": "The strategy captures and routes rainwater for irrigation use."
      },
      {
        "bmf_name": "Biomass fiber",
        "flow_type": "inflow",
        "confidence": "medium",
        "matched_materials": ["agricultural fiber acoustic panels"],
        "reason": "Agricultural fiber panels are a biomass-derived material category."
      }
    ],
    "unmatched_materials": ["fasteners and mounting hardware"],
    "ecosystem_connections": [
      {
        "bmf_name": "Rainwater",
        "ecosystem_service": "Water regulation",
        "relationship_type": "PROVIDES_INPUT"
      },
      {
        "bmf_name": "Seeds and plants",
        "ecosystem_service": "Habitat support",
        "relationship_type": "CONTRIBUTES_TO"
      },
      {
        "bmf_name": "Biomass fiber",
        "ecosystem_service": "Material cycling",
        "relationship_type": "CONTRIBUTES_TO"
      }
    ],
    "ecosystem_services": [
      "Habitat support",
      "Material cycling",
      "Thermal regulation",
      "Water regulation"
    ],
    "ecosystem_service_details": {
      "Water regulation": {
        "name": "Water regulation",
        "description": "Processes that influence water capture, movement, storage, release, or quality.",
        "category": "regulating"
      }
    },
    "role_analyses": [
      {
        "role_name": "Architect",
        "materials_touched": ["mass timber interior partitions", "acoustic panels"],
        "description": "Coordinates interior assemblies, acoustic performance, material specification, and integration with educational goals."
      },
      {
        "role_name": "Landscape Architect",
        "materials_touched": ["planted roof trays", "rainwater-fed irrigation", "growing medium"],
        "description": "Shapes planting, roof tray layout, irrigation approach, and habitat-related opportunities."
      }
    ],
    "place_profile": {
      "biome": "temperate deciduous forest",
      "place_context": "Urban school retrofit in a humid temperate climate. The design team wants circular material choices, visible learning features, and lower stormwater load.",
      "summary": "The strategy links renewable interior materials with roof vegetation and rainwater routing, making water regulation, habitat support, and material cycling visible in the retrofit.",
      "matched_flow_count": 4,
      "current_service_count": 4,
      "potential_service_count": 6
    },
    "current_state": {
      "inflows": [
        {
          "bmf_name": "Rainwater",
          "flow_type": "both",
          "matched_materials": ["rainwater-fed irrigation"],
          "ecosystem_services": ["Water regulation"],
          "reason": "Rainwater is captured and routed into irrigation."
        },
        {
          "bmf_name": "Timber products",
          "flow_type": "inflow",
          "matched_materials": ["mass timber interior partitions"],
          "ecosystem_services": ["Material cycling"],
          "reason": "Timber enters the project as a construction material."
        }
      ],
      "outflows": [
        {
          "bmf_name": "Rainwater",
          "flow_type": "both",
          "matched_materials": ["rainwater-fed irrigation"],
          "ecosystem_services": ["Water regulation"],
          "reason": "Captured rainwater is also released through irrigation and planting systems."
        }
      ],
      "connected_ecosystem_services": [
        "Habitat support",
        "Material cycling",
        "Thermal regulation",
        "Water regulation"
      ],
      "coverage_note": "This is a current mapped view from submitted strategy text; detailed site hydrology, quantities, and maintenance assumptions are not included."
    },
    "opportunity_gap_status": "comparison_complete",
    "opportunity_gaps": [
      {
        "ecosystem_service": "Soil formation",
        "gap_kind": "missing_from_current_state",
        "rationale": "The planting strategy includes growing media, but the description does not yet explain how soil health will be supported over time."
      },
      {
        "ecosystem_service": "Pollination support",
        "gap_kind": "missing_from_current_state",
        "rationale": "The roof planting could support pollinators if species, bloom timing, and maintenance are selected for that purpose."
      }
    ],
    "system_lenses": [
      {
        "system_name": "Roof assembly",
        "endpoint_labels": ["Roof vegetation", "Irrigation"],
        "inflows": ["Rainwater", "Seeds and plants"],
        "outflows": ["Rainwater"],
        "roles": ["Landscape Architect", "Facilities Manager"],
        "stages": ["Design", "Operations"]
      }
    ],
    "role_lenses": [
      {
        "role_name": "Facilities Manager",
        "systems": ["Roof assembly"],
        "stages": ["Operations"],
        "inflows": ["Rainwater"],
        "outflows": ["Rainwater"],
        "materials_touched": ["rainwater-fed irrigation"],
        "description": "Maintains irrigation routing, roof vegetation, and inspection routines after occupancy."
      }
    ],
    "stage_lenses": [
      {
        "stage_name": "Design",
        "roles": ["Architect", "Landscape Architect"],
        "systems": ["Interior partitions", "Roof assembly"],
        "inflows": ["Timber products", "Seeds and plants"],
        "outflows": ["Rainwater"]
      }
    ],
    "inflow_count": 4,
    "outflow_count": 1,
    "charge_usd": 0.046
  }
}

Errors and retries

Common failures

401: the API key is missing or invalid.
403: the key does not have agents:invoke scope or the agent is not available to the caller.
402: the account does not have enough credits to start the job.
422: strategy_description is missing, too short, too long, or an input field has the wrong shape.
429: the client exceeded the allowed request rate.
503: the platform could not accept or complete the mapping job at that time.
failed: the accepted job could not complete, often because extraction, matching, or enrichment returned unusable output.
404: the job ID is wrong, expired, or not owned by the caller.

Retry guidance

After a job_id is returned, poll GET /v1/jobs/{job_id} with bounded exponential backoff.
Honor Retry-After on 429 responses.
Retry transient 503 responses only when no job_id was returned, and use caller-side safeguards to prevent duplicate submissions.
Do not blindly retry POST /invoke after a network timeout because the public contract does not currently include an idempotency key.
If extraction is sparse, ask the user for more concrete assemblies, resources, site conditions, or intended flows instead of repeating the same request.

Composition ideas

Design intake to review map

Collect a short design strategy from a form or assistant, invoke Material Mapper, then render materials, matched flows, connected services, and opportunity gaps for human review.

Material library enrichment

Use extracted materials and matched flow categories to tag projects, case studies, or material records with ecosystem-service context.

Workshop facilitation

Run participant concepts through the endpoint during a design workshop, then use opportunity gaps and role lenses to structure discussion.

Circularity and resource-flow dashboard

Separate inflows and outflows so users can spot reuse loops, waste streams, maintenance needs, and opportunities for local resource cycling.

Search and evidence chain

Use returned ecosystem services or flow categories as follow-up queries for source discovery, citation review, or expert analysis.

Education and curriculum

Turn student design concepts into structured maps that show how design choices relate to water, materials, energy, habitat, and ecosystem services.

Application fit

Architecture, landscape architecture, planning, and public-realm concept review.
Regenerative design tools that need a first-pass map from strategy language to material and ecological relationships.
Circular economy dashboards for comparing inflows, outflows, reuse loops, and material categories.
Design education products that help students connect building decisions with ecosystem-service thinking.
Material passport or product-library workflows that need ecosystem-service tags for early exploration.
Climate adaptation planning tools for water, heat, habitat, soil, and vegetation interventions.
AI assistants that need structured review output before writing a report, checklist, or workshop prompt.

Back to agent catalog