{"id":153,"library":"magentic","title":"Magentic","description":"Decorator-based library for seamlessly integrating LLMs as Python functions. Uses @prompt, @chatprompt, and @prompt_chain decorators to turn Python function signatures into LLM calls with typed structured output. Built on pydantic for output validation. Current version: 0.41.1 (Mar 2026). Still pre-1.0 — API may change. Default backend: OpenAI.","status":"active","version":"0.41.1","language":"python","source_language":"en","source_url":"https://github.com/jackmpcollins/magentic","tags":["magentic","llm","decorator","structured-output","pydantic","python","prompt"],"install":[{"cmd":"pip install magentic","lang":"bash","label":"Python (core, OpenAI backend)"},{"cmd":"pip install 'magentic[anthropic]'","lang":"bash","label":"Python (Anthropic backend)"},{"cmd":"pip install 'magentic[litellm]'","lang":"bash","label":"Python (LiteLLM backend — 100+ providers)"}],"dependencies":[{"reason":"Default backend. Installed automatically with core package.","package":"openai","optional":false},{"reason":"Required for structured output validation.","package":"pydantic","optional":false}],"imports":[{"note":"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.","wrong":"from magentic import prompt\n\n@prompt('Create a superhero named {name}.')\ndef create_superhero(name: str) -> Superhero:\n    return Superhero(name=name, power='Unknown')  # body is ignored","symbol":"prompt","correct":"from magentic import prompt\nfrom pydantic import BaseModel\n\nclass Superhero(BaseModel):\n    name: str\n    power: str\n\n@prompt('Create a superhero named {name}.')\ndef create_superhero(name: str) -> Superhero:\n    ...  # body is never executed — must be ellipsis\n\nhero = create_superhero('Garden Man')\nprint(hero.name, hero.power)"},{"note":"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.","wrong":"result = describe_weather('Boston')\nprint(result)  # prints FunctionCall object, not the weather","symbol":"FunctionCall","correct":"from magentic import prompt, FunctionCall\n\ndef get_weather(city: str) -> str:\n    return f'Sunny in {city}'\n\n@prompt(\n    'What is the weather in {city}?',\n    functions=[get_weather]\n)\ndef describe_weather(city: str) -> FunctionCall[str]:\n    ...\n\n# Returns a FunctionCall object — must be called to execute\nfn_call = describe_weather('Boston')\nresult = fn_call()  # actually calls get_weather\nprint(result)"},{"note":"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.","wrong":"from magentic import prompt\n\n@prompt('System: You are helpful.\\nUser: {question}')\ndef answer(question: str) -> str:\n    ...","symbol":"chatprompt","correct":"from magentic import chatprompt, SystemMessage, UserMessage\n\n@chatprompt(\n    SystemMessage('You are a helpful assistant.'),\n    UserMessage('{question}'),\n)\ndef answer(question: str) -> str:\n    ...\n\nprint(answer('What is Python?'))"}],"quickstart":{"code":"# pip install magentic\nfrom magentic import prompt\nfrom pydantic import BaseModel\n\nclass Superhero(BaseModel):\n    name: str\n    power: str\n    enemies: list[str]\n\n@prompt('Create a superhero named {name}.')\ndef create_superhero(name: str) -> Superhero:\n    ...  # never executed\n\nhero = create_superhero('Garden Man')\nprint(hero.name)     # 'Garden Man'\nprint(hero.power)    # 'Control over plants'\nprint(hero.enemies)  # ['Pollution Man', ...]","lang":"python","description":"Minimal magentic structured output using @prompt decorator."},"warnings":[{"fix":"Always use '...' as the function body for @prompt, @chatprompt, @prompt_chain decorated functions.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"result = describe_weather('Boston')() — note the extra () to execute the FunctionCall. Or use @prompt_chain for automatic resolution.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Set OPENAI_API_KEY env var. Or pass model= explicitly: @prompt('...', model=OpenaiChatModel('gpt-4o'))","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Pin version in production: pip install magentic==0.41.1","message":"Still pre-1.0 (0.41.x). API stability not guaranteed. Minor versions may introduce breaking changes.","severity":"gotcha","affected_versions":"all"},{"fix":"pip install 'magentic[anthropic]' or 'magentic[litellm]'","message":"Anthropic and LiteLLM backends require separate extras. 'pip install magentic' alone only includes OpenAI backend.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade Python to 3.10 or newer.","message":"magentic requires Python >= 3.10. Installation will fail on older Python versions.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T09:03:53.813Z","next_check":"2026-06-24T00:00:00.000Z","problems":[{"fix":"Ensure your OpenAI API key is correctly set as an environment variable: `export OPENAI_API_KEY='sk-your-api-key'` (or `set OPENAI_API_KEY=sk-your-api-key` on Windows) before running your application. You can generate or verify your API key on the OpenAI platform dashboard.","cause":"Magentic uses OpenAI as its default LLM provider, and this error occurs when the `OPENAI_API_KEY` environment variable is not set correctly, is expired, or is invalid.","error":"openai.AuthenticationError: Incorrect API key provided"},{"fix":"Adjust your `@prompt` or `@chatprompt` to more explicitly guide the LLM to produce output in the expected structured format. This might involve adding instructions to the prompt, providing examples in a `chatprompt`, or using `max_retries` on the decorator to allow `magentic` to prompt the LLM again with error feedback.","cause":"This error happens when `magentic` expects the LLM to return data in a specific Python type (often a Pydantic model) as defined by your function's return type annotation, but the LLM instead returns a plain string that cannot be parsed into the expected type.","error":"ValueError: String was returned by model but not expected. You may need to update your prompt to encourage the model to return a specific type."},{"fix":"Ensure that the LLM's response genuinely intends to call a function. Review your prompt to confirm it encourages function calls when appropriate, or check the `Chat` object's history before attempting `exec_function_call()` to confirm the last message is indeed a `FunctionCall` type.","cause":"This error occurs when you attempt to call `chat.exec_function_call()` on a `Chat` object, but the most recent message from the LLM in the conversation history does not indicate a function call.","error":"TypeError: Last message is not a function call."},{"fix":"Install the `anthropic` package using pip: `pip install anthropic`. If you installed `magentic` with extras, ensure you included the `anthropic` extra: `pip install 'magentic[anthropic]'`.","cause":"This error arises when you configure `magentic` to use the Anthropic LLM provider (e.g., `AnthropicChatModel`), but the `anthropic` Python package is not installed in your environment.","error":"ModuleNotFoundError: No module named 'anthropic'"}],"ecosystem":"pypi","meta_description":null,"install_score":85,"install_tag":"verified","quickstart_score":70,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"anthropic","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.16,"mem_mb":27.5,"disk_size":"55.7M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.39,"mem_mb":30.5,"disk_size":"212.9M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.21,"mem_mb":27.5,"disk_size":"49.1M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"anthropic","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.61,"mem_mb":27.5,"disk_size":"55M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.81,"mem_mb":30.5,"disk_size":"196M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.58,"mem_mb":27.5,"disk_size":"48M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"anthropic","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.83,"mem_mb":29.6,"disk_size":"60.2M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.1,"mem_mb":32.9,"disk_size":"229.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.9,"mem_mb":29.6,"disk_size":"53.1M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"anthropic","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.42,"mem_mb":29.6,"disk_size":"59M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.67,"mem_mb":32.9,"disk_size":"213M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.44,"mem_mb":29.6,"disk_size":"52M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"anthropic","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.63,"mem_mb":29.3,"disk_size":"51.3M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.85,"mem_mb":32.4,"disk_size":"218.3M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.67,"mem_mb":29.3,"disk_size":"44.3M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"anthropic","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.62,"mem_mb":29.3,"disk_size":"50M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.98,"mem_mb":32.4,"disk_size":"201M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.6,"mem_mb":29.3,"disk_size":"44M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"anthropic","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.49,"mem_mb":29.8,"disk_size":"51.0M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.79,"mem_mb":33,"disk_size":"218.0M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.52,"mem_mb":29.8,"disk_size":"44.0M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"anthropic","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.57,"mem_mb":29.8,"disk_size":"50M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"litellm","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.91,"mem_mb":33,"disk_size":"201M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.53,"mem_mb":29.8,"disk_size":"43M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"anthropic","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"anthropic","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}