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

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, 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

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.

# 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.

# 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)

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

# 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)

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

# 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)

# 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 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 and 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.
• 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 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) and Omni converter (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}