Repository navigation
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_DISCOVERYis replaced byBROKER_QUERY_PROVIDER. If your Broker ran query discovery withBROKER_QUERY_DISCOVERY=on, setBROKER_QUERY_PROVIDER=llminstead.BROKER_QUERY_CATALOG_FILE,BROKER_QUERY_MODELandBROKER_QUERY_URI_SCHEMEkeep their meaning. The old setting is no longer read: a Broker that still sets onlyBROKER_QUERY_DISCOVERYstarts with no catalog search and logsbroker.query_discovery.disabled.BROKER_QUERY_PROVIDER=onstops the Broker at start-up. If you deploy with the Terraformcompose-stackmodule or the demo and staging stacks, nothing changes for you:query_discoveryworks as before. - Identity.
IDENTITY_MCP_SEARCH_FILTERS_SCHEMA(or its_FILEform) is new and optional. Leave it unset unless the Broker behind this service runs theelasticsearchprovider. Unset,fora_discoverchecks no filter itself and passessearch_filtersto the Broker, as in v1.0.0. - Console. No setting is new or removed.
CONSOLE_SUPPORT_EMAILis now also written into the README of every edge package, so set it. - Terraform. The
compose-stackmodule and thedemo-awsandstaging-awsstacks take a new optionalelasticsearch_searchobject. No variable is removed. Theaws-vmmodule has a new output,data_volume_name.
Highlights
- Catalog search providers.
BROKER_QUERY_PROVIDERselects 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) orelasticsearch. 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,filtersandlimit. 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/templateand_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 isapi_key,basicornone, with no default. Plainhttpneeds its own opt-in (BROKER_ES_ALLOW_HTTP), and bothnoneand plainhttplog 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 issrc/broker/SEARCH-TEMPLATE.md, and a working template and filter schema to start from are indeploy/broker/. Design: ADR-030. - Declared search filters. A deployment declares the
search_filterskeys its template applies, and the format of each value, in a JSON Schema (BROKER_ES_FILTERS_SCHEMAorBROKER_ES_FILTERS_SCHEMA_FILE). The Broker checks every request against it before it searches: a key the schema does not declare is refused withUNIMPLEMENTED, and a value it refuses withINVALID_ARGUMENT, each naming the fieldsearch_filters.<key>. A filter is never dropped, and with no schema every filter is refused. The Identity service'sfora_discovertool shows the same schema to agents as the input schema ofsearch_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_EMAILis set, where to write for help. - Terraform. With
elasticsearch_searchset, thecompose-stackmodule and the demo and staging stacks run the Broker on theelasticsearchprovider. The module takes anhttpsURL 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
elasticsearchprovider, 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