Core Concepts

Architecture Patterns

1. PromptContributor Pattern

Most domain types implement PromptContributor from embabel-common, enabling them to format their data for LLM prompts via contribution(): String.

interface PromptContributor : PromptElement {
    fun promptContribution(): PromptContribution
    fun contribution(): String
}

Usage:

val blog = Blog(
    title = "AI Ethics",
    author = "Dr. Smith",
    content = "AI systems must..."
)

val promptText = blog.contribution()
// Use promptText in LLM requests

2. ContentAsset Hierarchy

ContentAsset serves as a marker for content types with textual content, timestamps, and prompt contribution capabilities.

interface ContentAsset : HasContent, Timestamped, PromptContributor

Implementing Types:

• Blog - Blog posts
• ResearchReport - Research reports with linked resources

3. Open Classes

Many classes are open, allowing extension with additional properties:

open class NewsStory(...)
open class ResearchTopic(...)
open class ResearchReport(...)
open class RelevantNewsStories(...)

Example Extension:

class CategorizedNewsStory(
    url: String,
    title: String,
    summary: String,
    val category: String,
    val publishDate: Instant
) : NewsStory(url, title, summary)

4. Jackson Integration

All types use Jackson annotations for JSON serialization:

• @JsonClassDescription - Class-level descriptions for schema generation
• @JsonPropertyDescription - Property-level descriptions
• @JsonDeserialize - Implementation classes for interfaces

Type Hierarchy

HasContent
├── Summary
└── ContentAsset (extends Timestamped, PromptContributor)
    ├── Blog
    └── ResearchReport (also extends InternetResources, HasInfoString)

PromptContributor
├── ContentAsset (see above)
├── NewsStory (also extends Page)
└── RelevantNewsStories

Person
└── PersonImpl

ResearchTopic (open class)
ResearchTopics (container for ResearchTopic)

Interface Overview

From embabel-agent-domain

• ContentAsset - Content with timestamp and prompt contribution
• Person - Person with name

From embabel-agent-api

• HasContent - Types with content: String property
• Page - Web pages with url and summary
• InternetResources - Container for internet resources

From embabel-common

• PromptContributor - Types that can contribute to prompts
• Timestamped - Types with timestamp: Instant
• HasInfoString - Types with formatted info strings

Design Principles

1. LLM Integration First - All types designed for easy LLM consumption via contribution()
2. Jackson Ready - Full JSON serialization support out of the box
3. Extensibility - Open classes allow customization without modification
4. Type Safety - Kotlin data classes provide structural equality and immutability
5. Interoperability - Java-compatible APIs throughout