{"id":15012916,"url":"https://github.com/lennartpollvogt/ollama-instructor","last_synced_at":"2025-04-09T18:21:59.683Z","repository":{"id":241384628,"uuid":"806715859","full_name":"lennartpollvogt/ollama-instructor","owner":"lennartpollvogt","description":"Python library for the instruction and reliable validation of structured outputs (JSON) of Large Language Models (LLMs) with Ollama and Pydantic. -\u003e Deterministic work with LLMs.","archived":false,"fork":false,"pushed_at":"2024-12-21T12:37:26.000Z","size":427,"stargazers_count":75,"open_issues_count":2,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-02T13:53:59.495Z","etag":null,"topics":["instructor","json","json-schema","llm","local-llm","ollama","prompting","pydantic","validation"],"latest_commit_sha":null,"homepage":"","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/lennartpollvogt.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}},"created_at":"2024-05-27T18:43:46.000Z","updated_at":"2025-03-26T12:19:15.000Z","dependencies_parsed_at":"2024-06-22T12:58:15.189Z","dependency_job_id":"0e945826-247f-483c-b03d-3101a43a902c","html_url":"https://github.com/lennartpollvogt/ollama-instructor","commit_stats":{"total_commits":48,"total_committers":2,"mean_commits":24.0,"dds":0.125,"last_synced_commit":"7ad10cd72c175cf4187a4d00506584ef5f57c443"},"previous_names":["lennartpollvogt/ollama-instructor"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lennartpollvogt%2Follama-instructor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lennartpollvogt%2Follama-instructor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lennartpollvogt%2Follama-instructor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lennartpollvogt%2Follama-instructor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lennartpollvogt","download_url":"https://codeload.github.com/lennartpollvogt/ollama-instructor/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248085637,"owners_count":21045191,"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","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":["instructor","json","json-schema","llm","local-llm","ollama","prompting","pydantic","validation"],"created_at":"2024-09-24T19:43:24.604Z","updated_at":"2025-04-09T18:21:59.641Z","avatar_url":"https://github.com/lennartpollvogt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ollama-instructor\n\n`ollama-instructor` is a lightweight Python library that provides a convenient wrapper around the Ollama Client, extending it with validation features for obtaining valid JSON responses from Large Language Models (LLMs). Utilizing Pydantic, `ollama-instructor` ensures that responses from LLMs adhere to defined schemas.\n\n[![Downloads](https://static.pepy.tech/badge/ollama-instructor/month)](https://pepy.tech/project/ollama-instructor)\n\n\u003e **Note**: This library depends on having [Ollama](https://ollama.com) installed and running. For more information, please refer to the official website of Ollama.\n\n## Breaking Changes in Version 1.0.0\n\nVersion 1.0.0 introduces significant changes from version 0.5.2:\n- Complete refactoring to directly inherit from Ollama's official Client classes\n- Simplified API that aligns more closely with Ollama's native interface\n- Improved logging system using Python's built-in logging module\n- Streamlined validation process using Pydantic\n- Removal of partial validation features to focus on core functionality\n- New method names: `chat_completion` and `chat_stream` (previously `chat_completion_with_stream`)\n\n## Features\n\n- **Direct Integration**: Inherits directly from Ollama's official client for seamless integration\n- **Schema Validation**: Uses Pydantic BaseModel to ensure valid JSON responses\n- **Retry Mechanism**: Automatically retries failed validations with configurable attempts\n- **Logging**: Comprehensive logging system with configurable levels\n- **Async Support**: Full async/await support through `OllamaInstructorAsync`\n\n## Installation\n\n```bash\npip install ollama-instructor\n```\n\n## Quick Start\n\nFor streaming examples click [here](examples/)\n\n### Synchronous Usage:\n```python\nfrom pydantic import BaseModel\nfrom ollama_instructor import OllamaInstructor\n\nclass FriendInfo(BaseModel):\n    name: str\n    age: int\n    is_available: bool\n\nclass FriendList(BaseModel):\n    friends: list[FriendInfo]\n\n# Create client with logging enabled\nclient = OllamaInstructor(enable_logging=True, log_level='DEBUG')\n\n# Chat completion\nresponse = client.chat_completion(\n    format=FriendList,\n    model='llama2:latest',\n    messages=[\n        {\n            'role': 'user',\n            'content': 'I have two friends: John (25, available) and Mary (30, busy)'\n        }\n    ]\n)\n```\n\n### Asynchronous Usage:\n```python\nimport asyncio\nfrom pydantic import BaseModel\nfrom ollama_instructor import OllamaInstructorAsync\n\nclass FriendInfo(BaseModel):\n    name: str\n    age: int\n    is_available: bool\n\nasync def main():\n    client = OllamaInstructorAsync(enable_logging=True)\n\n    response = await client.chat_completion(\n        format=FriendInfo,\n        model='llama2:latest',\n        messages=[\n            {\n                'role': 'user',\n                'content': 'John is 25 years old and available to hang out'\n            }\n        ]\n    )\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n## Logging\n\nThe library includes comprehensive logging capabilities. You can enable and configure logging when initializing the client:\n\n```python\nclient = OllamaInstructor(\n    enable_logging=True,\n    log_level=\"DEBUG\",  # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL\n    log_format=\"%(asctime)s - %(name)s - %(levelname)s - %(message)s\"\n)\n```\n\n## Support and Community\n\nIf you need help or want to discuss `ollama-instructor`, feel free to:\n- Open an issue on GitHub\n- Start a discussion in the GitHub repository\n- Contact via email: lennartpollvogt@protonmail.com\n\nContributions and feedback are always welcome! 😊\n\n## License\n\n`ollama-instructor` is released under the MIT License. See the [LICENSE](LICENSE) file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flennartpollvogt%2Follama-instructor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flennartpollvogt%2Follama-instructor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flennartpollvogt%2Follama-instructor/lists"}