Retrieval basics

Directory examples/python/retrieval_basics

Store documents, retrieve passages with hybrid search, return citations and delete indexed content. Ingest text directly or read local .txt, .md and .rst files.

Agent node label retrieval_basics, version 1.0.0.

Capabilities

Capability	Kind	Signature	Module	Summary
`answer_question`	traversal	`(question: str, top_k: int = 3) -> dict`	`examples/python/retrieval_basics/main.py`
`forget_document`	skill	`(document_id: str) -> dict`	`examples/python/retrieval_basics/main.py`
`ingest_document`	skill	`(document_id: str, text: str \| None = None, path: str \| None = None) -> dict`	`examples/python/retrieval_basics/main.py`	Index supplied text or a file within the configured document root.

Commands

Taken from this example's own README and module docstrings.

EXAMPLE_MODE=fixture python -m atfgraph.worker --module examples.python.retrieval_basics.main:app
atfg install ./examples/python/retrieval_basics
atfg run retrieval_basics
atfg server start
atfg traverse retrieval_basics.answer_question --in '{"question":"When does the travel desk open?","top_k":3}'
atfg traverse retrieval_basics.forget_document --in '{"document_id":"desk"}'
atfg traverse retrieval_basics.ingest_document --in '{"document_id": "desk", "text": "The travel desk opens at 9am."}'
python -m examples.python.retrieval_basics.call

Files

examples/python/retrieval_basics/README.md
examples/python/retrieval_basics/__init__.py
examples/python/retrieval_basics/agentnode.yaml
examples/python/retrieval_basics/call.py
examples/python/retrieval_basics/main.py
examples/python/retrieval_basics/node.py
examples/python/retrieval_basics/requirements.txt
examples/python/retrieval_basics/support.py

README

Rendered from examples/python/retrieval_basics/README.md; the source file is not modified.

Store documents, retrieve passages with hybrid search, return citations and delete indexed content. Ingest text directly or read local .txt, .md and .rst files.

Run locally

With the SDK installed, run from the repository root:

atfg server start
EXAMPLE_MODE=fixture python -m atfgraph.worker --module examples.python.retrieval_basics.main:app
# In a second terminal:
python -m examples.python.retrieval_basics.call

To manage it as an installed package instead:

atfg install ./examples/python/retrieval_basics
atfg run retrieval_basics

The node.py entrypoint also supports copying this folder outside the checkout. The local server defaults to http://127.0.0.1:18880; its Console shows submitted work at /ui/.

Call with the CLI

atfg traverse retrieval_basics.ingest_document --in '{"document_id": "desk", "text": "The travel desk opens at 9am."}'

Providers

Default fixture mode uses deterministic local data and token hashing rather than a learned embedding provider. It needs no external model/search calls and illustrates mechanics rather than retrieval quality.

Set EXAMPLE_MODE=live plus the model URL/name/key and the full embedding endpoint URL/model/optional key before starting the worker. These use ATFGRAPH_MODEL_* and ATFGRAPH_EMBEDDING_*. Missing settings and live errors are not replaced with fixture answers.

Choose the readable directory through EXAMPLE_DOCUMENT_ROOT, which defaults to this folder. Acceptable files are text, Markdown or reStructuredText, with limits of 1 MB each and 100 files per folder ingestion. Treat their contents as untrusted input; matching citation IDs and quoted text does not establish correctness of the answer.

Python client

from atfgraph import Client

async with Client("http://127.0.0.1:18880") as client:
    result = await client.traverse(
        "retrieval_basics.ingest_document",
        {'document_id': 'desk', 'text': 'The travel desk opens at 9am.'},
        timeout=300,
    )
    print(result)

Once ingestion completes, query the collection and remove a document:

atfg traverse retrieval_basics.answer_question --in '{"question":"When does the travel desk open?","top_k":3}'
atfg traverse retrieval_basics.forget_document --in '{"document_id":"desk"}'