Research synthesis

Strategy Distiller Agent

agents.biomimicry.strategy_distiller

Compresses a larger set of submitted biomimicry strategy records into a smaller, reviewable set of biology-language strategy families. It preserves source_strategy_ids, organisms, citations, and mechanism nuance so downstream builders can move from synthesis back to the source records.

POST /v1/agents/agents.biomimicry.strategy_distiller/invokeagents:invoke

When to use it

Good fit

  • Compressing many biological strategy records into a reviewable set for reports, classrooms, workshops, dashboards, or ideation.
  • Preserving biological mechanism detail before translating findings into design principles.
  • Keeping source_strategy_ids and citations attached to each distilled strategy.
  • Comparing source coverage with input_count, output_count, requested_target_count, represented_source_count, coverage_percentage, warnings, and summary.
  • Building workflows that already have retrieved or curated source evidence and now need synthesis, clustering, and compression.

Use something else when

  • Search or evidence retrieval. This endpoint works from the strategies you submit.
  • The only validation layer for high-stakes scientific, legal, medical, financial, safety, or regulatory claims.
  • Workflows where every source record must remain separate. Distillation intentionally merges overlapping strategies.
  • Treating target_count as a hard guarantee. Compare requested_target_count and output_count in the completed result.
  • Strict round-by-round audit workflows unless your application also stores its own run state and source selections.

Use after search, upload, or curation has produced source strategy records and the workflow needs a smaller review set without losing source links, citations, organisms, or mechanism nuance.

Required inputs

strategies
Array of source strategy records to synthesize.
design_challenge
Design or research challenge that gives the synthesis context.

Optional inputs

target_count
Requested number of distilled strategies, from 1 to 50. Default is 10. This is a target, not a hard guarantee.
preserve_nuance
Boolean. Default is true. Use true when biological specificity matters; false requests a more concise synthesis while staying grounded in submitted sources.
session_id
Optional workflow identifier that helps clients connect this run to their own records.
distillation_round
Optional integer round marker, usually 1 or 2.
function_source
Optional function label to carry into round-one outputs.
configuration.metadata
Caller-owned metadata for connecting the job to a workflow, review queue, dashboard, or webhook receiver.

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.biomimicry.strategy_distiller.
poll_url
Relative polling URL for the job result.
estimated_cost_usd
Pre-run estimate visible before execution. The final billed amount can differ.
created_at / completed_at
Job lifecycle timestamps when available.
result.distilled_strategies
Array of distilled strategy objects.
result.input_count
Number of submitted strategies processed.
result.output_count
Number of distilled strategies returned.
result.coverage_percentage
Percentage of submitted source strategies represented by returned source_strategy_ids.
result.requested_target_count
The target_count requested by the caller.
result.represented_source_count
Number of unique submitted source strategies represented in the result.
result.summary
Short summary of the distillation result.
result.warnings
Non-fatal parser and quality notes, such as target-count mismatch or dropped invalid source references.
result.citations / citation_count
Aggregate citation summary and count from submitted source records.
result.status / error
Agent-level completion or public error message when present.
result.charge_usd
Customer-visible charge attached after a billable completed run.

Distilled strategy fields

id
Stable identifier for the distilled strategy.
name
Short human-readable strategy name.
function
Function achieved by the distilled strategy.
combined_mechanism
Mechanism synthesis in biological language.
biological_nuance
Caveats, constraints, and biological details that should not be flattened.
organisms
Organisms or living systems represented in source records.
source_strategy_ids
Submitted source strategy ids represented by this distilled strategy.
source_count
Number of source strategies contributing to this distilled strategy.
parent_distilled_ids
Prior distilled strategy ids when multi-round workflows use them.
distillation_round
Round marker carried into the output.
original_strategy_ids
Original source strategy ids preserved through multi-round workflows.
function_source
Function label carried into round-one outputs when supplied.
abstraction_level
One of principle, pattern, or mechanism.
confidence
0 to 10 synthesis confidence signal. Treat it as a review aid, not calibrated certainty.
related_distilled_ids
Other distilled strategies related to this one.
citations / citation_count
Per-strategy citations projected from submitted source records.

How output is produced

  • Authenticates the API key and confirms permission to invoke agents.
  • Checks whether the account can start a billable synthesis 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.
  • Normalizes accepted strategy records into a common shape for synthesis.
  • Compares functions, mechanisms, organisms, and source relationships across submitted records.
  • Merges overlapping strategies into biology-language strategy families while leaving distinctive outliers separate when merging would hide an important mechanism.
  • Checks source references against submitted source_strategy_ids so returned strategies point back to records the caller provided.
  • Attaches citation-friendly details from submitted strategies when available.
  • Returns compression and review signals such as input_count, output_count, requested_target_count, represented_source_count, coverage_percentage, summary, and warnings.

Trust and caution

  • This endpoint synthesizes the strategies you provide. It does not retrieve or verify new evidence.
  • Do not present distilled output as a new source. Present it as derived synthesis of submitted source records.
  • coverage_percentage reports representation of submitted source_strategy_ids, not scientific certainty.
  • confidence is a review signal from the synthesis process and should not be treated as calibrated probability.
  • Citations are only as complete as the citation metadata in your source strategy records.
  • High compression can hide minority mechanisms. Increase target_count or review warnings when outliers matter.
  • Review generated synthesis before high-stakes use, publication, procurement, safety decisions, or regulatory submissions.

Runtime

Runtime depends mainly on the number and length of submitted strategies and requested target_count. The endpoint is async, so clients should poll poll_url rather than hold an open request.

Cost behavior

Use smaller, cleaner source sets when possible. Remove duplicates before calling the endpoint, choose a target_count that matches your review surface, show estimated_cost_usd before execution, and use charge_usd from the completed result for final customer-visible accounting.

Billing notes

  • The queued response includes estimated_cost_usd as a pre-run estimate.
  • Completed billable jobs include charge_usd in result. Treat charge_usd as the customer-visible final charge.
  • Organization credits are deducted for billable completed work according to the account's public API pricing.
  • The final charge can be lower or higher than the pre-run estimate depending on source record count, source record length, target_count, and output cleanup.
  • Build product UI around the queued estimate and final customer-visible charge.
Representative input
{
  "inputs": {
    "design_challenge": "Keep outdoor learning spaces cool during hot afternoons without powered air conditioning.",
    "target_count": 5,
    "preserve_nuance": true,
    "session_id": "cool-schoolyard-001",
    "strategies": [
      {
        "id": "strat_termite_ventilation",
        "name": "Termite mound stack ventilation",
        "function": "Move heat and stale air away from enclosed chambers.",
        "organism_or_system": "Macrotermes termite mound",
        "written_strategy": "Termites build porous mounds and branching channels that couple wind and buoyancy to exchange gases and moderate temperature.",
        "mechanism": "A network of tunnels, porous walls, and vertical shafts creates pressure and temperature gradients that drive airflow without a centralized fan.",
        "source_type": "academic_paper",
        "source_id": "10.1242/jeb.042978",
        "citation": "Turner and Soar, 2008",
        "confidence": 8.5,
        "doi": "10.1242/jeb.042978"
      }
    ]
  },
  "configuration": {
    "metadata": {
      "external_run_id": "cool-schoolyard-001",
      "workflow_step": "strategy_distillation"
    }
  }
}
Queued response
{
  "job_id": "job_7f3a2b1c",
  "status": "queued",
  "agent_id": "agents.biomimicry.strategy_distiller",
  "poll_url": "/v1/jobs/job_7f3a2b1c",
  "estimated_cost_usd": 0.12,
  "created_at": "2026-05-27T18:30:00Z"
}
Representative completed result
{
  "job_id": "job_7f3a2b1c",
  "agent_id": "agents.biomimicry.strategy_distiller",
  "status": "completed",
  "created_at": "2026-05-27T18:30:00Z",
  "completed_at": "2026-05-27T18:31:20Z",
  "result": {
    "distilled_strategies": [
      {
        "id": "distilled_passive_air_exchange",
        "name": "Porous Stack Ventilation",
        "function": "Move heat and stale air through pressure and temperature gradients.",
        "combined_mechanism": "Source organisms use porous outer structures, vertical channels, and spatially distributed openings to couple buoyancy, wind pressure, and diffusion. The useful biological lesson is not simply a chimney; it is a tuned exchange surface where geometry, porosity, and thermal gradients work together.",
        "biological_nuance": "The mechanism depends on local wind, solar loading, chamber geometry, and wall permeability. Over-abstracting it as passive ventilation would lose the role of distributed porosity and feedback between mound structure and colony metabolism.",
        "organisms": [
          "Macrotermes termite mound"
        ],
        "source_strategy_ids": [
          "strat_termite_ventilation"
        ],
        "source_count": 1,
        "parent_distilled_ids": [],
        "distillation_round": 1,
        "original_strategy_ids": [
          "strat_termite_ventilation"
        ],
        "function_source": "thermal comfort",
        "abstraction_level": "mechanism",
        "confidence": 8.0,
        "related_distilled_ids": [],
        "citations": [
          {
            "title": "Termite mound stack ventilation",
            "doi": "10.1242/jeb.042978",
            "pmid": null,
            "url": "https://doi.org/10.1242/jeb.042978",
            "in_text": "Turner and Soar, 2008",
            "full": null,
            "year": null,
            "open_access": false,
            "source_type": "academic_paper",
            "authors": null,
            "journal": null
          }
        ],
        "citation_count": 1
      }
    ],
    "input_count": 1,
    "output_count": 1,
    "coverage_percentage": 100.0,
    "requested_target_count": 5,
    "represented_source_count": 1,
    "summary": "Distilled 1 submitted strategy into 1 biology-language strategy family with 100.0% source coverage.",
    "warnings": [
      {
        "code": "target_count_mismatch",
        "message": "Returned 1 distilled strategy for requested target_count 5.",
        "severity": "info"
      }
    ],
    "citations": {
      "count": 1,
      "items": [
        {
          "title": "Termite mound stack ventilation",
          "doi": "10.1242/jeb.042978",
          "url": "https://doi.org/10.1242/jeb.042978",
          "in_text": "Turner and Soar, 2008",
          "source_type": "academic_paper"
        }
      ]
    },
    "citation_count": 1,
    "charge_usd": 0.18
  }
}

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: the request shape failed validation, such as missing design_challenge, missing strategies, or target_count outside 1 to 50.
  • 429: the client exceeded the allowed request rate.
  • 503: the platform could not accept or complete the synthesis job at that time.
  • failed: the accepted job could not complete, often because strategy records were unusable, synthesis output needed review, or billing could not be completed.
  • 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.
  • Treat failed jobs as terminal unless your application can safely submit a new job.
  • Do not blindly retry POST /invoke after a network timeout because the public contract does not currently include an idempotency key.
  • Use stable session_id values and configuration.metadata so your application can reconcile jobs before creating duplicates.
  • If warnings show low coverage or target-count mismatch, revise the source set or target_count before rerunning.

Composition ideas

Search or upload first

Use retrieval, upload, or curation workflows to gather strategies, pass selected records into this endpoint, and show users the source links next to each distilled strategy.

Distill before design translation

Keep the Strategy Distiller output in biological language, then pass selected distilled_strategies to a design-principle or concept-generation step.

Review loop

Display warnings, coverage_percentage, represented_source_count, and source_strategy_ids so reviewers can decide whether to rerun with more records or a different target_count.

Compare source sets

Run the same design_challenge against different source sets and compare output_count, coverage_percentage, summary, and repeated mechanisms.

Workflow reconciliation

Put your own external_run_id or workflow_step in configuration.metadata so your application can connect the async job to local workflow state.

Application fit

  • Research report builders that compress a large set of biological strategies into a section a human can review.
  • Classroom tools where students compare recurring mechanisms across organisms.
  • Workshop facilitation boards that turn source research cards into named biological strategy families.
  • Product discovery systems that reduce noisy research into a short candidate set before ideation.
  • Knowledge curation pipelines that merge overlapping records without losing source_strategy_ids.
  • Regenerative design workflows comparing approaches to cooling, water handling, repair, sensing, and coordination.
  • Graph or notebook interfaces that let users expand a distilled strategy back to source records and citations.
  • Evaluation dashboards that compare coverage_percentage, output_count, repeated mechanisms, and lost outliers across corpora.