// Add or modify application configuration settings in Oscilla. Use when: adding new environment variables, adding new settings fields, understanding settings conventions, working with secrets, or configuring optional vs required settings.
| name | pydantic-settings |
| description | Add or modify application configuration settings in Oscilla. Use when: adding new environment variables, adding new settings fields, understanding settings conventions, working with secrets, or configuring optional vs required settings. |
context7: If the
mcp_context7tool is available, resolve and load the fullpydantic-settingsdocumentation before adding or modifying any settings:mcp_context7_resolve-library-id: "pydantic-settings" mcp_context7_get-library-docs: <resolved-id>
Oscilla manages all application configuration through the pydantic-settings library. Settings are defined in a single class and loaded from the environment and .env file.
Settings class lives at oscilla/conf/settings.py. Always update this existing class — never create a new settings class.SecretStr or SecretBytes: Any value that is sensitive (passwords, tokens, API keys) must be wrapped in one of these types.None: Never use empty strings as a sentinel for "not set".Field(): Include a description= for every field so operators know what it does.# oscilla/conf/settings.py
from pydantic import Field, SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
model_config = SettingsConfigDict(
env_file=".env",
env_file_encoding="utf-8",
extra="ignore",
)
# Regular setting with a default
project_name: str = Field(default="Oscilla", description="Human-readable project name")
# Required setting (no default — must be set in environment)
database_url: SecretStr = Field(description="PostgreSQL connection URL")
# Optional sensitive setting — defaults to None, not empty string
sendgrid_api_key: SecretStr | None = Field(
default=None,
description="SendGrid API key for outbound email. Leave unset to disable email sending.",
)
# Optional non-sensitive setting
max_upload_size_mb: int = Field(
default=10,
description="Maximum allowed upload size in megabytes",
)
SecretStr wraps the value to prevent accidental logging. Access the actual value explicitly when needed:
settings.database_url.get_secret_value() # returns the raw string
settings.sendgrid_api_key.get_secret_value() if settings.sendgrid_api_key else None
| Pattern | Behavior |
|---|---|
field: str = Field(...) | Required — raises ValidationError if not set |
field: str = Field(default=x) | Optional with default |
field: str | None = Field(default=None) | Optional, absent means None |
Never use "" as a default for "not configured":
# Bad
smtp_host: str = Field(default="")
# Good
smtp_host: str | None = Field(default=None, description="SMTP server hostname. None disables email.")
pydantic-settings maps field names to environment variable names automatically using the field name in uppercase:
project_name → PROJECT_NAME
database_url → DATABASE_URL
Prefix overrides can be set via env_prefix in SettingsConfigDict if needed.
oscilla/conf/settings.py.Settings class with Field(description=...).SecretStr if the value is sensitive.None (not "") if the setting is optional..env.example with the new variable name and a placeholder value or explanation..env in the project root (gitignored)..env.example is the template for new developers — keep it updated with every new setting.conf/settings.py, conf/cache.py, conf/db.py), accessing settings in different component types, and environment variable conventions.Write or modify Oscilla game content YAML manifests for any game package. Use when: creating a new game package, writing adventures, enemies, items, quests, regions, locations, skills, buffs, archetypes, recipes, loot tables, or conditions; designing progression systems; configuring game.yaml or character_config.yaml; authoring template expressions; setting up cooldowns or passive effects; validating content with the CLI; or any task that touches files under a content/ game package directory.
Work with the Oscilla Docker Compose development environment. Use when: starting or stopping services, inspecting logs, opening a shell in a container, resetting the database, or understanding the service topology.
Create or modify FastAPI routes in the Oscilla codebase. Use when: adding new API endpoints, creating Pydantic request/response models, registering routers, designing REST APIs, or following route conventions for this project.
Work on the Oscilla frontend (SvelteKit/Vite). Use when: writing or modifying any Svelte components, routes, stores, styles, or frontend tests; adding new UI features or pages; fixing frontend bugs; running frontend tests or type checks; managing npm dependencies; working on accessibility or usability; building production assets; or any task that touches files under frontend/.
Complete reference for all make targets in the Oscilla project. Use when: looking up the right make command for any task — setup, testing, linting, formatting, database, frontend, packaging, or cleanup.
Use the Oscilla CLI to assist content authors writing YAML manifests. Use when: setting up JSON schema validation for YAML manifests, running validate or oscilla content test, inspecting manifest content with list/show, tracing adventure paths, graphing world structure, scaffolding new manifests with oscilla content create, debugging content errors, checking cross-references. Knows all oscilla content subcommands: schema, test, list, show, graph, trace, create. Also covers oscilla validate.