# How the `ai_context` Field Functions for AI Tools Consuming Apache OSSIE Models

> Discover how the ai_context field in Apache OSSIE models provides AI-specific metadata for LLM converters. Gain fine-grained control over AI behavior without changing converter logic.

- Repository: [The Apache Software Foundation/ossie](https://github.com/apache/ossie)
- Tags: how-to-guide
- Published: 2026-07-26

---

**The `ai_context` field (implemented as the `aicontext` attribute in the source code) is an optional `Dict[str, Any]` in Apache OSSIE models that supplies AI-specific metadata—such as system prompts, example inputs/outputs, and retrieval URLs—to LLM converters during the model-to-artifact transformation, enabling fine-grained control over AI behavior without modifying converter logic.**

The Apache OSSIE (Open Source Semantic Integration Engine) repository provides a semantic modeling framework where the `ai_context` field serves as a bridge between structured data models and AI consumption pipelines. Defined in the core Model dataclass at [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py), this free-form dictionary allows model authors to embed instructions specifically for language models. Downstream converters, such as Wisdom and Omni, inspect this field during the conversion process to inject contextual information into generated prompts.

## Core Definition: The `ai_context` Schema in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py)

The `ai_context` functionality is implemented as the `aicontext` attribute within the base Model class. It accepts any dictionary structure, giving model authors flexibility to define AI-specific instructions.

```python

# File: python/src/ossie/models.py

from dataclasses import dataclass, field
from typing import Dict, Any, List

@dataclass
class Model:
    name: str
    version: str
    description: str = ""
    # ... other OSSIE fields ...

    # AI-specific context field

    aicontext: Dict[str, Any] = field(default_factory=dict)

```

When instantiating a model programmatically, authors populate this dictionary with keys that their target AI tools recognize.

```python

# Example: Populating ai_context for an LLM converter

my_model = Model(
    name="flight_delay",
    version="1.0",
    description="Predicts flight delays based on weather and schedule data.",
    aicontext={
        "system_message": "You are a helpful assistant that explains flight delay predictions.",
        "example_input": {"flight_id": "AA123", "departure": "2024-08-01T14:30:00Z"},
        "example_output": {"delay_minutes": 27, "reason": "Severe thunderstorm"},
        "retrieval_context": ["https://github.com/apache/ossie/blob/main/examples/flights.yaml"]
    }
)

```

## Consumption in AI Converters

During the **model-to-artifact** transformation step, OSSIE converters inspect the `aicontext` dictionary to build AI-ready configurations. If the field is absent, the converter falls back to generic templates; if present, it injects the custom context.

### Wisdom Converter ([`converters/wisdom/src/ossie_wisdom/cli.py`](https://github.com/apache/ossie/blob/main/converters/wisdom/src/ossie_wisdom/cli.py))

The Wisdom converter extracts `system_message` and example pairs to build prompts for the Wisdom LLM backend.

```python

# File: converters/wisdom/src/ossie_wisdom/cli.py

# Simplified extraction logic

def build_wisdom_prompt(model):
    ctx = model.aicontext
    prompt_parts = []
    
    if ctx.get("system_message"):
        prompt_parts.append(f"System: {ctx['system_message']}")
    
    if ctx.get("example_input") and ctx.get("example_output"):
        prompt_parts.append(f"Example Input: {ctx['example_input']}")
        prompt_parts.append(f"Example Output: {ctx['example_output']}")
    
    return "\n".join(prompt_parts)

```

### Omni Converter ([`converters/omni/src/osi_omni/cli.py`](https://github.com/apache/ossie/blob/main/converters/omni/src/osi_omni/cli.py))

Similarly, the Omni converter incorporates retrieval contexts and system messages into Omni-style prompt formats.

```python

# File: converters/omni/src/osi_omni/cli.py

import json
from ossie.models import Model

def build_prompt(model: Model) -> str:
    # Base prompt skeleton

    prompt = f"Model: {model.name} (v{model.version})\n{model.description}\n"

    # Inject AI-specific context if it exists

    ctx = model.aicontext
    if ctx.get("system_message"):
        prompt = f"System: {ctx['system_message']}\n" + prompt

    if ctx.get("example_input") and ctx.get("example_output"):
        prompt += "\nExample:\n"
        prompt += f"Input: {json.dumps(ctx['example_input'])}\n"
        prompt += f"Output: {json.dumps(ctx['example_output'])}\n"

    # Optionally add any retrieval URLs

    if ctx.get("retrieval_context"):
        prompt += "\nReferences:\n" + "\n".join(ctx["retrieval_context"])

    return prompt

```

## Declarative Definition in YAML

OSSIE supports YAML-based model definitions where `aicontext` maps directly to the Python dataclass field. The YAML loader automatically parses the dictionary structure.

### YAML Model File ([`examples/flights.yaml`](https://github.com/apache/ossie/blob/main/examples/flights.yaml))

```yaml

# File: examples/flights.yaml

name: flight_delay
version: "1.0"
description: Predicts flight delays based on weather and schedule data.
aicontext:
  system_message: "You are a helpful assistant that explains flight delay predictions."
  example_input:
    flight_id: "AA123"
    departure: "2024-08-01T14:30:00Z"
  example_output:
    delay_minutes: 27
    reason: "Severe thunderstorm"
  retrieval_context:
    - "https://github.com/apache/ossie/blob/main/examples/flights.yaml"

```

This declarative approach allows non-Python workflows to specify AI context metadata that converters will consume identically to programmatically defined models.

## Standard `ai_context` Keys for LLM Integration

While OSSIE enforces no strict schema on the `aicontext` dictionary, the following keys are conventionally used by the Wisdom and Omni converters:

- **system_message**: Defines the system role or persona for the LLM.
- **example_input** and **example_output**: Concrete input/output pairs that demonstrate the model's intended usage pattern.
- **retrieval_context**: A list of URLs or resource identifiers pointing to external knowledge bases the AI should reference.

Model authors may include additional custom keys, as the field accepts any `Dict[str, Any]` structure.

## Summary

- The `ai_context` field (source attribute `aicontext`) is an optional, free-form dictionary defined in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py) that attaches AI-specific metadata to OSSIE models.
- It enables model authors to specify system messages, examples, and retrieval contexts without modifying converter source code.
- Converters in [`converters/wisdom/src/ossie_wisdom/cli.py`](https://github.com/apache/ossie/blob/main/converters/wisdom/src/ossie_wisdom/cli.py) and [`converters/omni/src/osi_omni/cli.py`](https://github.com/apache/ossie/blob/main/converters/omni/src/osi_omni/cli.py) consume this field during the model-to-artifact transformation to generate tailored LLM prompts.
- The field supports both programmatic Python instantiation and declarative YAML definitions via [`examples/flights.yaml`](https://github.com/apache/ossie/blob/main/examples/flights.yaml).
- When `ai_context` is absent, converters fall back to generic templates, making the field strictly optional but powerful for fine-tuning AI interactions.

## Frequently Asked Questions

### What is the difference between `ai_context` and `aicontext` in Apache OSSIE?

In the OSSIE codebase, the field is named `aicontext` (lowercase, no underscore). Documentation and discussions often refer to it as `ai_context` for readability. Both refer to the same `Dict[str, Any]` attribute defined in [`python/src/ossie/models.py`](https://github.com/apache/ossie/blob/main/python/src/ossie/models.py) that stores AI-specific metadata.

### Can `ai_context` contain nested data structures or is it limited to strings?

The field is typed as `Dict[str, Any]`, meaning it can contain arbitrarily nested dictionaries, lists, booleans, or numbers. However, consuming converters like Wisdom and Omni specifically look for string values in keys like `system_message` and list structures in `retrieval_context`. You should verify your target converter's expectations when designing complex nested structures.

### Which OSSIE converters support the `ai_context` field?

According to the source code, the **Wisdom** converter ([`converters/wisdom/src/ossie_wisdom/cli.py`](https://github.com/apache/ossie/blob/main/converters/wisdom/src/ossie_wisdom/cli.py)) and **Omni** converter ([`converters/omni/src/osi_omni/cli.py`](https://github.com/apache/ossie/blob/main/converters/omni/src/osi_omni/cli.py)) both implement logic to read `aicontext`. These tools use the field to construct prompts for LLM backends. Other converters may ignore the field if they do not implement specific extraction logic.

### Is the `ai_context` field required in OSSIE model definitions?

No, the field is strictly optional. The Model dataclass initializes `aicontext` with `field(default_factory=dict)`, meaning it defaults to an empty dictionary if not provided. Converters gracefully handle missing or empty `ai_context` by falling back to generic prompt templates, ensuring backward compatibility with models that do not specify AI-specific instructions.