Docs assistant

Directory examples/python/docs_assistant

Index local Markdown, text or reStructuredText documents, then answer questions by planning parallel retrieval and deduplicating passages. Answers carry citations. Collection labels group indexed files; confirmed deletion also removes their vectors.

Agent node label docs_assistant, version 1.0.0.

Capabilities

Capability	Kind	Signature	Module
`clear_namespace`	skill	`(namespace: str, confirm: bool = False) -> dict`	`examples/python/docs_assistant/main.py`
`ingest_folder`	skill	`(folder_path: str = 'sample_docs', namespace: str = 'example-docs') -> dict`	`examples/python/docs_assistant/main.py`
`plan_queries`	traversal	`(question: str) -> dict`	`examples/python/docs_assistant/main.py`
`qa_answer`	traversal	`(question: str, namespace: str = 'example-docs') -> dict`	`examples/python/docs_assistant/main.py`
`retrieve`	skill	`(query: str, namespace: str = 'example-docs', top_k: int = 4) -> list[dict]`	`examples/python/docs_assistant/main.py`

Commands

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

EXAMPLE_MODE=fixture python -m atfgraph.worker --module examples.python.docs_assistant.main:app
atfg install ./examples/python/docs_assistant
atfg run docs_assistant
atfg server start
atfg traverse docs_assistant.clear_namespace --in '{"namespace":"example-docs","confirm":true}'
atfg traverse docs_assistant.ingest_folder --in '{"folder_path": "sample_docs", "namespace": "example-docs"}'
atfg traverse docs_assistant.qa_answer --in '{"question":"When does the travel desk open?","namespace":"example-docs"}'
python -m examples.python.docs_assistant.call

Files

examples/python/docs_assistant/README.md
examples/python/docs_assistant/__init__.py
examples/python/docs_assistant/agentnode.yaml
examples/python/docs_assistant/call.py
examples/python/docs_assistant/main.py
examples/python/docs_assistant/node.py
examples/python/docs_assistant/requirements.txt
examples/python/docs_assistant/sample_docs/getting-started.md
examples/python/docs_assistant/sample_docs/refunds.md
examples/python/docs_assistant/support.py

README

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

Run locally

Use the installed SDK and run these commands from the repository root:

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

Alternatively, install the folder as a managed node package:

atfg install ./examples/python/docs_assistant
atfg run docs_assistant

node.py also supports a copy of this folder outside the checkout. By default, use http://127.0.0.1:18880 and inspect its work in /ui/.

Call with the CLI

atfg traverse docs_assistant.ingest_folder --in '{"folder_path": "sample_docs", "namespace": "example-docs"}'

Providers

Default EXAMPLE_MODE=fixture uses deterministic local data and token-hash vectors. It makes no external model/search calls and demonstrates retrieval mechanics, not learned embedding or answer quality.

For live behavior, set EXAMPLE_MODE=live, model URL/name and any required model key. Also set the full ATFGRAPH_EMBEDDING_URL, embedding model and optional embedding key. Configure them before starting the worker. Missing settings and provider failures remain errors rather than switching to fixtures.

Set EXAMPLE_DOCUMENT_ROOT to the folder the worker may read; it defaults to this example. Accepted types are text, Markdown and reStructuredText, limited to 1 MB per file and 100 files per folder ingestion. Citation checks establish source references and quotes, not the correctness of generated reasoning.

Python client

from atfgraph import Client

async with Client("http://127.0.0.1:18880") as client:
    result = await client.traverse(
        "docs_assistant.ingest_folder",
        {'folder_path': 'sample_docs', 'namespace': 'example-docs'},
        timeout=300,
    )
    print(result)

After the ingestion run completes, query the stored collection:

atfg traverse docs_assistant.qa_answer --in '{"question":"When does the travel desk open?","namespace":"example-docs"}'
atfg traverse docs_assistant.clear_namespace --in '{"namespace":"example-docs","confirm":true}'

Collection namespace labels organize data but do not grant access. Server credentials and memory/knowledge scopes enforce authorization; authorized callers sharing global scope can see its data. Re-ingestion replaces matching paths, but removed files remain indexed until you clear and re-ingest the collection.