← Library
private-reader

Private reader

For the documents you would never paste into a chat window: a tenancy agreement, a bank statement, a letter from the tax office, a diagnosis. It lists the folder, searches it for the words that would appear in the passage rather than the words of the question, reads around each hit, and answers with `file.ext:line` beside every claim. Two things make it more than a search box. The spec names no vendor — OpenAiConfig with no url is whatever OPENAI_BASE_URL points at, so the same file runs against a hosted model or against Ollama on localhost, and with a local model nothing about the question, the documents or the answer leaves the building. And a plugin transform enforces the citation rather than requesting it: an answer carrying no reference is refused on its way out, and the flow ends by saying the documents do not answer the question. That is the honest outcome, and it is not the one a model under pressure to be helpful picks on its own. Point the mount at your own folder and the sample documents are gone.

documentsprivatelocalcitationsrag

Run it

terminal
npx @heddle-run/cli run private-reader

One command, pasted into a terminal. The bare name is this entry's published address, and fetching it fetches the agent — flow, tools and sample data travel inside the bundle, along with a default input. heddle asks for anything still missing, like your model key, before it starts. Nothing is installed.

The flow

spec.yaml
# private-reader — an agent for the documents you would never upload.
#
# start ──> read (Agent + CitationCheck post transform) ──> route ──┬─> end_answered
# └─> end_ungrounded
#
# Nothing here names a vendor. `OpenAiConfig` with no url set is whatever
# OPENAI_BASE_URL points at, so the same file answers from gpt-4o-mini or from
# a model on localhost, and the choice belongs to the machine rather than to the
# document. Point it at Ollama and no part of the question, the documents or the
# answer leaves the building.
component_type: Flow
agentspec_version: 26.2.0
id: flow_private_reader
name: private-reader
description: >
Answers a question about a folder of documents, quoting the file and line each
claim comes from, and refuses to answer at all when the documents do not say.
metadata: {}
inputs: []
outputs: []
start_node:
$component_ref: n_start
nodes:
- $component_ref: n_start
- $component_ref: n_read
- $component_ref: n_route
- $component_ref: n_answered
- $component_ref: n_ungrounded
control_flow_connections:
- component_type: ControlFlowEdge
id: e_start_read
name: start_to_read
metadata: {}
from_node: { $component_ref: n_start }
from_branch: null
to_node: { $component_ref: n_read }
- component_type: ControlFlowEdge
id: e_read_route
name: read_to_route
metadata: {}
from_node: { $component_ref: n_read }
from_branch: null
to_node: { $component_ref: n_route }
- component_type: ControlFlowEdge
id: e_route_answered
name: route_to_answered
metadata: {}
from_node: { $component_ref: n_route }
from_branch: answered_branch
to_node: { $component_ref: n_answered }
- component_type: ControlFlowEdge
id: e_route_ungrounded
name: route_to_ungrounded
metadata: {}
from_node: { $component_ref: n_route }
from_branch: ungrounded_branch
to_node: { $component_ref: n_ungrounded }
data_flow_connections:
- component_type: DataFlowEdge
id: e_question
name: question_to_read
metadata: {}
source_node: { $component_ref: n_start }
source_output: question
destination_node: { $component_ref: n_read }
destination_input: question
# The transform writes this, not the model: "ok" when the answer cited its
# sources, "rejected" when it did not.
- component_type: DataFlowEdge
id: e_status
name: status_to_route
metadata: {}
source_node: { $component_ref: n_read }
source_output: transform_status
destination_node: { $component_ref: n_route }
destination_input: branching_mapping_key
- component_type: DataFlowEdge
id: e_result_answered
name: result_to_answered
metadata: {}
source_node: { $component_ref: n_read }
source_output: result
destination_node: { $component_ref: n_answered }
destination_input: result
- component_type: DataFlowEdge
id: e_reason_ungrounded
name: reason_to_ungrounded
metadata: {}
source_node: { $component_ref: n_read }
source_output: transform_reason
destination_node: { $component_ref: n_ungrounded }
destination_input: transform_reason
$referenced_components:
n_start:
component_type: StartNode
id: n_start
name: start
metadata: {}
inputs: []
outputs:
- { title: question, type: string }
branches: [next]
n_read:
component_type: AgentNode
id: n_read
name: read
metadata: {}
inputs:
- { title: question, type: string }
outputs:
- { title: result, type: string }
- { title: transform_status, type: string }
- { title: transform_reason, type: string }
branches: [next]
agent:
component_type: Agent
id: a_reader
name: private-reader-agent
description: Answers from a local folder of documents, with citations
metadata: {}
inputs:
- { title: question, type: string }
outputs:
- { title: result, type: string }
system_prompt: |
You answer questions about a folder of documents on this machine. They
are private — contracts, statements, letters, notes — and the person
asking has read some of them and cannot remember where a detail was.
Work like this:
1. Call doc_list first, unless you already know the folder. Names carry
information: a date, a counterparty, a kind of document.
2. Call doc_search for the words that would appear in the passage, not
the words of the question. A contract says "termination", a person
asks "how do I get out of it".
3. Call doc_excerpt around any hit worth reading. A grep line is a
pointer; the surrounding paragraph is the evidence.
4. Answer in plain sentences, and put the source of every claim inline
as `file.ext:line` — the exact form doc_search gives you.
Two things you must not do. Do not answer from what you know about
contracts, tax or medicine in general: the only authority here is these
files. And do not soften a gap into a guess — if the documents do not
say, the answer is that they do not say, and which ones you checked.
An answer with no `file.ext:line` in it is refused before anybody reads
it, so cite as you go rather than at the end.
Question: {{question}}
llm_config:
# No `url`, on purpose. The OpenAI client reads OPENAI_BASE_URL, so this
# one line runs against a hosted model or against Ollama on localhost
# without the document changing. See the README.
component_type: OpenAiConfig
id: llm_openai
name: model
metadata: {}
model_id: gpt-4o-mini
api_key: $OPENAI_API_KEY
tools:
- component_type: ServerTool
id: t_list
name: doc_list
description: >
List the documents in the folder, with their size and how many lines
each has. Start here — the file names usually say what is where.
metadata: {}
inputs:
- { title: pattern, type: string, default: "" }
outputs:
- { title: documents, type: string }
- { title: count, type: integer }
- component_type: ServerTool
id: t_search
name: doc_search
description: >
Search every document for a phrase, case-insensitively. Returns each
hit as `file.ext:line text`, which is exactly the citation form the
answer must use.
metadata: {}
inputs:
- { title: query, type: string }
- { title: limit, type: integer, default: 12 }
outputs:
- { title: hits, type: string }
- { title: count, type: integer }
- component_type: ServerTool
id: t_excerpt
name: doc_excerpt
description: >
Read a window of lines around a point in one document. Use it on a
search hit before quoting it: a matching line is rarely the whole
clause.
metadata: {}
inputs:
- { title: document, type: string }
- { title: line, type: integer }
- { title: context, type: integer, default: 6 }
outputs:
- { title: text, type: string }
- { title: found, type: boolean }
transforms:
- component_type: CitationCheck
id: p_cite
name: citation_check
metadata: {}
min_citations: 1
n_route:
component_type: BranchingNode
id: n_route
name: route
metadata: {}
inputs:
- { title: branching_mapping_key, type: string }
outputs: []
branches: [answered_branch, ungrounded_branch]
mapping:
rejected: ungrounded_branch
DEFAULT_BRANCH: answered_branch
n_answered:
component_type: EndNode
id: n_answered
name: end_answered
metadata: {}
inputs:
- { title: result, type: string }
outputs: []
branches: []
branch_name: answered_branch
n_ungrounded:
component_type: EndNode
id: n_ungrounded
name: end_ungrounded
metadata: {}
inputs:
- { title: transform_reason, type: string }
outputs: []
branches: []
branch_name: ungrounded_branch

Facts

Model
gpt-4o-mini
Tools
doc_excerpt, doc_list, doc_search
Mounts
documents:documents:ro
Requires
OPENAI_API_KEYany non-empty value when OPENAI_BASE_URL points at a local modelpython3bash

The entry

  • README.md
  • bundle.json
  • documents/README.md
  • documents/letter-hmrc.md
  • documents/statement-march.txt
  • documents/tenancy-agreement.md
  • plugin.json
  • plugin.mjs
  • probe-args.json
  • script.json
  • spec.yaml
  • tools/doc_excerpt.sh
  • tools/doc_list.sh
  • tools/doc_search.sh

The spec, the tools and the mounted files travel in the archive; the README and bundle.json stay here. Neither carries the API key — a spec names it as an environment variable and it resolves where the bundle runs.

Source

library/private-reader on GitHub →

Its README covers pointing this at your own data, and what it will not do.