@nestbox-ai/cli
Version:
The cli tools that helps developers to build agents
906 lines (878 loc) • 31.2 kB
YAML
"$schema": https://json-schema.org/draft/2020-12/schema
"$id": https://github.com/nestbox-ai/report-generator/report-config.schema.yaml
title: GraphRAG Report Configuration
description: >-
Schema v2.2 for YAML-driven report generation using GraphRAG and LlamaIndex
ReAct Agent. Adds template pipes and document repository downloads.
type: object
required: [schema_version, report, docsets, llamaindex, computations, template]
additionalProperties: false
properties:
schema_version:
type: string
pattern: "^\\d+\\.\\d+(\\.\\d+)?$"
description: Semantic version of the config schema. Use '2.2' for current version.
examples: ["2.2", "2.2.0"]
report:
type: object
description: Report metadata - identifies and describes the report
required: [id, name]
additionalProperties: false
properties:
id:
type: string
minLength: 1
pattern: "^[a-z0-9][a-z0-9_-]*[a-z0-9]$|^[a-z0-9]$"
description: Unique identifier for the report (lowercase, underscores/hyphens allowed)
examples: [shipwell_cfo_kpi_pack_25q4, quarterly_board_report]
name:
type: string
minLength: 1
description: Human-readable report name displayed in outputs
examples: ["Shipwell CFO KPI Pack", "Q4 2025 Board Report"]
description:
type: string
description: Detailed description of the report purpose and scope
examples: ["Quarterly financial KPI extraction from board meeting presentations."]
version:
type: string
description: Report version, typically tied to reporting period
examples: ["2025.Q4", v1.0]
context:
type: object
description: >-
Runtime context variables, policies, and system integration settings.
Variables can be referenced in prompts as {{context.variable_name}}
additionalProperties: true
properties:
company_name:
type: string
description: Company name for prompt substitution
examples: ["Shipwell, Inc."]
currency:
type: string
default: USD
description: Default currency for financial values
examples: [USD, EUR]
source_deck:
type: object
description: Primary source document metadata
additionalProperties: false
properties:
document_id:
type: string
description: Reference to document ID in docsets
title:
type: string
description: Human-readable title of the source
units_policy:
type: string
description: Policy for handling units and normalization
examples: ["Normalize all currency values to USD. Express large values in millions with 'M' suffix."]
answer_quality_policy:
type: object
description: Quality requirements for extracted answers
additionalProperties: false
properties:
numeric_requirements:
type: array
items: { type: string }
description: Requirements for numeric value extraction
labeling_requirements:
type: array
items: { type: string }
description: Requirements for labeling/citation
system_of_record_policy:
type: object
description: Policy for MCP system of record integration
additionalProperties: false
properties:
kpi_namespace:
type: string
description: Namespace for KPI storage
examples: [shipwell.board.25q4]
upsert_granularity:
type: string
enum: [metric_by_period, bulk]
description: Granularity of upsert operations
idempotency_key_template:
type: string
description: Template for generating idempotency keys
examples: ["{{namespace}}:{{metric_id}}:{{period}}"]
value_types:
type: array
items: { type: string }
description: Allowed value type labels
examples: [[currency, percentage, count, ratio]]
prompts:
type: object
description: >-
Custom named prompts that can be referenced throughout the config.
Define prompts here and reference them by name in llamaindex settings
or computation prompts.
additionalProperties:
type: string
minLength: 1
description: "Prompt text. Can contain {{variable}} placeholders."
examples:
- my_system_prompt: "You are a financial analyst extracting KPIs..."
custom_synthesis: "Synthesize the following results into a structured output..."
strict_citation_rules: "Every value MUST have a citation. Never leave citations empty..."
storage:
type: object
description: >-
Storage configuration for resolving document_id references.
Required when using document_id in docs instead of locator.
additionalProperties: false
required: [base_path]
properties:
base_path:
type: string
minLength: 1
description: Base path for resolving document_id references (relative to config file or absolute)
examples: [./documents, ../documents, /data/graphrag]
graphrag_subpath:
type: string
default: graphrag/output
description: Subpath within each document folder to the GraphRAG output
examples: [graphrag/output, output]
doc_repository:
type: object
description: >-
Document repository for automatic artifact downloads. When configured,
documents not found locally will be downloaded from the API and cached.
additionalProperties: false
required: [api_base_url, api_key]
properties:
api_base_url:
type: string
minLength: 1
description: Base URL of the document repository API
examples: ["http://130.211.209.186", "${DOC_REPO_URL}"]
api_key:
type: string
minLength: 1
description: "API key for authentication (supports ${ENV_VAR})"
examples: ["${DOC_REPO_API_KEY}"]
rotation:
type: integer
minimum: 1
default: 200
description: Maximum number of cached documents (FIFO eviction)
mcp:
type: array
description: Model Context Protocol (MCP) server endpoints for external system integration
items: { "$ref": "#/$defs/mcpEndpoint" }
docsets:
type: array
description: Named collections of documents for GraphRAG querying. Each docset groups related documents.
minItems: 1
items: { "$ref": "#/$defs/docset" }
llamaindex:
type: object
description: LlamaIndex ReAct agent configuration - single config for all agent operations
required: [model, api_key]
additionalProperties: false
properties:
model:
type: string
minLength: 1
description: Model identifier for agent operations
examples: [gpt-4o, gpt-4.1-mini, claude-3-5-sonnet]
base_url:
type: string
description: "Custom base URL for API calls (supports ${ENV_VAR})"
examples: ["${OPENAI_BASE_URL:-https://api.openai.com/v1}", "https://api.openai.com/v1"]
api_key:
type: string
minLength: 1
description: "API key (supports ${ENV_VAR} substitution)"
examples: ["${OPENAI_API_KEY}", "${LLAMAINDEX_API_KEY}"]
max_tool_calls:
type: integer
minimum: 1
maximum: 100
default: 20
description: Maximum tool calls per agent execution
examples: [18, 20]
tool_timeout_seconds:
type: integer
minimum: 1
maximum: 600
default: 120
description: Timeout for individual tool calls in seconds
examples: [120, 180]
system_prompt:
type: string
description: >-
Main system prompt for the ReAct agent. Defines the agent's role and behavior.
When omitted, uses default CFO-grade KPI extraction prompt.
examples: ["You are a CFO-grade KPI extraction analyst..."]
autonomous_search_guidance:
type: string
description: >-
Search strategy guidance for autonomous mode. Explains when to use
each search type (basic, local, global, drift). When omitted, uses default guidance.
examples: ["You have access to multiple GraphRAG search tools. Use basic_search for exact text values..."]
synthesis_prompt:
type: string
description: >-
Prompt template for synthesizing multiple subtask results into a final value.
Use {{subtask_results}} placeholder for subtask outputs and {{output_schema}}
for the expected structure.
examples: ["Synthesize these search results into a single structured response matching the schema..."]
validation_repair_prompt:
type: string
description: >-
Prompt template for repairing outputs that fail schema validation.
Use {{raw_response}}, {{validation_errors}}, and {{output_schema}} placeholders.
examples: ["The following response failed validation. Fix the errors and return valid JSON..."]
mcp_system_prompt:
type: string
description: System prompt for MCP integration agent. If not set, uses default MCP prompt.
guardrail_system_prompt:
type: string
description: Default system prompt for guardrail LLM-judge calls. Can be overridden per-guardrail.
json_extraction_prompt:
type: string
description: Prompt for LLM fallback when converting non-JSON agent responses to JSON.
max_agent_iterations:
type: integer
minimum: 1
maximum: 100
default: 30
description: Maximum ReAct agent iterations before stopping.
max_repair_attempts:
type: integer
minimum: 1
maximum: 10
default: 2
description: Maximum schema validation repair attempts before failing.
computations:
type: object
description: Defines what values to extract. Fields produce single values, tables produce rows.
additionalProperties: false
properties:
fields:
type: array
description: "Single-value computations (e.g., Total ARR, Gross Margin)"
items: { "$ref": "#/$defs/fieldComputation" }
tables:
type: array
description: Tabular computations that produce multiple rows
items: { "$ref": "#/$defs/tableComputation" }
template:
type: object
description: "Output template configuration. Uses placeholders like {{field.id.property}} and {{table.id}}"
required: [content]
additionalProperties: false
properties:
format:
type: string
enum: [markdown]
description: Output format (currently only markdown supported)
sections:
type: object
description: Reusable template sections
additionalProperties: { type: string }
content:
type: string
minLength: 1
description: Main template content with placeholders for computed values
guardrails:
type: array
description: LLM-judge validation checks to run on computed outputs
items: { "$ref": "#/$defs/guardrail" }
execution:
"$ref": "#/$defs/executionConfig"
description: Execution settings for retries and output configuration
"$defs":
document:
type: object
description: A reference to a document with GraphRAG output
required: [id]
additionalProperties: false
properties:
id:
type: string
minLength: 1
description: Unique document identifier
examples: [board_deck_pdf, financial_statements]
locator:
type: string
description: >-
Document location. Can be: a filesystem path to GraphRAG output,
'repo:doc-ID' to download from doc_repository, or a bare 'doc-ID'
to check local cache then download.
examples: [/data/graphrag/board_deck/output, "repo:doc-6b3c6cdf", doc-a850ad6f]
document_id:
type: string
description: "Legacy: Document folder ID under storage.base_path (deprecated, use locator)"
examples: [doc-a850ad6f]
description:
type: string
description: Human-readable description
examples: ["Q4 2025 Board Meeting Presentation"]
alias:
type: string
description: Short alias for referencing in prompts
examples: [q4_deck]
docset:
type: object
description: A named collection of documents that can be searched together
required: [id, docs]
additionalProperties: false
properties:
id:
type: string
minLength: 1
description: Unique docset identifier
examples: [shipwell_board_deck_25q4]
description:
type: string
description: Description of what this docset represents
api_key:
type: string
description: >-
API key for OpenAI used by GraphRAG search operations on this docset.
Supports environment variable substitution (e.g., ${OPENAI_API_KEY}).
If not set, falls back to the OPENAI_API_KEY environment variable.
examples: ["${OPENAI_API_KEY}"]
docs:
type: array
minItems: 1
items: { "$ref": "#/$defs/document" }
description: List of documents in this docset
mcpEndpoint:
type: object
description: Configuration for an MCP server endpoint
required: [id, url]
additionalProperties: false
properties:
id:
type: string
minLength: 1
description: Unique identifier for this MCP endpoint
examples: [system_of_record]
type:
type: string
enum: [http, streamable-http, sse, stdio]
default: http
description: MCP transport type
examples: [streamable-http]
url:
type: string
minLength: 1
description: "MCP server URL (supports ${ENV_VAR})"
examples: ["${SOR_MCP_URL}"]
headers:
type: object
description: HTTP headers for authentication
additionalProperties: { type: string }
examples: [{ Authorization: "Bearer ${SOR_MCP_TOKEN}" }]
timeout_seconds:
type: integer
minimum: 1
maximum: 300
default: 30
description: Request timeout in seconds
description:
type: string
description: "Description of this MCP endpoint's purpose"
basicSearchOptions:
type: object
description: Options for basic_search (embedding-based text retrieval)
additionalProperties: false
properties:
chat_model_id:
type: string
description: Model ID for chat completion
examples: [gpt-4o]
embedding_model_id:
type: string
default: text-embedding-3-large
description: Embedding model for semantic search
examples: [text-embedding-3-large, text-embedding-3-small]
prompt:
type: [string, "null"]
description: Custom prompt for search context
k:
type: [integer, "null"]
minimum: 1
maximum: 100
default: 10
description: Number of results to retrieve
localSearchOptions:
type: object
description: Options for local_search (entity/relationship focused)
additionalProperties: false
properties:
chat_model_id:
type: string
description: Model ID for chat completion
embedding_model_id:
type: string
description: Embedding model for entity search
prompt:
type: [string, "null"]
description: Custom prompt for search
text_unit_prop:
type: number
minimum: 0
maximum: 1
description: Proportion of context for text units
community_prop:
type: number
minimum: 0
maximum: 1
description: Proportion of context for community summaries
conversation_history_max_turns:
type: integer
minimum: 0
description: Max conversation history turns
top_k_entities:
type: integer
minimum: 1
default: 10
description: Number of top entities to retrieve
top_k_relationships:
type: integer
minimum: 1
default: 10
description: Number of top relationships to retrieve
max_context_tokens:
type: integer
minimum: 1
description: Maximum tokens for context
globalSearchOptions:
type: object
description: Options for global_search (community-level summaries)
additionalProperties: false
properties:
chat_model_id:
type: string
description: Model ID for chat completion
examples: [gpt-4.1-mini]
knowledge_prompt:
type: [string, "null"]
description: Knowledge context prompt
max_context_tokens:
type: integer
minimum: 1
default: 9000
description: Maximum tokens for context
data_max_tokens:
type: integer
minimum: 1
default: 4500
description: Maximum tokens for data
map_max_length:
type: integer
minimum: 1
default: 1800
description: Maximum length for map phase output
reduce_max_length:
type: integer
minimum: 1
default: 1600
description: Maximum length for reduce phase output
dynamic_search_threshold:
type: integer
minimum: 0
default: 2
description: Threshold for dynamic community search
dynamic_search_keep_parent:
type: boolean
default: true
description: Keep parent community in dynamic search
dynamic_search_num_repeats:
type: integer
minimum: 1
default: 1
description: Number of dynamic search repeats
dynamic_search_use_summary:
type: boolean
default: true
description: Use community summaries in dynamic search
dynamic_search_max_level:
type: integer
minimum: 0
default: 2
description: Maximum level for dynamic search
driftSearchOptions:
type: object
description: Options for drift_search (multi-hop exploration)
additionalProperties: false
properties:
chat_model_id:
type: string
description: Model ID for chat completion
embedding_model_id:
type: string
description: Embedding model for search
prompt:
type: [string, "null"]
description: Custom prompt for search
reduce_prompt:
type: [string, "null"]
description: Custom prompt for reduce phase
data_max_tokens:
type: integer
minimum: 1
description: Maximum tokens for data
concurrency:
type: integer
minimum: 1
description: Concurrent search operations
drift_k_followups:
type: integer
minimum: 1
description: Number of follow-up queries per hop
primer_folds:
type: integer
minimum: 1
description: Number of primer folds
primer_llm_max_tokens:
type: integer
minimum: 1
description: Max tokens for primer LLM
n_depth:
type: integer
minimum: 1
maximum: 5
default: 2
description: Maximum exploration depth (hops)
local_search_text_unit_prop:
type: number
minimum: 0
maximum: 1
description: Text unit proportion for local search
local_search_community_prop:
type: number
minimum: 0
maximum: 1
description: Community proportion for local search
local_search_top_k_mapped_entities:
type: integer
minimum: 1
description: Top K mapped entities for local search
local_search_top_k_relationships:
type: integer
minimum: 1
description: Top K relationships for local search
local_search_max_data_tokens:
type: integer
minimum: 1
description: Max data tokens for local search
local_search_temperature:
type: number
minimum: 0
maximum: 2
description: Temperature for local search
local_search_top_p:
type: number
minimum: 0
maximum: 1
description: Top P for local search
local_search_n:
type: integer
minimum: 1
description: N for local search
searchOptions:
type: object
description: Search options nested under the search type key
additionalProperties: false
properties:
basic_search: { "$ref": "#/$defs/basicSearchOptions" }
local_search: { "$ref": "#/$defs/localSearchOptions" }
global_search: { "$ref": "#/$defs/globalSearchOptions" }
drift_search: { "$ref": "#/$defs/driftSearchOptions" }
oneOf:
- required: [basic_search]
- required: [local_search]
- required: [global_search]
- required: [drift_search]
docsetSubtask:
type: object
description: >-
A subtask that searches a docset and produces intermediate output.
When search_type is omitted, the agent autonomously decides which
search methods to use.
required: [id, prompt, output_schema]
additionalProperties: false
properties:
id:
type: string
minLength: 1
description: Unique subtask identifier
examples: [arr_retention_extract, kpi_arr_retention]
docset_id:
type: string
minLength: 1
description: >-
Bind this subtask to a specific top-level docset. Overrides
computation-level docset_id. When set, search tools are pre-scoped.
examples: [shipwell_board_deck_25q4]
search_type:
type: string
enum: [basic, local, global, drift]
description: >-
Type of GraphRAG search. OPTIONAL - when omitted, agent autonomously
chooses search strategy with access to ALL search tools (basic, local,
global, drift).
examples: [global, basic]
options:
"$ref": "#/$defs/searchOptions"
description: Search options nested under the search type key. Optional when using autonomous mode (no search_type).
prompt:
type: string
minLength: 1
description: Subtask-specific extraction prompt
examples: ["From the ARR & Logo Waterfall slides, extract..."]
output_schema:
type: object
description: "JSON Schema for this subtask's output"
required: [type]
properties:
type: { type: string }
properties: { type: object }
required:
type: array
items: { type: string }
mcpSubtask:
type: object
description: MCP integration subtask with per-MCP prompt
required: [id, prompt]
additionalProperties: false
properties:
id:
type: string
minLength: 1
description: MCP endpoint ID (must match an id in the mcp array)
examples: [system_of_record]
prompt:
type: string
minLength: 1
description: Prompt describing what to do with this MCP endpoint
examples: ["Upsert the KPI rows to the system of record..."]
fieldComputation:
type: object
description: A computation that produces a single structured value
required: [id, label, prompt]
additionalProperties: false
properties:
id:
type: string
minLength: 1
pattern: "^[a-z][a-z0-9_]*$"
description: "Unique computation ID (used in template as {{field.id}})"
examples: [arr_retention_snapshot, net_new_arr]
label:
type: string
minLength: 1
description: Human-readable label for the field
examples: ["ARR & Retention Snapshot", "Net New ARR"]
type:
type: string
default: object
description: Output type hint
examples: [object, number, string]
description:
type: string
description: Detailed description
priority:
type: integer
default: 0
description: Execution priority (lower = earlier)
depends_on:
type: array
items: { type: string, minLength: 1 }
description: IDs of computations this depends on
docset_id:
type: string
minLength: 1
description: >-
Default docset for all subtasks in this computation. Overridden by
subtask-level docset_id. When set, search tools are pre-scoped.
examples: [shipwell_board_deck_25q4]
agents:
type: array
description: Agent subtasks — each spawns a ReAct agent with its own prompt and search tools
items: { "$ref": "#/$defs/docsetSubtask" }
mcp_scope:
type: array
description: Array of MCP subtasks with per-MCP prompts
items: { "$ref": "#/$defs/mcpSubtask" }
prompt:
type: string
minLength: 1
description: Synthesis prompt - combines subtask outputs into final result
examples: ["Return 25Q4 ARR snapshot with citations."]
output_schema:
type: object
description: >-
JSON Schema for the final synthesized output. Only needed for
multi-agent computations where synthesis combines different schemas.
For single-agent computations, the agent's output_schema is used automatically.
properties:
type: { type: string }
properties: { type: object }
required:
type: array
items: { type: string }
tableComputation:
type: object
description: A computation that produces a table with multiple rows
required: [id, title, prompt]
additionalProperties: false
properties:
id:
type: string
minLength: 1
pattern: "^[a-z][a-z0-9_]*$"
description: "Unique computation ID (used in template as {{table.id}})"
examples: [cfo_kpi_export, key_deals]
title:
type: string
minLength: 1
description: Human-readable title for the table
examples: ["CFO KPI Export", "Key Customer Deals"]
description:
type: string
description: Detailed description
priority:
type: integer
default: 0
description: Execution priority (lower = earlier)
depends_on:
type: array
items: { type: string, minLength: 1 }
description: IDs of computations this depends on
docset_id:
type: string
minLength: 1
description: >-
Default docset for all subtasks in this computation. Overridden by
subtask-level docset_id. When set, search tools are pre-scoped.
examples: [shipwell_board_deck_25q4]
agents:
type: array
description: Agent subtasks — each spawns a ReAct agent with its own prompt and search tools
items: { "$ref": "#/$defs/docsetSubtask" }
mcp_scope:
type: array
description: Array of MCP subtasks
items: { "$ref": "#/$defs/mcpSubtask" }
prompt:
type: string
minLength: 1
description: Synthesis prompt - combines subtask outputs into final table
output_schema:
type: object
description: >-
JSON Schema for the final table output. Only needed for multi-agent
computations. For single-agent computations, the agent's output_schema
is used automatically.
properties:
type: { type: string }
properties: { type: object }
required:
type: array
items: { type: string }
guardrail:
type: object
description: LLM-judge validation rule for computed outputs
required: [id, target, on_fail, model, api_key, prompt]
additionalProperties: false
properties:
id:
type: string
minLength: 1
pattern: "^[a-z][a-z0-9_]*$"
description: Unique guardrail identifier
examples: [gr_no_uncited_numbers, gr_arr_math]
target:
type: string
minLength: 1
description: >-
What to validate: 'computations' (all), 'field.{id}' (single field),
'table.{id}' (single table), 'final_report' (rendered report)
examples: [computations, field.arr_retention_snapshot, table.arr_logo_waterfall_history, final_report]
on_fail:
type: string
enum: [error, warn]
description: "Action on failure: 'error' blocks output, 'warn' just reports"
examples: [warn, error]
model:
type: string
minLength: 1
description: Model ID for LLM-judge
examples: [gpt-4.1-mini, gpt-4o]
base_url:
type: string
description: "Custom base URL for guardrail LLM (supports ${ENV_VAR})"
examples: ["${OPENAI_BASE_URL:-https://api.openai.com/v1}"]
api_key:
type: string
minLength: 1
description: "API key for guardrail LLM (supports ${ENV_VAR})"
examples: ["${LLAMAINDEX_API_KEY}"]
prompt:
type: string
minLength: 1
description: "Validation prompt. Use {{content}} placeholder for the value being checked."
examples: ["Enforce that every numeric value includes a citation..."]
system_prompt:
type: string
description: "Custom system prompt for this guardrail's LLM-judge. Overrides llamaindex.guardrail_system_prompt."
description:
type: string
description: Human-readable description of what this guardrail checks
executionConfig:
type: object
description: Execution settings for retries and output configuration
additionalProperties: false
properties:
retries:
type: object
additionalProperties: false
properties:
max_attempts:
type: integer
minimum: 1
maximum: 10
default: 3
description: Maximum retry attempts per computation
backoff_seconds:
type: number
minimum: 0
default: 1.0
description: Seconds to wait between retries
output:
type: object
additionalProperties: false
properties:
directory:
type: string
default: ./output
description: Directory for output files
timestamp_suffix:
type: boolean
default: false
description: Add timestamp to output directory name
include_final_report:
type: boolean
default: true
description: Generate final markdown report
include_computed_json:
type: boolean
default: true
description: Include raw computed values as JSON
include_evidence:
type: boolean
default: true
description: Include search results and evidence
include_guardrails:
type: boolean
default: true
description: Run guardrails and include guardrails.json