Siftrank

SiftRank

Turn a large collection into meaningful candidates, rank them against the user's objective, and investigate the strongest results in their original context. Prefer this workflow when there are too many items to examine directly and relevance requires semantic judgment.

SiftRank repeatedly compares small shuffled batches and refines their ordering. The collection need not fit into a single model request. Use a fast, inexpensive model to prioritize material for deeper investigation.

Keep preparation simple. Reuse existing extraction tools and data structures. Speed, cost, and ranking quality depend on the model and workload.

Read the documentation and discover the CLI

Read the project's README and relevant configuration examples:

https://github.com/noperator/siftrank

Run siftrank --help, or ./siftrank --help for a local build. Check the installed version's flags and behavior; documentation may describe a different release. If examples disagree with the installed implementation, check the relevant source rather than guessing.

In a SiftRank checkout, build with:

go build -o siftrank ./cmd/siftrank

Otherwise, the published installation command is:

go install github.com/noperator/siftrank/cmd/siftrank@latest

Check that the installed version supports the intended provider.

Define the objective and candidate units

Translate the user's objective into a clear ranking criterion: what makes one candidate more useful, relevant, or promising than another?

Common applications include:

• Rank web results by likelihood of directly answering a research question.
• Find passages containing evidence for or against a claim.
• Prioritize support tickets by urgency or relevance to an incident.
• Select products that best satisfy stated requirements.
• Find messages containing a decision, commitment, or unresolved question.
• Prioritize files or functions likely to explain a behavior.
• Find log events or event sequences relevant to a failure.
• Select the most useful evidence to include in an agent's next context.

Use file listings, indexes, parsers, and exact searches to enumerate and scope the collection. Avoid aggressive keyword filtering that could remove semantically relevant candidates before ranking.

Choose the smallest unit that retains the context needed for the judgment:

• Documents: passages or sections with headings and source locations.
• Web results: title, URL, and useful snippet or extracted passage.
• Messages: individual messages or short threads when replies matter.
• Records: individual objects or related groups when the relationship matters.
• Logs: events or time windows with identifiers and timestamps.
• Code: functions, methods, files, or basic blocks, depending on the question.

Smaller units make comparisons more focused but can lose essential context. Preserve headings, surrounding text, signatures, or neighboring events when needed. Split oversized units at meaningful boundaries rather than silently truncating them.

Retain a stable identifier and source location for every candidate. Prepare the collection programmatically instead of reading the entire corpus into the agent's conversation.

Prefer JSON objects with an explicit presentation template

For agent workflows, prefer a JSON file containing an array of objects. Each object represents one candidate and can retain all the information downstream automation needs.

Use --template to select and format the fields the ranker should see. SiftRank applies the Go text template separately to every object. The template controls the model-facing presentation; the full original object remains available in the final output.

For example, candidates.json could contain:

[
  {
    "id": "result-001",
    "title": "Moving an application between regions",
    "content": {
      "excerpt": "Explains replication, cutover, and rollback procedures."
    },
    "source": {
      "url": "https://example.org/regional-migration"
    },
    "metadata": {
      "retrieval_score": 0.73,
      "collection": "search-pass-1"
    }
  },
  {
    "id": "result-002",
    "title": "Regional availability overview",
    "content": {
      "excerpt": "Lists supported regions and available services."
    },
    "source": {
      "url": "https://example.org/regions"
    },
    "metadata": {
      "retrieval_score": 0.91,
      "collection": "search-pass-1"
    }
  }
]

Create candidate.tmpl:

ID: {{.id}}
Title: {{.title}}
Source: {{.source.url}}

{{.content.excerpt}}

The template accesses each object's fields directly, including nested fields such as .content.excerpt. Use Go template index for keys that cannot be accessed conveniently with dot notation, for example {{index .metadata "retrieval-score"}}.

Here, the model sees the ID, title, URL, and excerpt. It does not see metadata, because the template omits it. Nevertheless, metadata and every other original field remain in the output's document object.

This separates presentation from storage: keep rich records for downstream processing while showing the ranker only the evidence relevant to its task. Avoid including unrelated scores or metadata that might bias the judgment.

Include the identifier or source locator in the rendered template. In the current implementation, candidate identity derives from rendered text, so distinct records with identical presentations may collide. Consolidate true duplicates or distinguish their rendered identifiers.

Use a JSON serializer to preserve multiline text and escaping. The expected JSON input is an array, not JSONL.

Plain text and stdin

Plain text input is line-oriented: each nonempty line becomes one candidate. Use {{.Data}} to reference a text line in a template. Multiline passages, functions, and rich records are better represented as JSON objects.

The reviewed CLI requires --file. On Unix, use --file /dev/stdin to read a pipeline. Add --json when stdin contains a JSON array, since /dev/stdin has no .json extension. Do not assume that --file - is supported.