Context Scope

Context Scope controls data visibility and flow between actions—selecting which upstream namespaces an action can read from the record, what passes through to output, and what gets excluded.

:::warning Required context_scope is required on every action. Omitting it raises a ConfigurationError. Every action must declare its data dependencies explicitly via observe, passthrough, or drop. :::

Directives

Directive	Purpose	In LLM Context	In Output
observe	Include specific fields in LLM context	Yes	No
drop	Exclude specific fields from context	No	No
passthrough	Forward fields directly to output	No	Yes

Syntax

yaml

YAML

context_scope:
  observe:
    - upstream_action.field_name
    - another_action.nested.field
  drop:
    - source.unused_field
    - upstream_action.internal_field
  passthrough:
    - upstream_action.preserve_this
    - source.metadata

Observe Directive

The observe directive selects which upstream namespaces and fields are visible to the action. When specified, only listed namespaces are included in the LLM context.

yaml

YAML

- name: Cluster_Validation_Agent
  dependencies: [group_by_similarity, cluster_list]
  context_scope:
    observe:
      - canonicalize_facts.candidate_facts_list
      - cluster_list.semantic_unique_id
      - group_by_similarity.num_similar_facts
      - source.page_content  # Can include source data

Drop Directive

The drop directive excludes fields from the LLM context. All other fields are included unless observe is also specified.

yaml

YAML

- name: fact_extractor
  context_scope:
    drop:
      - source.syllabus    # Reference data not needed
      - source.url         # URL not relevant

Passthrough Directive

The passthrough directive forwards fields directly to the action output without including them in the LLM context. Data flows around the LLM rather than through it.

yaml

YAML

- name: Cluster_Validation_Agent
  context_scope:
    observe:
      - canonicalize_facts.candidate_facts_list
    passthrough:
      - group_by_similarity.grouped_facts   # Forward without LLM seeing
      - source.url                          # Preserve for downstream

Seed Data

Static reference data can be loaded via seed_path. See Seed Data for details.

yaml

YAML

defaults:
  context_scope:
    seed_path:
      exam_syllabus: $file:syllabus.json
  data_source:
    type: local
    folder: ./staging
    file_type: [json]
  reprompt:
    on_schema_mismatch: reprompt
    max_attempts: 3
  batch_max_workers: 6

Note: data_source, reprompt, and batch_max_workers are workflow-level defaults that can also appear in the defaults: block. They are documented in Defaults and Run Modes.

Version Field Patterns

When consuming outputs from version actions, field names are prefixed to avoid collisions. Use wildcard syntax to reference all iterations:

yaml

YAML

- name: extract_raw_qa
  versions:
    range: [1, 3]

- name: flatten_questions
  dependencies: [extract_raw_qa]
  context_scope:
    observe:
      - extract_raw_qa.*  # Matches extract_raw_qa_1_*, extract_raw_qa_2_*, etc.

See Version Actions for complete documentation.

Auto-Inferred Context Dependencies

Actions referenced in context_scope but not in dependencies are automatically treated as context dependencies. These are loaded from record namespaces with lineage matching.

yaml

YAML

- name: generate_report
  dependencies: [extract_data]  # Primary input source
  context_scope:
    observe:
      - extract_data.*         # From input files
      - enrich_data.*          # Auto-inferred: loaded from record namespaces
      - validate_data.*        # Auto-inferred: loaded from record namespaces

How it works:

1. extract_data is in dependencies → its output files are processed as input
2. enrich_data and validate_data are only in context_scope → auto-inferred as context dependencies
3. Context dependencies are loaded from record namespaces, matched by lineage to ensure data from the same record flow

This is especially useful for fan-in patterns where multiple upstream actions feed into one action:

yaml

YAML

- name: final_action
  dependencies: [action_A, action_B, action_C]  # Fan-in pattern
  context_scope:
    observe:
      - action_A.*   # Primary input (first in list)
      - action_B.*   # Context dependency (lineage-matched)
      - action_C.*   # Context dependency (lineage-matched)

Resolution Order

1. Observe filter - If observe is specified, start with only those fields
2. Drop filter - Remove any fields in drop list
3. Passthrough merge - After LLM processing, merge passthrough fields into output

Passthrough fields never enter the LLM context—they join the output after processing.

Best Practices

1. Use observe for focus: When LLM needs only specific fields
2. Use drop for noise reduction: When most fields are needed but some aren't
3. Use passthrough for data lineage: Preserve data that downstream actions need

Combined Example

yaml

YAML

- name: generate_explanation
  context_scope:
    observe:
      - generate_summary.summary    # LLM needs this
    passthrough:
      - source.url                  # Preserve for downstream
    drop:
      - upstream.debug_info         # Internal, not needed

Debugging Context

Enable prompt_debug to see the rendered context:

yaml

YAML

- name: my_action
  prompt_debug: true

See Also

• Version Actions - Loop configuration and consumption patterns
• Field References - Field reference syntax and validation
• Seed Data - Loading static reference data