API Reference

def create_llm(
    provider: str,
    model: Optional[str] = None,
    retry_config: Optional[RetryConfig] = None,
    **kwargs
) -> AbstractCoreInterface

from abstractcore import create_llm

# Basic usage
llm = create_llm("openai", model="gpt-4o-mini")

# With unified token management
llm = create_llm(
    "anthropic",
    model="claude-3-5-haiku-latest",
    temperature=0.7,
    max_tokens=32000,           # Context window (input + output)
    max_output_tokens=8000,     # Maximum output tokens
    max_input_tokens=24000,     # Maximum input tokens (auto-calculated if not set)
    timeout=30
)

# With tool syntax rewriting for agent CLI compatibility
llm = create_llm(
    "ollama",
    model="qwen3-coder:30b",
    tool_call_tags="function_call"  # Converts to ...JSON...
)

# Local provider
llm = create_llm("ollama", model="qwen2.5-coder:7b", base_url="http://localhost:11434")

def generate(
    self,
    prompt: str,
    messages: Optional[List[Dict]] = None,
    system_prompt: Optional[str] = None,
    media: Optional[List[str]] = None,
    tools: Optional[List[Callable]] = None,
    response_model: Optional[BaseModel] = None,
    retry_strategy: Optional[Retry] = None,
    stream: bool = False,
    **kwargs
) -> Union[GenerateResponse, Iterator[GenerateResponse]]

# Attach images, documents, and data files
from abstractcore import create_llm

llm = create_llm("openai", model="gpt-4o")

# Single image
response = llm.generate(
    "What's in this image?",
    media=["photo.jpg"]
)

# Multiple files (images, PDFs, Office docs, data)
response = llm.generate(
    "Compare the chart with the data and summarize the document",
    media=["chart.png", "data.csv", "report.pdf"]
)

# Supported file types:
# Images: PNG, JPEG, GIF, WEBP, BMP, TIFF
# Documents: PDF, DOCX, XLSX, PPTX
# Data: CSV, TSV, TXT, MD, JSON

# Local providers support memory management
llm = create_llm("ollama", model="large-model")
response = llm.generate("Hello")
llm.unload()  # Explicitly free memory
del llm

# API providers (OpenAI, Anthropic) - unload() is safe but no-op
api_llm = create_llm("openai", model="gpt-4o-mini")
api_llm.unload()  # Safe to call, but has no effect

@dataclass
class GenerateResponse:
    content: Optional[str]          # Generated text content
    raw_response: Any              # Raw provider response
    model: Optional[str]           # Model used for generation
    finish_reason: Optional[str]   # Why generation stopped
    usage: Optional[Dict[str, int]] # Token usage information
    tool_calls: Optional[List[Dict]] # Tools called by the LLM
    metadata: Optional[Dict]       # Additional metadata

class BasicSession:
    def __init__(
        self,
        provider: AbstractCoreInterface,
        system_prompt: Optional[str] = None
    ):

def generate(self, prompt: str, **kwargs) -> GenerateResponse

def add_message(self, role: str, content: str, **metadata) -> Message

def save(self, filepath: Path, summary: bool = False, assessment: bool = False, facts: bool = False) -> None

@classmethod
def load(cls, filepath: Path, provider: AbstractCoreInterface) -> "BasicSession"

from abstractcore import create_llm, BasicSession

llm = create_llm("openai", model="gpt-4o-mini")
session = BasicSession(
    provider=llm,
    system_prompt="You are a helpful coding tutor."
)

# Multi-turn conversation with memory
response1 = session.generate("My name is Alice and I'm learning Python.")
response2 = session.generate("What's my name and what am I learning?")
# Output: Your name is Alice and you're learning Python.

# Save with analytics
session.save(
    'tutoring_session.json',
    summary=True,      # Generate conversation summary
    assessment=True,   # Assess learning progress
    facts=True        # Extract key facts learned
)

# Load and continue later
loaded_session = BasicSession.load('tutoring_session.json', provider=llm)

from abstractcore.events import EventType, on_global

# Cost monitoring
def monitor_costs(event):
    if event.cost_usd and event.cost_usd > 0.10:
        alert(f"High cost request: ${event.cost_usd}")

# Security control
def prevent_dangerous_tools(event):
    for call in event.data.get('tool_calls', []):
        if call.name in ['delete_file', 'system_command']:
            event.prevent()  # Stop tool execution

# Performance tracking
def track_performance(event):
    if event.duration_ms > 10000:
        log(f"Slow request: {event.duration_ms}ms")

# Register event handlers
on_global(EventType.GENERATION_COMPLETED, monitor_costs)
on_global(EventType.TOOL_STARTED, prevent_dangerous_tools)
on_global(EventType.GENERATION_COMPLETED, track_performance)