AgenticCode/openspec/specs/extraction-tools/spec.md

Purpose

Define the Semantic Kernel tool functions for extraction validation — counterparty lookup, trade validation, currency validation, schema validation, external API configuration, and error handling.

Requirements

Requirement: Counterparty lookup tool

The extraction plugin SHALL expose a lookup_counterparty Semantic Kernel function that accepts a counterparty name string and calls the external counterparty API. The tool SHALL return a list of candidate (counterparty, legal_entity) tuples.

Scenario: Single match found

• WHEN the tool is called with a counterparty name that matches exactly one record
• THEN the tool returns a single candidate with the counterparty name and legal entity ID

Scenario: Multiple matches found (disambiguation needed)

• WHEN the tool is called with a counterparty name that matches multiple records
• THEN the tool returns all matching candidates so the agent can present them to the user for selection

Scenario: No match found

• WHEN the tool is called with a counterparty name that matches no records
• THEN the tool returns an empty list and an informative message so the agent can ask the user for clarification

Requirement: Trade validation tool

The extraction plugin SHALL expose a validate_trade Semantic Kernel function that accepts a trade ID and calls the external trade validation API to verify the trade exists.

Scenario: Valid trade ID

• WHEN the tool is called with a known trade ID
• THEN the tool returns a success result confirming the trade exists

Scenario: Invalid trade ID

• WHEN the tool is called with an unknown trade ID
• THEN the tool returns an error result so the agent can flag it to the user

Requirement: Currency validation tool

The extraction plugin SHALL expose a validate_currency Semantic Kernel function that accepts a currency code and calls the external currency validation API to verify it is a valid ISO currency code.

Scenario: Valid currency code

• WHEN the tool is called with "GBP"
• THEN the tool returns a success result

Scenario: Invalid currency code

• WHEN the tool is called with an unrecognized code
• THEN the tool returns an error with suggestions for valid codes

Requirement: Schema validation tool

The extraction plugin SHALL expose a validate_schema Semantic Kernel function that accepts the full ExtractionResult JSON and validates that all required fields are present and correctly typed for every TradeItem.

Scenario: Valid extraction result

• WHEN the tool is called with a complete and correctly typed ExtractionResult JSON
• THEN the tool returns a success result with no errors

Scenario: Missing required fields

• WHEN the tool is called with a TradeItem missing the trade_id field
• THEN the tool returns a failure result listing the missing fields and which item they belong to

Requirement: External API configuration

All external API base URLs SHALL be configurable via appsettings.json under an ExternalApis section. Each tool's HttpClient SHALL read its base URL from configuration at startup.

Scenario: Configuration at startup

• WHEN the API starts
• THEN it reads external API base URLs from the ExternalApis configuration section and configures typed HttpClients accordingly

Requirement: External API error handling

Each tool SHALL handle HTTP errors from external APIs gracefully, returning a structured error message that the LLM agent can reason about rather than throwing exceptions.

Scenario: External API unavailable

• WHEN a tool calls an external API that is unreachable
• THEN the tool returns an error result with a descriptive message (e.g., "Counterparty API unavailable") so the agent can inform the user