xml_tag_guide.md

# XML Tag Structure Guide

## Root Element
- `<agent_response>` - Root element containing all response data

## Primary Response Types
1. `<thought>` - Agent's reasoning and analysis process
   - Contains the agent's internal thinking process
   - May appear empty (`<thought />`) during processing
   - Can contain full text analysis and reasoning

2. `<message>` - Direct agent messages/responses
   - Contains user-facing messages
   - May appear empty (`<message />`) during processing
   - Can be partial messages during streaming
   - Often contains markdown formatting
   - Common patterns:
     ```xml
     <!-- Empty message -->
     <agent_response><message /></agent_response>
     
     <!-- Partial message during streaming -->
     <agent_response><message>partial response</message></agent_response>
     
     <!-- Complete message -->
     <agent_response><message>complete response with markdown **formatting**</message></agent_response>
     
     <!-- Message with line breaks -->
     <agent_response><message>multi-line
     response with
     breaks</message></agent_response>
     ```
   - Used for:
     - Direct responses to user queries
     - Status updates during processing
     - Incremental output during streaming
     - Formatted text with markdown
     - Multi-line responses
     - Interactive prompts and questions

3. `<error>` - Error messages and notifications
   - Contains error details when something goes wrong
   - Used for both system and processing errors

## Observation Structure
- `<observation>` - Contains tool outputs and analysis results
  - May appear empty (`<observation />`) during processing
  - `<tools>` - Container for all tool outputs
    - `<tool name="[tool_name]">` - Individual tool output container
      - Required attribute: `name` matching ToolType constants

## Tool-Specific Tags

### Census Data (`get_census_data`)
- `<census_tracts>` - Container for census tract data
  - May appear empty if no tract data
  - `<tract id="[tract_id]">` - Individual census tract
    - Required attribute: `id` with tract identifier
    - `<population>` - Population statistics
    - `<income>` - Income statistics
    - `<demographics>` - Demographic information
    - Additional dynamic fields based on census data

### Mermaid Diagrams (`mermaid_diagram`)
- `<diagram>` - Contains the cleaned mermaid diagram code
  - Contains raw mermaid syntax without markdown backticks

### Health Data Tools
Common structure for WISQARS, WONDER, NCHS tools:
- `<tool name="wisqars|wonder|nchs">` - Health data container
  - Dynamic category elements based on data structure
  - Nested elements for hierarchical data

### Generic Tool Output
For tools like DuckDuckGo, Reddit News, PubMed, etc:
- `<content>` - Contains cleaned, formatted tool output text
  - Markdown formatting removed
  - Code blocks cleaned
  - Whitespace normalized

## Streaming Response Pattern
Responses typically come in this sequence:

1. Initial empty thought:
```xml
<agent_response><thought /></agent_response>
```

2. Message chunks (multiple):
```xml
<agent_response><message>I</message></agent_response>
<agent_response><message>'ll help you analyze</message></agent_response>
<agent_response><message>the data.</message></agent_response>
```

3. Empty message marker:
```xml
<agent_response><message /></agent_response>
```

4. Thought statement:
```xml
<agent_response><thought>Complete thought statement</thought></agent_response>
```

5. Thought with observation (when using tools):
```xml
<agent_response>
  <thought>Complete thought statement</thought>
  <observation>
    <tools>
      <tool name="get_census_data">
        <census_tracts />
        <content>{"llmresult": "tool output data"}</content>
      </tool>
    </tools>
  </observation>
</agent_response>
```

6. Empty thought transition:
```xml
<agent_response><thought /></agent_response>
```

7. Final message chunks:
```xml
<agent_response><message>Final analysis</message></agent_response>
<agent_response><message>and conclusions.</message></agent_response>
<agent_response><message /></agent_response>
```

Each chunk is prefixed with `data: ` in the stream and represents a single step in the response generation process. Messages are often split into smaller chunks for streaming, while thoughts and observations typically come as complete units.

## Supported Tool Types
- `duckduckgo_search` - Web search results
- `reddit_x_gnews_newswire_crunchbase` - News and social media data
- `pubmed_search` - Medical research papers
- `get_census_data` - Census statistics
- `heatmap_code` - Visualization code
- `mermaid_diagram` - Diagram generation
- `wisqars` - Injury statistics
- `wonder` - CDC Wonder database
- `nchs` - National Center for Health Statistics
- `onestep` - One-step analysis
- `dqs_nhis_adult_summary_health_statistics` - Health statistics


EXAMPLE OUTPUT:

(base) bdillon@YAM-GWLGVJQVCF cc-api % 
curl -X POST https://merry-contrast-substantially-initiative.trycloudflare.com/v1/agent \
-H "Content-Type: application/json" \
-d '{
  "query": "Show me the number of elderly (over 70) fall injuries in Illinois",
  "stream": true,
  "inputs": {},
  "files": [],
  "user": "default_user",
  "response_mode": "streaming"
}'

data: <agent_response><thought /></agent_response>

data: <agent_response><message>I</message></agent_response>

data: <agent_response><message>'ll help you analyze elderly fall injuries in Illinois using</message></agent_response>

data: <agent_response><message>multiple data sources and create a comprehensive visualization of</message></agent_response>

data: <agent_response><message>the findings.

1. First, let's</message></agent_response>

data: <agent_response><message>get census data for Illinois (FIPS code: 17</message></agent_response>

data: <agent_response><message>):</message></agent_response>

data: <agent_response><message /></agent_response>

data: <agent_response><thought>I'll help you analyze elderly fall injuries in Illinois using multiple data sources and create a comprehensive visualization of the findings.

1. First, let's get census data for Illinois (FIPS code: 17):</thought></agent_response>

data: <agent_response><thought>I'll help you analyze elderly fall injuries in Illinois using multiple data sources and create a comprehensive visualization of the findings.

1. First, let's get census data for Illinois (FIPS code: 17):</thought><observation><tools><tool name="get_census_data"><census_tracts /><content>{"llmresult": "Bulleted List:\n\n Census Tract 9005:  A high percentage (1.7%) of residents have ambulatory difficulty.\n Census Tract 101: A high percentage (1.0%) of residents have ambulatory difficulty.\n Census Tract 4008: A high percentage (1.0%) of residents have ambulatory difficulty.\n Census Tract 102: A high percentage (0.9%) of residents have ambulatory difficulty.\n Census Tract 8808: A high percentage (0.9%) of residents have ambulatory difficulty.\n\n\nNumbered Summary:\n\n1. Census Tract 9005: 4347 residents with ambulatory difficulty (1.7%), $58,828 median income.\n2. Census Tract 101: 3733 residents with ambulatory difficulty (1.0%), $54,120 median income.\n3. Census Tract 4008: 4783 residents with ambulatory difficulty (1.0%), $71,574 median income.\n4. Census Tract 102: 3306 residents with ambulatory difficulty (0.9%), $70,107 median income.\n5. Census Tract 8808: 3318 residents with ambulatory difficulty (0.9%), $71,563 median income.\n\n\nJSON Summary:\n\n\n"}tool response: {"llmresult": "Bulleted List:\n\n Census Tract 9005:  A high percentage (1.7%) of residents have ambulatory difficulty.\n Census Tract 101: A high percentage (1.0%) of residents have ambulatory difficulty.\n Census Tract 4008: A high percentage (1.0%) of residents have ambulatory difficulty.\n Census Tract 102: A high percentage (0.9%) of residents have ambulatory difficulty.\n Census Tract 8808: A high percentage (0.9%) of residents have ambulatory difficulty.\n\n\nNumbered Summary:\n\n1. Census Tract 9005: 4347 residents with ambulatory difficulty (1.7%), $58,828 median income.\n2. Census Tract 101: 3733 residents with ambulatory difficulty (1.0%), $54,120 median income.\n3. Census Tract 4008: 4783 residents with ambulatory difficulty (1.0%), $71,574 median income.\n4. Census Tract 102: 3306 residents with ambulatory difficulty (0.9%), $70,107 median income.\n5. Census Tract 8808: 3318 residents with ambulatory difficulty (0.9%), $71,563 median income.\n\n\nJSON Summary:\n\n\n"}.</content></tool></tools></observation></agent_response>

data: <agent_response><thought /></agent_response>

data: <agent_response><message>Let</message></agent_response>

data: <agent_response><message>me query the WISQARS dataset</message></agent_response>

data: <agent_response><message>specifically for fall injuries:</message></agent_response>

data: <agent_response><message /></agent_response>

data: <agent_response><thought>Let me query the WISQARS dataset specifically for fall injuries:</thought></agent_response>

data: <agent_response><thought>Let me query the WISQARS dataset specifically for fall injuries:</thought><observation /></agent_response>

data: <agent_response><thought /></agent_response>

data: <agent_response><message>Let</message></agent_response>

data: <agent_response><message>me analyze the fall injuries data for elderly</message></agent_response>

data: <agent_response><message>individuals in Illinois by combining census data an</message></agent_response>

data: <agent_response><message>d WISQARS fall injury data. I'll create</message></agent_response>

data: <agent_response><message>a comprehensive visualization to help understand the distribution.</message></agent_response>

data: <agent_response><message /></agent_response>

data: <agent_response><thought>Let me analyze the fall injuries data for elderly individuals in Illinois by combining census data and WISQARS fall injury data. I'll create a comprehensive visualization to help understand the distribution.</thought></agent_response>

data: <agent_response><thought>Let me analyze the fall injuries data for elderly individuals in Illinois by combining census data and WISQARS fall injury data. I'll create a comprehensive visualization to help understand the distribution.</thought><observation /></agent_response>

data: <agent_response><thought /></agent_response>

data: <agent_response><message>Based on the data</message></agent_response>

data: <agent_response><message>collected, I can provide an analysis of elderly</message></agent_response>

data: <agent_response><message>fall injuries and ambulatory difficulties in Illinois:</message></agent_response>

data: <agent_response><message>1. **Census Data Analysis**</message></agent_response>

data: <agent_response><message>- The highest concentration of ambulatory difficulty is</message></agent_response>

data: <agent_response><message>in Census Tract 9005 with 1.7</message></agent_response>

data: <agent_response><message>% of residents affected
- Four other</message></agent_response>

data: <agent_response><message>tracts show significant ambulatory difficulty rates ranging</message></agent_response>

data: <agent_response><message>from 0.9% to 1.</message></agent_response>

data: <agent_response><message>0%
- There's a correlation between areas with higher ambulatory difficulty</message></agent_response>

data: <agent_response><message>and moderate median incomes ($54,120-</message></agent_response>

data: <agent_response><message>$71,574)

2. **Key</message></agent_response>

data: <agent_response><message>Findings by Census Tract**:
   -</message></agent_response>

data: <agent_response><message>Tract 9005: 4</message></agent_response>

data: <agent_response><message>,347 residents with disabilities (highest concentration</message></agent_response>

data: <agent_response><message>)
   - Tract 4008: 4,</message></agent_response>

data: <agent_response><message>783 residents with disabilities
   - Tract</message></agent_response>

data: <agent_response><message>101: 3,733 residents with disabilities</message></agent_response>

data: <agent_response><message>- Tract 102: 3,</message></agent_response>

data: <agent_response><message>306 residents with disabilities
   - Tract</message></agent_response>

data: <agent_response><message>8808: 3,318</message></agent_response>

data: <agent_response><message>residents with disabilities

3. **Risk</message></agent_response>

data: <agent_response><message>Factors**:
   - Higher concent</message></agent_response>

data: <agent_response><message>rations of elderly populations in specific census tracts
   -</message></agent_response>

data: <agent_response><message>Varying income levels that may affect access to prevent</message></agent_response>

data: <agent_response><message>ive care
   - Geographic distribution showing</message></agent_response>

data: <agent_response><message>clusters of high-risk areas

4.</message></agent_response>

data: <agent_response><message>**Visualization**:
I've include</message></agent_response>

data: <agent_response><message>d a pie chart showing the distribution of ambulatory difficulty percentages across the top</message></agent_response>

data: <agent_response><message>census tracts in Illinois.

```mermaid
pie</message></agent_response>

data: <agent_response><message>title Illinois Census Tracts -</message></agent_response>

data: <agent_response><message>Ambulatory Difficulty Distribution
    "Tract</message></agent_response>

data: <agent_response><message>9005 (1.7%)</message></agent_response>

data: <agent_response><message>": 31
    "Tract</message></agent_response>

data: <agent_response><message>101 (1.0%)": 18</message></agent_response>

data: <agent_response><message>"Tract 4008 (</message></agent_response>

data: <agent_response><message>1.0%)": 18
    "Tract</message></agent_response>

data: <agent_response><message>102 (0.9%)":</message></agent_response>

data: <agent_response><message>16
    "Tract 8808</message></agent_response>

data: <agent_response><message>(0.9%)": 16
```

5. **</message></agent_response>

data: <agent_response><message>Recommendations for Fall Prevention**:
   - Focus</message></agent_response>

data: <agent_response><message>resources on Census Tract 9005,</message></agent_response>

data: <agent_response><message>which shows the highest concentration of ambulatory difficulties</message></agent_response>

data: <agent_response><message>- Implement targeted intervention programs in areas</message></agent_response>

data: <agent_response><message>with higher elderly populations
   - Consider income levels</message></agent_response>

data: <agent_response><message>when designing accessibility and support services

To</message></agent_response>

data: <agent_response><message>get more specific data about fall injuries, I</message></agent_response>

data: <agent_response><message>recommend:
1. Consulting local healthcare</message></agent_response>

data: <agent_response><message>facilities for actual fall incident reports
2. Working</message></agent_response>

data: <agent_response><message>with senior living communities in these</message></agent_response>

data: <agent_response><message>census tracts
3. Conducting</message></agent_response>

data: <agent_response><message>detailed assessments of environmental factors in high-risk areas</message></agent_response>

data: <agent_response><message>Would you like more detailed information about any specific aspect of this</message></agent_response>

data: <agent_response><message>analysis or additional data about particular census tracts?</message></agent_response>

data: <agent_response><message /></agent_response>

data: <agent_response><thought>Based on the data collected, I can provide an analysis of elderly fall injuries and ambulatory difficulties in Illinois:

1. **Census Data Analysis**
- The highest concentration of ambulatory difficulty is in Census Tract 9005 with 1.7% of residents affected
- Four other tracts show significant ambulatory difficulty rates ranging from 0.9% to 1.0%
- There's a correlation between areas with higher ambulatory difficulty and moderate median incomes ($54,120-$71,574)

2. **Key Findings by Census Tract**:
   - Tract 9005: 4,347 residents with disabilities (highest concentration)
   - Tract 4008: 4,783 residents with disabilities
   - Tract 101: 3,733 residents with disabilities
   - Tract 102: 3,306 residents with disabilities
   - Tract 8808: 3,318 residents with disabilities

3. **Risk Factors**:
   - Higher concentrations of elderly populations in specific census tracts
   - Varying income levels that may affect access to preventive care
   - Geographic distribution showing clusters of high-risk areas

4. **Visualization**:
I've included a pie chart showing the distribution of ambulatory difficulty percentages across the top census tracts in Illinois.

```mermaid
pie
    title Illinois Census Tracts - Ambulatory Difficulty Distribution
    "Tract 9005 (1.7%)": 31
    "Tract 101 (1.0%)": 18
    "Tract 4008 (1.0%)": 18
    "Tract 102 (0.9%)": 16
    "Tract 8808 (0.9%)": 16
```

5. **Recommendations for Fall Prevention**:
   - Focus resources on Census Tract 9005, which shows the highest concentration of ambulatory difficulties
   - Implement targeted intervention programs in areas with higher elderly populations
   - Consider income levels when designing accessibility and support services

To get more specific data about fall injuries, I recommend:
1. Consulting local healthcare facilities for actual fall incident reports
2. Working with senior living communities in these census tracts
3. Conducting detailed assessments of environmental factors in high-risk areas

Would you like more detailed information about any specific aspect of this analysis or additional data about particular census tracts?</thought></agent_response>