{"id":29790233,"url":"https://github.com/piotrmaciejbednarski/structllm","last_synced_at":"2025-07-31T03:02:09.388Z","repository":{"id":306332780,"uuid":"1025858053","full_name":"piotrmaciejbednarski/structllm","owner":"piotrmaciejbednarski","description":"Universal Python library for Structured Outputs with any LLM provider","archived":false,"fork":false,"pushed_at":"2025-07-25T01:39:25.000Z","size":239,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-25T03:50:25.297Z","etag":null,"topics":["ai","anthropic","json-schema","litellm","llm","openai","pydantic","structured-output","structured-outputs"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/structllm/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/piotrmaciejbednarski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-24T23:33:34.000Z","updated_at":"2025-07-25T01:36:42.000Z","dependencies_parsed_at":"2025-07-25T03:50:27.660Z","dependency_job_id":"7b6aa5c5-91bc-4fb2-8ab2-a9ab78be7733","html_url":"https://github.com/piotrmaciejbednarski/structllm","commit_stats":null,"previous_names":["piotrmaciejbednarski/structllm"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/piotrmaciejbednarski/structllm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmaciejbednarski%2Fstructllm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmaciejbednarski%2Fstructllm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmaciejbednarski%2Fstructllm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmaciejbednarski%2Fstructllm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piotrmaciejbednarski","download_url":"https://codeload.github.com/piotrmaciejbednarski/structllm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmaciejbednarski%2Fstructllm/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267979248,"owners_count":24175273,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","anthropic","json-schema","litellm","llm","openai","pydantic","structured-output","structured-outputs"],"created_at":"2025-07-28T00:00:35.545Z","updated_at":"2025-07-31T03:02:09.240Z","avatar_url":"https://github.com/piotrmaciejbednarski.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# structllm\n\n\u003cdiv style=\"text-align: center;\"\u003e\n  \u003cimg width=\"100%\" src=\"structllm.svg\" alt=\"Logo\"\u003e\n\u003c/div\u003e\n\n[![PyPI version](https://badge.fury.io/py/structllm.svg)](https://badge.fury.io/py/structllm)\n[![Python Support](https://img.shields.io/pypi/pyversions/structllm.svg)](https://pypi.org/project/structllm/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**structllm** is a universal and lightweight Python library that provides [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs?api-mode=responses) functionality for any LLM provider (OpenAI, Anthropic, Mistral, local models, etc.), not just OpenAI. It guarantees that LLM responses conform to your provided JSON schema using Pydantic models.\n\nIf your LLM model has 7B parameters or more, it can be used with structllm.\n\n## Installation\n\n```bash\npip install structllm\n```\n\nOr using uv (recommended):\n\n```bash\nuv add structllm\n```\n\n## Quick Start\n\n```python\nfrom pydantic import BaseModel\nfrom structllm import StructLLM\nfrom typing import List\n\nclass CalendarEvent(BaseModel):\n    name: str\n    date: str\n    participants: List[str]\n\nclient = StructLLM(\n    api_base=\"https://openrouter.ai/api/v1\",\n    api_key=\"sk-or-v1-...\",\n)\n\nmessages = [\n    {\"role\": \"system\", \"content\": \"Extract the event information.\"},\n    {\"role\": \"user\", \"content\": \"Alice and Bob are going to a science fair on Friday.\"},\n]\n\nresponse = client.parse(\n    model=\"openrouter/moonshotai/kimi-k2\",\n    messages=messages,\n    response_format=CalendarEvent,\n)\n\nif response.output_parsed:\n    print(response.output_parsed)\n    # {\"name\": \"science fair\", \"date\": \"Friday\", \"participants\": [\"Alice\", \"Bob\"]}\nelse:\n    print(\"Failed to parse structured output\")\n```\n\n## Provider Support\n\nStructLLM works with **100+ LLM providers** through LiteLLM. Check the [LiteLLM documentation](https://docs.litellm.ai/docs/providers) for the full list of supported providers.\n\n## Advanced Usage\n\n### Complex Data Structures\n\n```python\nfrom pydantic import BaseModel, Field\nfrom typing import List, Optional\nfrom enum import Enum\n\nclass Priority(str, Enum):\n    LOW = \"low\"\n    MEDIUM = \"medium\"\n    HIGH = \"high\"\n\nclass Task(BaseModel):\n    title: str = Field(description=\"The task title\")\n    description: Optional[str] = Field(default=None, description=\"Task description\")\n    priority: Priority = Field(description=\"Task priority level\")\n    assignees: List[str] = Field(description=\"List of assigned people\")\n    due_date: Optional[str] = Field(default=None, description=\"Due date in YYYY-MM-DD format\")\n\nclient = StructLLM(\n    api_base=\"https://openrouter.ai/api/v1\",\n    api_key=\"sk-or-v1-...\",\n)\n\nresponse = client.parse(\n    model=\"gpt-4o-2024-08-06\",\n    messages=[\n        {\n            \"role\": \"user\",\n            \"content\": \"Create a high-priority task for John and Sarah to review the quarterly report by next Friday.\"\n        }\n    ],\n    response_format=Task,\n)\n\ntask = response.output_parsed\nprint(f\"Task: {task.title}\")\nprint(f\"Priority: {task.priority}\")\nprint(f\"Assignees: {task.assignees}\")\n```\n\n### Error Handling\n\n```python\nresponse = client.parse(\n    model=\"gpt-4o-2024-08-06\",\n    messages=messages,\n    response_format=CalendarEvent,\n)\n\nif response.output_parsed:\n    # Successfully parsed\n    event = response.output_parsed\n    print(f\"Parsed event: {event}\")\nelse:\n    # Parsing failed, but raw response is available\n    print(\"Failed to parse structured output\")\n    print(f\"Raw response: {response.raw_response.choices[0].message.content}\")\n```\n\n### Custom Configuration\n\n```python\nclient = StructLLM(\n    api_base=\"https://api.custom-provider.com/v1\",\n    api_key=\"your-api-key\"\n)\n\nresponse = client.parse(\n    model=\"custom/model-name\",\n    messages=messages,\n    response_format=YourModel,\n    temperature=0.1,\n    top_p=0.1,\n    max_tokens=1000,\n    # Any additional parameters supported by the LiteLLM interface\n    custom_parameter=\"value\"\n)\n```\n\n## How It Works\n\nStructLLM uses prompt engineering to ensure structured outputs:\n\n1. **Schema Injection**: Automatically injects your Pydantic model's JSON schema into the system prompt\n2. **Format Instructions**: Adds specific instructions for JSON-only responses\n3. **Intelligent Parsing**: Extracts JSON from responses even when wrapped in additional text\n4. **Validation**: Uses Pydantic for robust type checking and validation\n5. **Fallback Handling**: Gracefully handles parsing failures while preserving raw responses\n\nBy default it uses low `temperature` and `top_p` settings to ensure consistent outputs, but you can customize these parameters as needed.\n\n## Testing\n\nRun the test suite:\n\n```bash\n# Install dependencies\nuv sync\n\n# Run tests\nuv run pytest\nuv run pytest -m \"not integration\"\n\n# Run integration tests (requires external services)\nuv run pytest -m \"integration\"\n\n# Run linting\nuv run ruff check .\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes with tests\n4. Run the test suite: `uv run pytest`\n5. Run linting: `uv run ruff check .`\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [LiteLLM](https://github.com/BerriAI/litellm) for providing the universal LLM interface\n- [Pydantic](https://github.com/pydantic/pydantic) for structured data validation","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmaciejbednarski%2Fstructllm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiotrmaciejbednarski%2Fstructllm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmaciejbednarski%2Fstructllm/lists"}