POST /query

POST /api/signal-foundry/query は、agent が作った company_query.v1 を検証し、実行可能な条件だけを Company Search に渡します。

自然文をこの endpoint に直接投げるのではなく、Codex / Claude Code / 自社 backend 側で自然文を company_query.v1 に変換してから送ります。unsupported / weak / needs_human は 0 件成功に変換せず、response の query.gaps と query.warnings を読んで復旧します。

契約サマリー

この endpoint の役割は、構造化された query plan を安全に実行することです。Financial Gold で決定的な company_ids を作り、その集合を Company Search の company_ids filter として合成します。

Claude Code / Codex から使う場合は、まず company_query.v1 JSON を作り、CLI から実行します。自然文を sf company search の q に残すと、財務閾値が未検証テキストとして扱われ、0 件成功のように見えることがあります。

sf query --file company-query.json --json

リクエスト

curl -s \
  -X POST \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  "https://signal-foundry.app/api/signal-foundry/query" \
  --data '{
    "contract_version": "company_query.v1",
    "raw_request": "上場企業の金融業界で売上1000億円以上",
    "predicates": [
      {
        "type": "listing_status",
        "operator": "in",
        "values": ["listed"]
      },
      {
        "type": "industry_33_code",
        "operator": "in",
        "values": ["7050", "7100", "7150", "7200"]
      },
      {
        "type": "financial_metric",
        "source": "biz_1738_gold_financial_dataset",
        "metric": "revenue",
        "operator": "gte",
        "period": { "latest": true },
        "value": {
          "amount": 100000000000,
          "currency": "JPY",
          "unit": "absolute"
        }
      }
    ],
    "requested_output": {
      "limit": 20,
      "order": "name"
    },
    "execution_policy": {
      "allow_db_writes": false,
      "allow_external_search": false,
      "allow_llm_sql": false,
      "allow_unvalidated_q_fallback": false
    }
  }'

営業利益と純利益を含む複合条件では、operating_profit を operating_income alias warning 付きで実行します。経常利益は ordinary_income、税引前利益は profit_before_tax を使います。売上総利益、売上原価、販管費、法人税等、資本金、利益剰余金、有形固定資産、無形資産も latest annual の Financial Gold filter として実行できますが、費用・税金の符号反転や指標間の派生計算はしません。

sf query --json '{
    "contract_version": "company_query.v1",
    "raw_request": "上場企業で営業利益と純利益が黒字、かつ売上1000億円以上",
    "predicates": [
      {
        "type": "listing_status",
        "operator": "in",
        "values": ["listed"]
      },
      {
        "type": "financial_metric",
        "source": "biz_1738_gold_financial_dataset",
        "metric": "operating_profit",
        "operator": "positive",
        "period": { "latest": true }
      },
      {
        "type": "financial_metric",
        "source": "biz_1738_gold_financial_dataset",
        "metric": "net_income",
        "operator": "positive",
        "period": { "latest": true }
      },
      {
        "type": "financial_metric",
        "source": "biz_1738_gold_financial_dataset",
        "metric": "revenue",
        "operator": "gte",
        "period": { "latest": true },
        "value": {
          "amount": 100000000000,
          "currency": "JPY",
          "unit": "absolute"
        }
      }
    ],
    "requested_output": {
      "limit": 5
    },
    "execution_policy": {
      "allow_db_writes": false,
      "allow_external_search": false,
      "allow_llm_sql": false,
      "allow_unvalidated_q_fallback": false
    }
  }'

Body

対応済みの主な predicate:

financial_metric は現在、source: "biz_1738_gold_financial_dataset" の read-only 実行です。実行可能な hosted Gold filter は latest annual の revenue、operating_income、ordinary_income、profit_before_tax、net_income、gross_profit、cost_of_sales、selling_general_admin_expenses、income_tax_expense、total_assets、total_liabilities、current_assets、current_liabilities、noncurrent_assets、noncurrent_liabilities、trade_receivables、trade_payables、cash_and_cash_equivalents、cash_and_deposits、equity、capital_stock、retained_earnings、treasury_stock、property_plant_equipment、intangible_assets、inventories、interest_bearing_debt、operating_cash_flow、investing_cash_flow、financing_cash_flow です。operating_profit は operating_income として warning 付きで実行します。equity は Gold table 上では net_assets に写像されます。cash_and_cash_equivalents と cash_and_deposits は別定義として扱います。cost_of_sales、selling_general_admin_expenses、income_tax_expense、treasury_stock は報告値のまま扱い、符号反転や他指標からの派生はしません。inventories は棚卸資産合計の報告値を優先し、ない場合だけ相互排他的な商品・製品、仕掛品、原材料・貯蔵品 group を合算します。interest_bearing_debt は明示的な有利子負債または bonds-and-borrowings total を優先し、ない場合だけ current debt、non-current debt、lease liabilities の非重複 group を合算します。component 合算の場合は source_fact_ref.components に provenance を残します。ordinary_profit、operating_margin、roe、trend 条件などは、unsupported として止めます。

レスポンス

実行できた場合は company_query_result を返します。まず見る key:

• ok
• query.status
• query.executors.financial_gold.status
• query.executors.financial_gold.result.matched_count
• query.api.body.company_ids
• companies[].company.company_id
• search.meta.returned_companies
• search.meta.coverage_warnings

以下は短縮した例です。実際の query.executors.financial_gold.result.company_ids は最大 1000 件返ります。

{
  "object": "company_query_result",
  "ok": true,
  "status": "completed",
  "query": {
    "status": "supported",
    "execution": {
      "allowed": true,
      "reason": "validated"
    },
    "executors": {
      "financial_gold": {
        "status": "ready",
        "result": {
          "source": "hosted_table",
          "matched_count": 968,
          "company_ids": ["jpx_7203", "jpx_7267"],
          "truncated": false
        }
      }
    }
  },
  "companies": [
    {
      "company": {
        "company_id": "jpx_8306",
        "display_name": "三菱ＵＦＪフィナンシャル・グループ"
      }
    }
  ],
  "search": {
    "companies": [
      {
        "company": {
          "company_id": "jpx_8306",
          "display_name": "三菱ＵＦＪフィナンシャル・グループ"
        }
      }
    ],
    "meta": {
      "returned_companies": 20,
      "matched_companies": 62
    }
  }
}

companies は search.companies の convenience copy です。正本は search の Company Search response と query の validation result です。

実行不可 response

ratio / trend / ordinary profit など実行できない条件の場合も、可能な限り 200 で company_query を返します。これを 0 件成功として扱わないでください。

{
  "object": "company_query",
  "ok": false,
  "status": "unsupported",
  "error": {
    "code": "financial_gold_adapter_unsupported",
    "message": "company_query.v1 could not be converted into an executable Company Search request."
  },
  "query": {
    "status": "unsupported",
    "gaps": [
      {
        "code": "financial_gold_adapter_unsupported",
        "severity": "blocking"
      }
    ]
  }
}

復旧方法

CLI equivalent

company_query.v1 は CLI から直接実行できます。agent が自然文を受け取った場合は、自然文をこの command に直接渡さず、先に company_query.v1 JSON を生成してください。

sf query --file company-query.json --json

財務閾値を正確に扱う workflow では、agent / backend が company_query.v1 を生成し、この endpoint に送ります。自然文のまま閾値を q に残すと、unsupported / weak 条件を 0 件成功と誤読しやすくなります。