Ingest API¶
Interactive API reference for graffold-ingest. Covers all REST endpoints and the full CLI.
CLI Reference¶
Setup Commands¶
| Command | Description |
|---|---|
graffold-ingest init |
One-time setup — creates ~/.graffold/config.toml with defaults |
graffold-ingest status |
Verify installation, config, and connectivity |
Pipeline Commands¶
| Command | Description |
|---|---|
graffold-ingest ingest <dir> |
One-shot ingest of a program directory (uses config defaults) |
graffold-ingest pipeline |
Full pipeline with explicit options (source, service, publish mode) |
graffold-ingest watch |
Daemon — watches for new/changed files, incremental by default |
graffold-ingest scrape |
Quick scrape a single URL |
Query Commands (local Parquet)¶
| Command | Description |
|---|---|
graffold-ingest ask <question> |
Natural language query via DRIFT search over Parquet |
graffold-ingest context <disease> |
Generate prior-knowledge.md for Atlas's next run |
graffold-ingest query |
Full query with format/output options |
graffold-ingest trajectory |
Show full history of a specific target across runs |
Remote KG Commands (hosted graphs)¶
Query the same hosted graphs the webapp uses, over the API, with a bearer key — CLI/webapp parity. Authenticate once with login (stores the key in ~/.graffold/config.toml) or set GRAFFOLD_API_KEY.
graffold-ingest login <api-key> # get a key from Admin → API & Query
graffold-ingest kg graphs # list hosted graphs you can query
| Command | Description |
|---|---|
graffold-ingest kg graphs |
List the hosted graphs you can query |
graffold-ingest kg coverage <entities> |
Which of the comma-separated entities exist in the graph |
graffold-ingest kg validate <targets> |
Score candidate targets by graph support |
graffold-ingest kg evidence |
Evidence + contradiction flags for a claim |
graffold-ingest kg prior-knowledge <disease> |
Prior-knowledge document from the hosted graph |
graffold-ingest kg kills |
Targets killed / not-re-proposed, with reasons |
graffold-ingest kg trajectory <target> |
Full history of a target across the graph |
graffold-ingest kg predictions |
Structural novel predictions (shared-neighbor inference) |
graffold-ingest kg gaps |
Targets mentioned but lacking validated evidence |
graffold-ingest kg stats <graph> |
Entity/relationship counts + type breakdown |
The login key is sent as a per-request Authorization: Bearer header (not a session); GRAFFOLD_API_KEY overrides the stored key, and --url overrides the default https://api.graffold.com.
Schema Commands¶
| Command | Description |
|---|---|
graffold-ingest schema |
Print the current extraction schema |
graffold-ingest discover |
Auto-generate a domain schema from sample data |
graffold-ingest validate |
Validate a schema YAML file |
graffold-ingest refine |
Refine schema based on extraction feedback |
Utility Commands¶
| Command | Description |
|---|---|
graffold-ingest deploy |
Load a Parquet graph into a served backend (FalkorDB/Neo4j/Neptune/Spanner) as a named graph |
graffold-ingest serve |
Start the REST API server |
graffold-ingest tui |
Interactive terminal UI |
graffold-ingest export |
Export graph to CSV/JSON/Parquet |
graffold-ingest audit |
Run quality audit on a program's graph |
pipeline options¶
--source web | pdf | api | csv | database | agteria | pubmed | europepmc (required)
--url URL for web/api sources
--path Local path for pdf/csv/database/agteria
--query Search query (pubmed / europepmc)
--limit Max papers to fetch (pubmed / europepmc)
--full-text Europe PMC: fetch OA full text (vs --abstract)
--service bedrock | bedrock-llama | anthropic | openai | ollama | cloudflare | openrouter
--publish neo4j | parquet | dual
--parquet-dir Output directory for parquet files
--resolve Enable entity resolution (default: on)
--no-resolve Skip entity resolution
--direct Agteria: use regex-only extraction (skip LLM)
# Literature examples
graffold-ingest pipeline --source europepmc --query "F18 ETEC adhesion" --full-text --limit 50 --service bedrock-llama
graffold-ingest pipeline --source pubmed --query "post-weaning diarrhea" --limit 100 --service bedrock-llama
watch options¶
--poll Seconds between filesystem checks (default: 60)
--llm / --no-llm Enable/disable LLM extraction (default: on)
--resolve / --no-resolve Entity resolution (default: on)
--chunks Max chunks per run (default: unlimited)
--parquet-dir Output directory
query options¶
<disease> Query string (positional)
--graph Path to parquet directory
-o, --output Write answer to file
--fmt Output format: text | json | markdown
discover options¶
--domain Domain description (e.g. "veterinary drug discovery")
--from-file Sample document to analyze
--from-url Sample URL to analyze
--service LLM service for schema generation
-o, --output Write schema to file
--tenant Tenant ID
--project Project ID
audit options¶
<program-dir> Path to Atlas program directory (positional)
--graph Path to parquet directory
-o, --output Write audit report to file
init options¶
--llm-service Default LLM service (default: anthropic)
--graph-backend Default graph backend (default: neo4j)
--parquet-dir Default parquet output dir (default: ~/.graffold/parquet)
Creates ~/.graffold/config.toml with sensible defaults. Re-run to reconfigure.
status¶
No options. Checks:
- Config file exists and is valid
- LLM service is reachable
- Graph backend is connectable
- Parquet directory is writable
ingest options¶
<program-dir> Path to Atlas program directory (positional, required)
--llm / --no-llm Enable LLM extraction (default: from config)
--resolve / --no-resolve Entity resolution (default: from config)
--chunks Max chunks to process (default: all)
context options¶
<disease> Disease/program name (positional, required)
--graph Path to parquet directory (default: from config)
--program-dir Write prior-knowledge.md here (default: cwd)
ask options¶
<question> Natural language question (positional, required)
--graph Path to parquet directory (default: from config)
--mode auto | drift | global | local (default: auto)
--verify Verify claims against graph (default: true)
scrape options¶
<url> URL to scrape (positional, required)
--service LLM service (default: bedrock)
--depth Crawl depth (default: 1)
serve options¶
export options¶
--format parquet | jsonl | tsv | duckdb (default: parquet)
--output Output file or directory
--database-uri Source graph URI (default: bolt://localhost:7687)
--limit Max entities to export (default: all)
validate options¶
Exits 0 if valid, 1 with error details if not.
refine options¶
<path> Path to existing schema YAML (positional, required)
--feedback What to change (e.g. "add Drug entity type")
--service LLM service for refinement
--tenant Tenant ID
--project Project ID
trajectory options¶
<target_name> Target name to trace (positional, required)
--graph Path to parquet directory (default: from config)
Shows all mentions of a target across runs: when it was proposed, validated, killed, or revived.
tui¶
No options. Launches an interactive terminal UI (Textual-based) for browsing the graph, running queries, and viewing pipeline status.
deploy options¶
<graph-dir> Parquet directory — reads the latest harmonized snapshot (required)
--backend falkordb | neo4j | neptune | spanner (default: falkordb)
--graph Named graph = the kg_id Atlas queries (default: dir name)
--host Target DB host
--port Target DB port (0 = backend default)
Loads a program's graph into a served backend as an isolated named graph. See Serving the KG to Atlas for the full deploy → serve → query workflow and the /v1/atlas/* endpoint reference.