Magentic

Warnings

• gotcha The function body of @prompt decorated functions is NEVER executed. Must use ... (ellipsis) as the body. Any actual code in the body is dead code that will never run.
  Fix: Always use '...' as the function body for @prompt, @chatprompt, @prompt_chain decorated functions.
• gotcha When functions= is passed to @prompt, the LLM may return a FunctionCall object instead of the final result. Must call fn_call() to execute it. Use @prompt_chain to auto-resolve.
  Fix: result = describe_weather('Boston')() — note the extra () to execute the FunctionCall. Or use @prompt_chain for automatic resolution.
• gotcha Default model is gpt-4o-mini (OpenAI). Requires OPENAI_API_KEY. Fails silently if not set — raises AuthenticationError at call time, not at decoration time.
  Fix: Set OPENAI_API_KEY env var. Or pass model= explicitly: @prompt('...', model=OpenaiChatModel('gpt-4o'))
• gotcha Still pre-1.0 (0.41.x). API stability not guaranteed. Minor versions may introduce breaking changes.
  Fix: Pin version in production: pip install magentic==0.41.1
• gotcha Anthropic and LiteLLM backends require separate extras. 'pip install magentic' alone only includes OpenAI backend.
  Fix: pip install 'magentic[anthropic]' or 'magentic[litellm]'

Install

• pip install magentic Python (core, OpenAI backend)
• pip install 'magentic[anthropic]' Python (Anthropic backend)
• pip install 'magentic[litellm]' Python (LiteLLM backend — 100+ providers)

Imports

• prompt

  from magentic import prompt
  from pydantic import BaseModel
  
  class Superhero(BaseModel):
      name: str
      power: str
  
  @prompt('Create a superhero named {name}.')
  def create_superhero(name: str) -> Superhero:
      ...  # body is never executed — must be ellipsis
  
  hero = create_superhero('Garden Man')
  print(hero.name, hero.power)

  The function body of a @prompt decorated function is NEVER executed. It must be ... (ellipsis). Any code in the body is dead code and will never run. The LLM generates the return value.
• FunctionCall

  from magentic import prompt, FunctionCall
  
  def get_weather(city: str) -> str:
      return f'Sunny in {city}'
  
  @prompt(
      'What is the weather in {city}?',
      functions=[get_weather]
  )
  def describe_weather(city: str) -> FunctionCall[str]:
      ...
  
  # Returns a FunctionCall object — must be called to execute
  fn_call = describe_weather('Boston')
  result = fn_call()  # actually calls get_weather
  print(result)

  When LLM decides to call a function, @prompt returns a FunctionCall object — not the final result. You must call fn_call() to execute the function. Use @prompt_chain to auto-resolve.
• chatprompt

  from magentic import chatprompt, SystemMessage, UserMessage
  
  @chatprompt(
      SystemMessage('You are a helpful assistant.'),
      UserMessage('{question}'),
  )
  def answer(question: str) -> str:
      ...
  
  print(answer('What is Python?'))

  Use @chatprompt for structured chat messages with SystemMessage/UserMessage. @prompt is for single-string prompts. Mixing system instructions into @prompt string works but loses structure.

Quickstart

Minimal magentic structured output using @prompt decorator.

# pip install magentic
from magentic import prompt
from pydantic import BaseModel

class Superhero(BaseModel):
    name: str
    power: str
    enemies: list[str]

@prompt('Create a superhero named {name}.')
def create_superhero(name: str) -> Superhero:
    ...  # never executed

hero = create_superhero('Garden Man')
print(hero.name)     # 'Garden Man'
print(hero.power)    # 'Control over plants'
print(hero.enemies)  # ['Pollution Man', ...]