MiroFish pre-ingestion seeds from FeedOracle

中文版本: README-ZH.md

Independent, unofficial third-party adapter. This project is not built,
reviewed, verified or endorsed by the MiroFish maintainers or by Shanda
Group. It is not an official MiroFish service, not a native MiroFish
integration, and not a real-time MCP connection: MiroFish agents receive no
MCP access from this repository. It produces a file that a human uploads.

What this repository does

It collects a small, explicitly defined set of FeedOracle MCP responses,
verifies each grounding-receipt signature against the published FeedOracle
JWKS, and writes a deterministic Markdown seed plus a machine-readable
provenance sidecar. The seed is written so that MiroFish's own ingestion can
use it: a narrative section that survives MiroFish's 500-character chunking,
followed by the complete raw responses for audit.

What this repository does not do

• It does not give MiroFish agents live tool access.
• It does not run, invoke, extend or modify MiroFish.
• It does not pay, settle, sign transactions, or call priced routes. The five
  bundled scenarios use public, free FeedOracle endpoints.
• It does not decide compliance. Evidence indicators are inputs for review, not
  regulatory verdicts, certifications, ratings or investment advice.
• It does not assert that a FeedOracle response is correct. It records what was
  returned, when, and that the accompanying receipt verified.

Exact data flow

flowchart LR
    A[FeedOracle public MCP endpoints] --> B[Independent local adapter]
    B --> C[Schema validation]
    C --> D[Receipt-signature verification]
    D --> E[Deterministic narrative seed]
    E --> F[Raw JSON audit appendix]
    F --> G[User uploads the .md seed into MiroFish]
    G --> H[MiroFish performs its own ingestion and simulation]

Every step before the upload happens locally, on the machine that runs the
generator. Nothing is sent to MiroFish by this code.

Supported scenarios

Definitions and their exact tool calls live in
seeds/scenarios.py. Tool inventories are discovered at
runtime; this repository publishes no static count of FeedOracle or OracleNet
servers or tools, because such counts go stale and prove nothing.

Installation

MiroFish's backend pins requires-python = ">=3.11,<3.13", so use Python 3.11
or 3.12.

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Deterministic generation

python seeds/generate_seed.py --list
python seeds/generate_seed.py \
  --scenario rlusd_integrity_review \
  --output output/rlusd_integrity_review.md

Identical inputs produce a byte-identical seed. Ordering, field selection and
number formatting are fixed; nothing is summarised, rounded or rephrased by a
model. A run writes two files and writes nothing at all if any required call or
verification fails:

• *.md — the seed: narrative section, then the complete raw appendix.
• *.provenance.json — inputs, receipts, verification results, hashes, adapter
  version and the pinned MiroFish commit.

Optional authentication

The bundled scenarios work without any credential. If your FeedOracle access
requires one, set FEEDORACLE_API_KEY; the adapter sends it as an X-API-Key
request header. It is never placed in tool arguments — the advertised tool
schemas declare additionalProperties: false, and an extra argument would also
break the receipt's signed input_hash. The credential never appears in a
seed, a provenance file, an error message or a log line, and the test suite
enforces that.

What signature verification does and does not establish

The adapter verifies the receipt signature against the published FeedOracle
JWKS: ES256K over the canonical receipt, plus a required ML-DSA-65 signature
for receipt version 0.4 and above. It also recomputes the input_hash over the
arguments that went on the wire, so a receipt cannot be paired with a different
request.

That establishes the integrity of the signed receipt fields that were actually
included — tool, observation time, request hash, verdict. It does not establish
that an evidence indicator is legally correct, that a hypothetical scenario is
true, or that a MiroFish simulation outcome is reliable.

It also does not bind the returned payload: the server's output_hash field is
currently not derived from the response body, so this repository makes no
output-binding claim. See
docs/FOLLOW_UP_RECEIPT_OUTPUT_BINDING.md.

Local content hash

For every record the adapter computes its own SHA-256 over the exact content it
stores, published as content_sha256. This hash is local and self-asserted: it
shows the seed still carries the payload the adapter saved, and it is not
itself signed by the server receipt.

Importing the seed into MiroFish

1. Generate the seed and read both output files before using them.
2. Run MiroFish at the pinned commit, or re-validate compatibility yourself
   against a newer one.
3. Create a project and upload the generated .md file as seed material.
   MiroFish accepts pdf, md, txt and markdown
   (backend/app/config.py, ALLOWED_EXTENSIONS).
4. Paste the seed's Simulation requirement section into the requirement
   field.
5. Read the resulting report as a simulation. It is not evidence, and it is not
   a regulatory conclusion.

MiroFish only needs the .md file. The provenance sidecar is for your own
review and audit trail.

Pinned compatibility snapshot

Developed against MiroFish commit
4ebb2ed6e9d33e12b6c06e59789ca6a14cd74661.

Verified locally at that commit, using MiroFish's own module: .md is an
accepted extension, FileParser.extract_text returns the seed unchanged, and
split_text_into_chunks (500 characters, 50 overlap) keeps every narrative
record inside a single chunk.

Not verified: the full upload and project-creation path. Building a MiroFish
project additionally requires an external LLM API and a Zep Cloud key, so that
part was deliberately not executed. The pin is a reproducible compatibility
snapshot, not a guarantee: newer MiroFish revisions are not automatically
supported, and the adapter should be re-tested against them.

Limitations

• Evidence reflects one point in time. Regenerate the seed when freshness
  matters; an old receipt stays verifiable but may no longer describe the world.
• The narrative section quotes short scalar values. Long values and values
  containing sentence separators are omitted whole rather than cut, so no
  statement is ever truncated; the raw appendix always holds the full response.
• MiroFish chunks the raw JSON appendix without sentence boundaries. That is
  expected: the appendix serves auditability, the narrative carries the meaning.
• Only the endpoints listed in connectors/oracle_registry.py are contacted.

Security

• Only explicit HTTPS endpoints are used; redirects are disabled for MCP and
  JWKS requests.
• The verifier refuses any JWKS location other than the configured FeedOracle
  one, even if a receipt names a different URL.
• Generated artifacts may contain third-party data — review them before sharing.
• Credentials belong in the environment, never in a commit. .env is ignored.

See SECURITY.md for reporting and operational guidance.

Reproducibility

python -m pip install -r requirements-dev.txt
python -m pytest -q

The suite runs fully offline with deterministic mock MCP responses and locally
generated signing keys. It covers the MCP lifecycle and tools/list
pagination, fail-closed handling of transport, protocol and tool errors,
signature and argument tampering, credential placement, byte-identical output,
untruncated audit data, chunk safety against a verbatim copy of MiroFish's
splitter, and claim hygiene in both README files.

No compliance verdict

Nothing in this repository, in a generated seed, or in a MiroFish report
produced from one is a legal, regulatory, financial or investment conclusion.
Evidence is structured for human or machine review. Human review remains
required for regulated or irreversible decisions.

Independence and trademarks

MiroFish is maintained by its own authors. FeedOracle and OracleNet are
independent third-party services. No affiliation with, verification by, or
endorsement from the MiroFish maintainers or Shanda Group is claimed. Product
and project names belong to their respective owners.

License

MIT. See LICENSE.