Skip to content

v1.1.0

Latest

Choose a tag to compare

@legendko legendko released this 05 Nov 17:15

v1.1.0 lets a Broker answer an agent's free-text query from a catalog search the operator chooses, including an Elasticsearch index the operator already runs, and lets agents narrow that search with filters the deployment declares. Every edge package the publisher console hands out now carries a README with its deploy steps and the checks the console runs.

Upgrading from v1.0.0

  • No database migrations, and the protocol does not change. The release stays on FORA protocol v1.2.0. The Exchange and the edge worker behave as in v1.0.0.
  • Broker: BROKER_QUERY_DISCOVERY is replaced by BROKER_QUERY_PROVIDER. If your Broker ran query discovery with BROKER_QUERY_DISCOVERY=on, set BROKER_QUERY_PROVIDER=llm instead. BROKER_QUERY_CATALOG_FILE, BROKER_QUERY_MODEL and BROKER_QUERY_URI_SCHEME keep their meaning. The old setting is no longer read: a Broker that still sets only BROKER_QUERY_DISCOVERY starts with no catalog search and logs broker.query_discovery.disabled. BROKER_QUERY_PROVIDER=on stops the Broker at start-up. If you deploy with the Terraform compose-stack module or the demo and staging stacks, nothing changes for you: query_discovery works as before.
  • Identity. IDENTITY_MCP_SEARCH_FILTERS_SCHEMA (or its _FILE form) is new and optional. Leave it unset unless the Broker behind this service runs the elasticsearch provider. Unset, fora_discover checks no filter itself and passes search_filters to the Broker, as in v1.0.0.
  • Console. No setting is new or removed. CONSOLE_SUPPORT_EMAIL is now also written into the README of every edge package, so set it.
  • Terraform. The compose-stack module and the demo-aws and staging-aws stacks take a new optional elasticsearch_search object. No variable is removed. The aws-vm module has a new output, data_volume_name.

Highlights

  • Catalog search providers. BROKER_QUERY_PROVIDER selects one catalog search per Broker: none (the default, as before), llm (the former query discovery: a model extracts music tags from the query and matches them against the music feed held in memory) or elasticsearch. A provider that fails never falls back to another, and a configuration problem stops the Broker at start-up, naming the setting. Settings: src/broker/CONFIGURATION.md §7.
  • Elasticsearch catalog search. The Broker runs the index owner's search template, stored in the cluster (BROKER_ES_TEMPLATE_ID) or sent with each search from a file (BROKER_ES_TEMPLATE_FILE), and fills three parameters: query, filters and limit. It reads one URL from each hit at a configured path (BROKER_ES_HIT_URL_PATH), and each URL then takes the normal route through the publisher's discovery file and the Exchange's offers. The Broker calls only _search/template and _render/template, with Go's standard HTTP client and no Elasticsearch client library, so it works with Elasticsearch 6.x and later and with OpenSearch. It is tested on Elasticsearch 7.15.0. Authentication is api_key, basic or none, with no default. Plain http needs its own opt-in (BROKER_ES_ALLOW_HTTP), and both none and plain http log a warning at start-up. At start-up the Broker renders and runs the template once: credentials the cluster refuses stop the start, and an unreachable or misconfigured cluster logs a warning. A template file that inserts agent text unescaped ({{{ }}}, {{& }}, the join lambda, or changed delimiters) is refused. The guide for the index owner is src/broker/SEARCH-TEMPLATE.md, and a working template and filter schema to start from are in deploy/broker/. Design: ADR-030.
  • Declared search filters. A deployment declares the search_filters keys its template applies, and the format of each value, in a JSON Schema (BROKER_ES_FILTERS_SCHEMA or BROKER_ES_FILTERS_SCHEMA_FILE). The Broker checks every request against it before it searches: a key the schema does not declare is refused with UNIMPLEMENTED, and a value it refuses with INVALID_ARGUMENT, each naming the field search_filters.<key>. A filter is never dropped, and with no schema every filter is refused. The Identity service's fora_discover tool shows the same schema to agents as the input schema of search_filters (IDENTITY_MCP_SEARCH_FILTERS_SCHEMA), so an agent sees the accepted keys and formats before it calls. Settings: src/identity/CONFIGURATION.md.
  • A README in every edge package. Each edge package the console hands out now carries a README written for that domain: what is in the package, its values, links to the CDN vendor's pages, the deploy steps, and the three checks the console runs, numbered, each with the answer to expect. It ends with what verifies the domain and, when CONSOLE_SUPPORT_EMAIL is set, where to write for help.
  • Terraform. With elasticsearch_search set, the compose-stack module and the demo and staging stacks run the Broker on the elasticsearch provider. The module takes an https URL and a read-only API key, and writes the key, the template and the filter schema to the Broker's key directory as files, never into the compose file.
  • Testing. Integration tests run the provider against a real Elasticsearch 7.15.0 node, and the end-to-end stack runs a second Broker on the elasticsearch provider, with its own obligations.

Container images

Built from this tag for linux/amd64.

docker pull ghcr.io/fora-protocol/exchange:1.1.0
docker pull ghcr.io/fora-protocol/broker:1.1.0
docker pull ghcr.io/fora-protocol/identity:1.1.0
docker pull ghcr.io/fora-protocol/console:1.1.0
Image Digest
exchange sha256:c7f2d6b0a4b77b9f06da81fe746e4a1c90ed957d2d9b31319b2a0252d63502a9
broker sha256:db1f8b9ef210efe9a59deb7cbaebeb455d10c1df44409abf3544d1b68dba1cb7
identity sha256:7485ebdcc6258aae6f8b436ec51cf6cca5d5da7d20ebc194c7dbd54961e70097
console sha256:0ba0bbb031d426980152986ccd32e0c466d5c79b20f68a03f1727ccb2396f6fb

Each service's DEPLOYMENT.md and CONFIGURATION.md say how to run it: exchange, broker, identity, console.

Protocol

Unchanged since v1.0.0: FORA protocol v1.2.0 everywhere, as the Go module github.com/FORA-Protocol/protocol v1.2.0 for the services, @fora-protocol/sdk 1.2.0 for the edge, and fora-protocol-sdk 1.2.0 with the fora-protocol 1.2.0 models for the end-to-end tests.

Full Changelog: v1.0.0...v1.1.0