{"id":48917181,"url":"https://github.com/andrader/schellma","last_synced_at":"2026-04-17T03:09:58.770Z","repository":{"id":312201567,"uuid":"1045368550","full_name":"andrader/schellma","owner":"andrader","description":"Simplified schemas for generating structured output with LLMs","archived":false,"fork":false,"pushed_at":"2025-10-06T12:58:24.000Z","size":273,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T21:23:14.902Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://andrader.github.io/schellma/","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/andrader.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"Roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-27T03:58:51.000Z","updated_at":"2026-01-25T15:04:48.000Z","dependencies_parsed_at":"2025-08-29T07:37:25.394Z","dependency_job_id":"5d10848a-1327-49a2-882d-935afe21aa54","html_url":"https://github.com/andrader/schellma","commit_stats":null,"previous_names":["andrader/schellma"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/andrader/schellma","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrader%2Fschellma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrader%2Fschellma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrader%2Fschellma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrader%2Fschellma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrader","download_url":"https://codeload.github.com/andrader/schellma/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrader%2Fschellma/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31913118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"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":[],"created_at":"2026-04-17T03:09:58.075Z","updated_at":"2026-04-17T03:09:58.760Z","avatar_url":"https://github.com/andrader.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# scheLLMa\n\n_Schemas for LLMs and Structured Output_\n\n[![Documentation](https://img.shields.io/badge/Documentation-blue)](https://andrader.github.io/schellma/)\n[![Demo and Examples](https://img.shields.io/badge/Demo_and_Examples-blue)](https://andrader.github.io/schellma/demo/)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![PyPI version](https://badge.fury.io/py/schellma.svg)](https://badge.fury.io/py/schellma)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/schellma)\n\n\n\nConverts Pydantic models/JSON Schemas to clean, simplified type definitions perfect for **generating structured output** with **LLM prompts**. \n\nUnlike verbose JSON Schema formats, **scheLLMa** produces readable, concise type definitions that are ideal for language model interactions and structured output generation:\n\n- **Reduce token usage** - Concise format saves on API costs\n- **Minimize parsing errors** - Simple syntax is easier for models to parse, less verbose than JSON Schema, reducing confusion\n- **Stay readable** - Human-friendly format for prompt engineering\n\nView the [documentation](https://andrader.github.io/schellma/) for more details.\n\nCheckout the [demo](https://andrader.github.io/schellma/demo/) for more examples!\n\nCombine it with parsing libs, like `openai` sdk or `Instructor` for AWESOME results!\n\n- [scheLLMa](#schellma)\n  - [Features](#features)\n  - [Quick Start](#quick-start)\n    - [Using the new openai chat.completions.**parse** API](#using-the-new-openai-chatcompletionsparse-api)\n    - [Using the new openai Responses API](#using-the-new-openai-responses-api)\n  - [Installation](#installation)\n    - [Comparison with JSON Schema](#comparison-with-json-schema)\n  - [Advanced Usage with Type Definitions](#advanced-usage-with-type-definitions)\n  - [Examples](#examples)\n    - [Enum Support](#enum-support)\n    - [Complex Nested Structures](#complex-nested-structures)\n  - [Development](#development)\n    - [Setup](#setup)\n    - [Running Tests](#running-tests)\n    - [Type Checking](#type-checking)\n    - [Linting](#linting)\n  - [Contributing](#contributing)\n    - [Development Guidelines](#development-guidelines)\n  - [License](#license)\n  - [Changelog](#changelog)\n\n\n## Features\n\n- 🤖 **Optimized for LLM prompts** - Clean, readable type definitions\n- 💰 **Token-efficient** - Reduces LLM API costs\n- 🎯 **Support for all common Python types** (str, int, bool, datetime, etc.)\n- 🏗️ **Handle complex nested structures and collections** - Strong support for Pydantic model types\n- 🔗 **Support for enums, optional types, and unions** - Properly extract and display union types\n- ⚙️ **Customizable output formatting** - Indentation, compact mode, and more\n- 🎨 **Rich Default Values** - Automatically shows default values in human-readable comments\n- 📏 **Smart Constraints** - Displays field constraints (length, range, patterns) in clear language\n- ✅ **Clear Field Status** - Explicit required/optional marking\n- 📚 **Rich Examples** - Inline examples and documentation for better LLM understanding\n- 🔀 **Advanced Union Types** - Full support for allOf, not constraints, and discriminated unions\n- 🔢 **Advanced Arrays** - Contains constraints, minContains/maxContains, and enhanced tuple support\n\n\n\n## Quick Start\n\nView the [demo](demo.md) for more examples and features!\n\n```python\nfrom pydantic import BaseModel\nfrom schellma import schellma\nimport openai\n\nclass TaskRequest(BaseModel):\n    title: str\n    priority: int\n    tags: list[str]\n    due_date: str | None = None\n\n# Generate schema for LLM prompt\nschema = schellma(TaskRequest)\n\n# Add the scheLLMa schema to the prompt\nprompt = f\"\"\"\nPlease create a task with the following structure:\n\n{schema}\n\"\"\"\nprint(prompt)\n\n# Use with your favorite LLM API\ncompletion = openai.chat.completions.create(\n    model=\"gpt-4.1-mini\",\n    messages=[{\n        \"role\": \"user\",\n        \"content\": prompt\n    }]\n)\n\ncontent = completion.choices[0].message.content\nprint(content)\n\ntask = TaskRequest.model_validate_json(clean_content(content))\nprint(task)\n# TaskRequest(title='Task 1', priority=1, tags=['tag1', 'tag2'], due_date=None)\n```\n\n### Using the new openai chat.completions.**parse** API\n\n```python\n# or directly parse with openai sdk\ncompletion = openai.chat.completions.parse(\n    model=\"gpt-4.1-mini\",\n    messages=[{\n        \"role\": \"user\",\n        \"content\": prompt\n    }]\n)\ntask = completion.choices[0].message.parsed\nprint(task)\n# TaskRequest(title='Task 1', priority=1, tags=['tag1', 'tag2'], due_date=None)\n```\n\n### Using the new openai Responses API\n\n```python\nclass CalendarEvent(BaseModel):\n    name: str\n    date: str\n    participants: list[str]\n\nschema = schellma(CalendarEvent)\n\nresponse = openai.responses.parse(\n    model=\"gpt-4o-2024-08-06\",\n    input=[\n        # Make sure to include the schema in your prompt\n        {\"role\": \"system\", \"content\": f\"Extract the event information. {schema}\"},\n        {\n            \"role\": \"user\",\n            \"content\": \"Alice and Bob are going to a science fair on Friday.\",\n        },\n    ],\n    text_format=CalendarEvent,\n)\n\nevent = response.output_parsed\nprint(event)\n# CalendarEvent(name='Alice and Bob are going to a science fair on Friday.', date='Friday', participants=['Alice', 'Bob'])\n```\n\n\n\n## Installation\n\n```bash\npip install schellma\n```\n\nOr using uv:\n\n```bash\nuv add schellma\n```\n\nInstall from github\n\n```bash\nuv add git+https://github.com/andrader/schellma.git\n```\n\n\n### Comparison with JSON Schema\n\n**JSON Schema (verbose, token-heavy):**\n\n```json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": { \"type\": \"string\" },\n    \"age\": { \"type\": \"integer\" },\n    \"email\": { \"type\": [\"string\", \"null\"], \"default\": null }\n  },\n  \"required\": [\"name\", \"age\"],\n  \"additionalProperties\": false\n}\n```\n\n**scheLLMa (clean, token-efficient):**\n\n```typescript\n{\n    \"name\": string,\n    \"age\": int,\n    \"email\": string | null,\n}\n```\n\n## Advanced Usage with Type Definitions\n\n```python\nfrom pydantic import BaseModel\nfrom typing import List, Optional\nfrom schellma import schellma\n\nclass Address(BaseModel):\n    street: str\n    city: str\n    country: str\n\nclass User(BaseModel):\n    name: str\n    age: int\n    addresses: List[Address]\n    primary_address: Optional[Address] = None\n\n# Generate with separate type definitions\nschema = schellma(User, define_types=True)\nprint(schema)\n```\n\nOutput:\n\n```typescript\nAddress {\n    \"street\": string,\n    \"city\": string,\n    \"country\": string,\n}\n\n{\n    \"name\": string,\n    \"age\": int,\n    \"addresses\": Address[],\n    \"primary_address\": Address | null,\n}\n```\n\n\n\n\n## Examples\n\nView more exemples at [Demo](#demo.md)\n\n### Enum Support\n\n```python\nfrom enum import Enum\nfrom pydantic import BaseModel\n\nclass Status(Enum):\n    ACTIVE = \"active\"\n    INACTIVE = \"inactive\"\n\nclass Task(BaseModel):\n    title: str\n    status: Status\n\nschema = schellma(Task)\n# Output: { \"title\": string, \"status\": \"active\" | \"inactive\" }\n```\n\n### Complex Nested Structures\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Dict, List\n\nclass Tag(BaseModel):\n    name: str\n    color: str\n\nclass Post(BaseModel):\n    title: str\n    content: str\n    tags: List[Tag]\n    metadata: Dict[str, str]\n\nschema = schellma(Post, define_types=True)\n```\n\n\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/andrader/schellma.git\ncd schellma\nuv sync --dev\n```\n\n### Running Tests\n\n```bash\nuv run python -m pytest\n```\n\n### Type Checking\n\n```bash\nuv run mypy src/schellma/\n```\n\n### Linting\n\n```bash\nuv run ruff check src/schellma/\nuv run ruff format src/schellma/\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n### Development Guidelines\n\n1. Follow the existing code style (enforced by ruff)\n2. Add tests for any new functionality\n3. Update documentation as needed\n4. Ensure all tests pass and type checking succeeds\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\nSee [Changelog](CHANGELOG.md) for the changelog.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrader%2Fschellma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrader%2Fschellma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrader%2Fschellma/lists"}