Lets the agent write to KB / DB / Graph during a conversation. Turns DataMind from a read-only retrieval agent into a working assistant.

Tool catalog

Tool	What it does
kb_add_file	Single file → chunk → embed → upsert to Chroma, immediately searchable via kb_search
kb_add_path	Recursively walks a directory (or accepts a single file) for batch ingest
db_import_csv	CSV → infer schema → CREATE TABLE → INSERT, with append / replace / fail modes
graph_add_triples_from_text	Free-form text → LLM extracts (subject, relation, object) → upsert to graph + persist

All four belong to the ingest group. They register into the same ToolRegistry everything else uses, and surface under "数据导入 (ingest)" in the system-prompt grouping.

Tools are registered into the ingest or workspace groups and filtered by the StoreAgent / RetrieveAgent access boundary. Write tools are exposed to StoreAgent; read and build-verification tools can also be exposed to RetrieveAgent.

Unified workspace builds

For a workspace containing documents, tables, code, and other files, use this flow:

Tool	Purpose
workspace_inspect	Read-only inventory of file types, sizes, hashes, and candidate surfaces
surface_ingest_path	Routes documents to KB, tables to SQL, and file relations to the lineage Graph
raw_file_read	Reads paginated source or extracted document evidence with SHA-256
graph_build_lineage	Builds contains, mentions, version_of, shared_artifact, and explicit depends_on relations
build_start	Creates a build run and captures the source inventory
build_status	Reports build state and verifies frozen artifacts
build_freeze	Records hashes for DataMind artifacts
build_verify	Checks whether frozen artifacts changed
build_export	Exports verified KB, SQL, and Graph artifacts

Recommended order:

build_start → workspace_inspect → surface_ingest_path → build_freeze
                                      ↓
                         build_status / build_verify / build_export

Supported document formats include PDF, DOCX, PPTX, DOC, PPT, Markdown, TXT, HTML, JSON, XML, Python, and Java; CSV, TSV, and XLSX are imported into SQL. PDF extraction tries the MinerU Hosted API first and falls back to pypdf on missing configuration, timeout, API failure, or empty output. Set DATAMIND_MINERU=off to force pypdf only.

How to use it

1. Conversational (recommended)

you   → "add /Users/foo/policy.md to the KB"
agent → calls kb_add_file(path="/Users/foo/policy.md")
        ✓ 1 chunk added, retrievable now

you   → "import /Users/foo/sales-q2.csv as table sales_q2"
agent → calls db_import_csv(path=..., table="sales_q2", if_exists="append")
        ✓ 18 rows inserted, queryable now

you   → "陈诚 was promoted to Tech Lead, reports to Ann, owns Project Kepler"
agent → calls graph_add_triples_from_text(text="...")
        ✓ extracted 3 triples and upserted them

2. Browser drag-and-drop

Open http://127.0.0.1:8000. Above the input there's a "📎 drop files here" zone:

1. Drop any .md / .txt / .csv file
2. Backend POST /api/upload saves it to data/profiles/<profile>/uploads/<filename>
3. The file appears in the list below the dropzone with an 导入 button
4. Clicking it builds a prompt based on extension (.csv → "import as table", .md/.txt → "add to KB") and sends it to the agent
5. Agent picks the right ingest tool autonomously

The backend dedups by content hash so repeated uploads of the same name don't pollute storage.

3. Programmatic

agent = await build_agent(settings)
res = await agent.ingest.kb_add_file(path="/path/to/file.md")
res = await agent.ingest.db_import_csv(
    path="/path/to/data.csv", table="customers", if_exists="replace"
)
res = await agent.ingest.graph_add_triples_from_text(
    text="Alice leads the Search team."
)

Useful for batch loaders or scheduled jobs.

Path safety

IngestService maintains an allow-list that includes by default:

• The active profile's data_dir
• The current working directory
• Cwd's parent (lets you keep demo data in a sibling like ~/Desktop/DataMind/demo-uploads/)
• The system temp directory (tempfile.gettempdir())
• /tmp and /private/tmp (macOS-specific aliases)

Paths are Path.resolve()d before the prefix check, so symlinks can't escape. Add more roots via IngestService(..., allowed_roots=[...]) when needed.

There's also a basename fallback: if the user just says "add the file foo.md", the service looks under <profile>/uploads/foo.md. This lets the drag-drop UI work without ever showing a full path to the agent.

De-duplication

KB chunk ids are SHA1(text, source). Re-ingesting the same content yields the same id, so Chroma upsert is a no-op — no duplicate storage.

Error handling

• During a directory ingest (kb_add_path), one bad file doesn't abort the rest
• CSV import errors (illegal table name, empty file, SQL error) raise CapabilityError("ingest", ...) with a friendly message, surfaced to the user via the agent
• Triple extraction failures (empty result, malformed JSON) return {"triples_added": 0, "raw_response": "..."} instead of throwing

Plays well with others

you:   import /tmp/customers.csv as table customers
agent: db_import_csv → ✓ table created

you:   what's the total ARR for Enterprise-tier customers?
agent: db_query_nl → db_query_sql → returns numbers

you:   who's the CSM owning the 鼎元金融 account?
agent: db_query_sql → "Leo"
agent: graph_search_entities("Leo") → "in Operations dept"

Data ingested mid-conversation is exposed by the same ToolRegistry to every subsequent turn — zero seam.

See also

• Install §7a — Conversational ingest
• Demo §7 — Ingest demo
• Architecture overview