본문으로 건너뛰기

후보 확장

Candidate expansion은 initial search 이후 관련 tool을 추가합니다. 가장 중요한 확장은 producer discovery입니다. target이 required field를 소비한다면, graph는 그 field를 생산하는 tool을 포함할 수 있습니다.

이렇게 하면 LLM catalog는 작게 유지하면서도 plan synthesis가 required input을 채울 tool을 볼 수 있습니다.

Minimal Example​

from graph_tool_call.graphify import expand_candidates_with_producers

expanded = expand_candidates_with_producers(
    candidate_names=["cancelOrder"],
    tools_by_name=tools_by_name,
    max_producers_per_field=2,
    max_hops=1,
)

cancelOrder가 orderNo를 요구하고 다른 tool이 orderNo를 produce한다면, target selection 또는 planning 전에 producer가 candidate list에 추가될 수 있습니다.

Target-Specific Dependency Closure​

from graph_tool_call.graphify import assemble_tool_bundle, complete_target_dependencies

closure = complete_target_dependencies(
    selected_target,
    tools_by_name,
    graph=tool_graph,
    query=query,
    available_fields={"tenant_id"},
    context_field_names={"workspace_id"},
    allow_mutation=False,
    max_hops=3,
)

Closure는 target, required dependency, optional dependency를 별도 역할로 유지합니다. OpenAPI graph에서 consumer-aligned output promotion은 producer coverage를 높일 수 있지만, 일치하는 모든 neighbor를 실행해도 된다는 뜻은 아닙니다. API contract edge는 required field별로 해석하고, 출처 없는 structural requires edge는 optional hint로 남깁니다.

변경 dependency는 기본 차단됩니다. query의 생성·수정·삭제 의도와 adapter가 자체 인증 및 사용자 확인 후 설정하는 allow_mutation=True가 모두 있어야 허용됩니다. 둘 중 하나만으로는 부족하며, 차단된 tool은 model-facing alternative에도 노출하지 않고 diagnostics에만 남깁니다. contract-only producer도 찾기/목록 -> 상세/실행 형태의 탐색 흐름이 query에 있을 때만 자동 선택합니다. 직접 전달된 ID, body field, scope 값은 추가 API 호출 대신 user input slot으로 남습니다. 각 판단은 closure.safety, closure.user_input_slots, closure.diagnostics에서 확인할 수 있습니다.

하위 호환성을 위해 query를 생략한 기존 호출은 v1 admission 동작을 유지합니다. 실행 adapter는 safety-aware admission을 위해 원본 query를 항상 전달해야 합니다.

make paper-openapi-closure

이 gate는 required-producer recall, 전체 dependency 완성률, 불필요한 dependency, 표본 충분성을 함께 검사합니다. OpenAPI에서 optional인 workflow step은 query, manual, OpenAPI Link 또는 promoted trace 근거가 생기기 전까지 planner의 판단으로 남깁니다.

Expansion Sources​

  • deterministic IO contract edge
  • OpenAPI link
  • manual edge
  • promoted run-observed trace edge
  • high-confidence semantic link

Inputs​

Parameter목적
candidate_namesinitial retrieved target
tools_by_name이름으로 indexing된 tool metadata
max_producers_per_fieldmissing required field마다 추가할 producer 상한
max_hopsproducer chain을 따라갈 깊이
action_priorityproducer-like action ordering 옵션

Helper는 required kind=data consume field만 확장합니다. context, auth, paging, search filter는 execution catalog를 폭발시키면 안 됩니다.

Output​

반환값은 ordered tool name list입니다. 원래 candidate가 먼저 남고 그 뒤에 producer candidate가 붙습니다.

[
    "cancelOrder",
    "searchOrders",
    "getOrderDetail",
]

Safety Policy​

Expansion은 LLM catalog를 과하게 늘리지 않으면서 planning을 도와야 합니다. low-confidence structural edge는 graph inspection에는 남기되, execution-oriented candidate에는 strong evidence를 우선합니다.

권장 기본값:

SettingGuidance
max_hops일반 retrieval은 1, target-specific planning에서만 더 크게
max_producers_per_field1에서 3
Manual edgedeterministic contract evidence로 표현하기 어려울 때만
Trace edge단일 observed run이 아니라 promoted 상태만

Failure Modes​

증상가능한 원인조치
expanded tool이 너무 많음broad required field 또는 높은 max_hopshop/producer limit 낮추기
producer가 추가되지 않음produces metadata 부족IO contract 확인
wrong producer가 추가됨weak semantic tagsemantic build 또는 alias 보강
LLM에 helper tool이 노출됨source catalog에 non-user tool 포함collection build 단계에서 filter

Validation​

Candidate expansion은 list size만 보지 말고 plan outcome으로 검증합니다. 좋은 expansion은 평균 candidate count를 크게 늘리지 않으면서 unsatisfied_field failure를 줄입니다.

추적할 값:

  • average candidate count
  • max candidate count
  • plan hit rate
  • unsatisfied_field count
  • selector ambiguity count

관련 문서​