Core Foundation

Shared library providing domain models, settings, and logging for all capabilities.

The Core Foundation is the shared library that all other capabilities depend on. It provides shared domain models, a base settings class, structured logging configuration, and a config loader.

The core foundation is included automatically as a dependency of every capability — you do not need to install it separately.

Domain models

Import models directly from the top-level package:

from support_core import (
    Ticket, Customer, Agent, Message, Conversation,
    Priority, TicketStatus, Channel, CustomerTier, AuthorType,
)

Ticket

ticket = Ticket(
    id="T-001",
    subject="Can't log in",
    description="Password reset not working",
    status=TicketStatus.new,
    priority=Priority.high,
    channel=Channel.email,
    customer_id="C-001",
    tags=["auth", "login"],
)

Customer

customer = Customer(
    id="C-001",
    name="Jane Doe",
    email="jane@example.com",
    tier=CustomerTier.premium,
    metadata={"company": "Acme Inc"},
)

Agent

agent = Agent(
    id="A-001",
    name="John Smith",
    email="john@support.example.com",
    teams=["billing", "technical"],
    skills=["refunds", "api"],
)

Message and Conversation

message = Message(
    id="M-001",
    author_type=AuthorType.customer,
    author_id="C-001",
    body="I need help with my account",
    channel=Channel.chat,
)

conversation = Conversation(
    id="CV-001",
    ticket_id="T-001",
    messages=[message],
)

All models use Pydantic v2 with extra="forbid" (rejects unknown fields) and automatic whitespace stripping.

SimpliSettings

Base settings class for all services. Subclass it and add your own fields:

from support_core.settings import SimpliSettings

class Settings(SimpliSettings):
    litellm_model: str = "openai/gpt-5-mini"
    database_url: str | None = None

settings = Settings()

Settings are automatically loaded from environment variables and .env files. The base class provides:

Field	Default	Env var
`app_env`	`development`	`APP_ENV`
`app_host`	`0.0.0.0`	`APP_HOST`
`app_port`	`8000`	`APP_PORT`
`app_log_level`	`info`	`APP_LOG_LEVEL`
`app_debug`	`false`	`APP_DEBUG`

Logging

Configure structured logging in one call:

from support_core.logging import setup_logging

# Console output for development
setup_logging(log_level="DEBUG")

# JSON output for production
setup_logging(log_level="INFO", json_output=True)

Uses structlog with timestamping, log level filtering, exception formatting, and context variable support.

Config loader

For advanced configuration using YAML files:

from support_core.config import load_config

config = load_config(env_file=".env", yaml_file="config.yml")

Priority order: environment variables > .env file > YAML file. Only processes SIMPLI_* prefixed keys.

The core foundation gives every capability a consistent starting point: domain models for tickets, customers, agents, and conversations; a base settings class with environment variable loading; structured logging; and a YAML-based config loader.