# Ollama Utils
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A Python library providing convenient utilities for integrating [Ollama](https://ollama.com) with Streamlit and Python applications. This package offers a simple, pythonic interface to Ollama's API with built-in Streamlit components for rapid prototyping of LLM applications.
## Features
- **Full HTTP API Integration** - No CLI dependencies
- =� **Streaming Support** - Real-time response streaming
- <� **Parameter Control** - Fine-tune model behavior (temperature, top_p, etc.)
- =� **Streamlit Components** - Ready-to-use UI components
- = **Model Management** - List, pull, delete, and inspect models
- =� **Chat Interface** - Multi-turn conversations
- <� **Simple API** - Easy to use, well-documented functions
## Installation
### Using uv (recommended)
```bash
uv add ollama-utils
```
### Using pip
```bash
pip install ollama-utils
```
## Prerequisites
1. **Install Ollama**: Download from [ollama.com](https://ollama.com)
2. **Start Ollama server**:
```bash
ollama serve
```
3. **Pull a model**:
```bash
ollama pull llama3.2:latest
```
## Quick Start
### Basic Text Generation
```python
from ollama_utils import generate_with_model
# Simple generation
response = generate_with_model("llama3.2:latest", "Write a haiku about Python")
print(response)
# With custom parameters
response = generate_with_model(
"llama3.2:latest",
"Explain quantum computing",
temperature=0.7,
num_predict=500
)
```
### Chat Conversations
```python
from ollama_utils import chat_with_model
messages = [
{"role": "user", "content": "Hello! What's the weather like?"},
{"role": "assistant", "content": "I don't have access to real-time weather data, but I can help you with weather-related questions!"},
{"role": "user", "content": "What should I wear in 70�F weather?"}
]
response = chat_with_model("llama3.2:latest", messages)
print(response)
```
### Streaming Responses
```python
from ollama_utils import generate_with_model
# Stream generation
for chunk in generate_with_model("llama3.2:latest", "Tell me a story", stream=True):
print(chunk, end="", flush=True)
# Stream chat
for chunk in chat_with_model("llama3.2:latest", messages, stream=True):
print(chunk, end="", flush=True)
```
### Model Management
```python
from ollama_utils import list_models, pull_model, delete_model, show_model
# List available models
models = list_models()
for model in models:
print(f"Model: {model['name']}, Size: {model['size']}")
# Pull a new model
result = pull_model("mistral:latest")
if result["success"]:
print("Model pulled successfully!")
# Get model info
info = show_model("llama3.2:latest")
print(info)
```
## Streamlit Integration
### Quick Chat Interface
```python
import streamlit as st
from ollama_utils.streamlit_helpers import chat_ui
st.title("My LLM Chat App")
# This creates a complete chat interface!
chat_ui()
```
### Custom Streamlit App
```python
import streamlit as st
from ollama_utils.streamlit_helpers import model_selector
from ollama_utils import generate_with_model
st.title("LLM Text Generator")
# Model selection dropdown
model = model_selector()
# Text input
prompt = st.text_area("Enter your prompt:")
if st.button("Generate"):
if model and prompt:
# Generate with streaming
response_placeholder = st.empty()
full_response = ""
for chunk in generate_with_model(model, prompt, stream=True):
full_response += chunk
response_placeholder.markdown(full_response + "�")
response_placeholder.markdown(full_response)
```
## API Reference
### Core Functions
#### `generate_with_model(model_name, prompt, stream=False, **kwargs)`
Generate text using the `/api/generate` endpoint.
**Parameters:**
- `model_name` (str): Name of the model (e.g., "llama3.2:latest")
- `prompt` (str): Input prompt
- `stream` (bool): Enable streaming responses
- `**kwargs`: Additional parameters (temperature, top_p, num_predict, etc.)
**Returns:**
- If `stream=False`: Complete response as string
- If `stream=True`: Generator yielding response chunks
#### `chat_with_model(model_name, messages, stream=False, **kwargs)`
Multi-turn chat using the `/api/chat` endpoint.
**Parameters:**
- `model_name` (str): Name of the model
- `messages` (List[dict]): List of messages with "role" and "content" keys
- `stream` (bool): Enable streaming responses
- `**kwargs`: Additional parameters
**Returns:**
- If `stream=False`: Complete response as string
- If `stream=True`: Generator yielding response chunks
#### `list_models()`
List all locally installed models.
**Returns:**
- List of model dictionaries with metadata
#### `pull_model(model_name)`
Download a model from Ollama registry.
**Parameters:**
- `model_name` (str): Name of the model to pull
**Returns:**
- Dictionary with "success" and "output"/"error" keys
#### `delete_model(model_name)`
Remove a model from local cache.
**Parameters:**
- `model_name` (str): Name of the model to delete
**Returns:**
- Dictionary with "success" and "output"/"error" keys
#### `show_model(model_name)`
Display detailed information about a model.
**Parameters:**
- `model_name` (str): Name of the model
**Returns:**
- Formatted string with model information
#### `is_model_installed(model_name)`
Check if a model is installed locally.
**Parameters:**
- `model_name` (str): Name of the model
**Returns:**
- Boolean indicating if the model is installed
### Streamlit Helpers
#### `model_selector(label="Select a local model", sidebar=True)`
Create a dropdown selector for available models.
**Parameters:**
- `label` (str): Label for the selector
- `sidebar` (bool): Whether to place in sidebar
**Returns:**
- Selected model name or None
#### `chat_ui(model_name=None, streaming=True)`
Complete chat interface with history and controls.
**Parameters:**
- `model_name` (str, optional): Model to use (if None, shows selector)
- `streaming` (bool): Enable streaming responses
## Advanced Usage
### Custom Parameters
```python
# Fine-tune model behavior
response = generate_with_model(
"llama3.2:latest",
"Explain machine learning",
temperature=0.8, # Creativity (0.0-2.0)
top_p=0.9, # Nucleus sampling (0.0-1.0)
top_k=40, # Top-k sampling (1-100)
repeat_penalty=1.1, # Repetition penalty (0.0-2.0)
num_predict=1000, # Max tokens to generate
)
```
### Error Handling
```python
from ollama_utils import chat_with_model
try:
response = chat_with_model("nonexistent-model", messages)
if response.startswith("Chat error"):
print(f"Error occurred: {response}")
else:
print(f"Response: {response}")
except Exception as e:
print(f"Unexpected error: {e}")
```
## Demo Application
Run the included demo to test all features:
```bash
git clone https://github.com/malpasocodes/ollama-utils.git
cd ollama-utils
uv sync
uv run streamlit run demo_app.py
```
The demo includes:
- Model management interface
- Text generation testing
- Chat interface
- API parameter testing
- Full chat UI demonstration
## Requirements
- Python 3.8+
- [Ollama](https://ollama.com) installed and running
- `requests` library
- `streamlit` library (for Streamlit helpers)
## Contributing
1. Fork the repository
2. Clone and set up development environment:
```bash
git clone https://github.com/your-username/ollama-utils.git
cd ollama-utils
uv sync
```
3. Create a feature branch (`git checkout -b feature/amazing-feature`)
4. Run tests: `uv run pytest`
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- **Issues**: [GitHub Issues](https://github.com/malpasocodes/ollama-utils/issues)
- **Discussions**: [GitHub Discussions](https://github.com/malpasocodes/ollama-utils/discussions)
- **Documentation**: [API Reference](https://github.com/malpasocodes/ollama-utils#api-reference)
## Changelog
### 0.1.0
- Initial release
- Full HTTP API integration
- Streaming support
- Streamlit helpers
- Model management functions
- Chat and generation capabilities
Raw data
{
"_id": null,
"home_page": null,
"name": "ollama-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ollama, llm, streamlit, ai, chatbot, language-model, ml, nlp",
"author": null,
"author_email": "Alfred Essa <malpaso@alfredcodes.com>",
"download_url": "https://files.pythonhosted.org/packages/7d/c2/e241fc0c0abd876bc7c546660e5402ba933ca7f39e9f383061ad9ca15550/ollama_utils-0.1.0.tar.gz",
"platform": null,
"description": "# Ollama Utils\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA Python library providing convenient utilities for integrating [Ollama](https://ollama.com) with Streamlit and Python applications. This package offers a simple, pythonic interface to Ollama's API with built-in Streamlit components for rapid prototyping of LLM applications.\n\n## Features\n\n- \u0005 **Full HTTP API Integration** - No CLI dependencies\n- =\ufffd **Streaming Support** - Real-time response streaming\n- <\ufffd\u000f **Parameter Control** - Fine-tune model behavior (temperature, top_p, etc.)\n- =\ufffd **Streamlit Components** - Ready-to-use UI components\n- =\u0004 **Model Management** - List, pull, delete, and inspect models\n- =\ufffd **Chat Interface** - Multi-turn conversations\n- <\ufffd **Simple API** - Easy to use, well-documented functions\n\n## Installation\n\n### Using uv (recommended)\n```bash\nuv add ollama-utils\n```\n\n### Using pip\n```bash\npip install ollama-utils\n```\n\n## Prerequisites\n\n1. **Install Ollama**: Download from [ollama.com](https://ollama.com)\n\n2. **Start Ollama server**:\n ```bash\n ollama serve\n ```\n\n3. **Pull a model**:\n ```bash\n ollama pull llama3.2:latest\n ```\n\n## Quick Start\n\n### Basic Text Generation\n\n```python\nfrom ollama_utils import generate_with_model\n\n# Simple generation\nresponse = generate_with_model(\"llama3.2:latest\", \"Write a haiku about Python\")\nprint(response)\n\n# With custom parameters\nresponse = generate_with_model(\n \"llama3.2:latest\", \n \"Explain quantum computing\",\n temperature=0.7,\n num_predict=500\n)\n```\n\n### Chat Conversations\n\n```python\nfrom ollama_utils import chat_with_model\n\nmessages = [\n {\"role\": \"user\", \"content\": \"Hello! What's the weather like?\"},\n {\"role\": \"assistant\", \"content\": \"I don't have access to real-time weather data, but I can help you with weather-related questions!\"},\n {\"role\": \"user\", \"content\": \"What should I wear in 70\ufffdF weather?\"}\n]\n\nresponse = chat_with_model(\"llama3.2:latest\", messages)\nprint(response)\n```\n\n### Streaming Responses\n\n```python\nfrom ollama_utils import generate_with_model\n\n# Stream generation\nfor chunk in generate_with_model(\"llama3.2:latest\", \"Tell me a story\", stream=True):\n print(chunk, end=\"\", flush=True)\n\n# Stream chat\nfor chunk in chat_with_model(\"llama3.2:latest\", messages, stream=True):\n print(chunk, end=\"\", flush=True)\n```\n\n### Model Management\n\n```python\nfrom ollama_utils import list_models, pull_model, delete_model, show_model\n\n# List available models\nmodels = list_models()\nfor model in models:\n print(f\"Model: {model['name']}, Size: {model['size']}\")\n\n# Pull a new model\nresult = pull_model(\"mistral:latest\")\nif result[\"success\"]:\n print(\"Model pulled successfully!\")\n\n# Get model info\ninfo = show_model(\"llama3.2:latest\")\nprint(info)\n```\n\n## Streamlit Integration\n\n### Quick Chat Interface\n\n```python\nimport streamlit as st\nfrom ollama_utils.streamlit_helpers import chat_ui\n\nst.title(\"My LLM Chat App\")\n\n# This creates a complete chat interface!\nchat_ui()\n```\n\n### Custom Streamlit App\n\n```python\nimport streamlit as st\nfrom ollama_utils.streamlit_helpers import model_selector\nfrom ollama_utils import generate_with_model\n\nst.title(\"LLM Text Generator\")\n\n# Model selection dropdown\nmodel = model_selector()\n\n# Text input\nprompt = st.text_area(\"Enter your prompt:\")\n\nif st.button(\"Generate\"):\n if model and prompt:\n # Generate with streaming\n response_placeholder = st.empty()\n full_response = \"\"\n \n for chunk in generate_with_model(model, prompt, stream=True):\n full_response += chunk\n response_placeholder.markdown(full_response + \"\ufffd\")\n \n response_placeholder.markdown(full_response)\n```\n\n## API Reference\n\n### Core Functions\n\n#### `generate_with_model(model_name, prompt, stream=False, **kwargs)`\nGenerate text using the `/api/generate` endpoint.\n\n**Parameters:**\n- `model_name` (str): Name of the model (e.g., \"llama3.2:latest\")\n- `prompt` (str): Input prompt\n- `stream` (bool): Enable streaming responses\n- `**kwargs`: Additional parameters (temperature, top_p, num_predict, etc.)\n\n**Returns:**\n- If `stream=False`: Complete response as string\n- If `stream=True`: Generator yielding response chunks\n\n#### `chat_with_model(model_name, messages, stream=False, **kwargs)`\nMulti-turn chat using the `/api/chat` endpoint.\n\n**Parameters:**\n- `model_name` (str): Name of the model\n- `messages` (List[dict]): List of messages with \"role\" and \"content\" keys\n- `stream` (bool): Enable streaming responses\n- `**kwargs`: Additional parameters\n\n**Returns:**\n- If `stream=False`: Complete response as string\n- If `stream=True`: Generator yielding response chunks\n\n#### `list_models()`\nList all locally installed models.\n\n**Returns:**\n- List of model dictionaries with metadata\n\n#### `pull_model(model_name)`\nDownload a model from Ollama registry.\n\n**Parameters:**\n- `model_name` (str): Name of the model to pull\n\n**Returns:**\n- Dictionary with \"success\" and \"output\"/\"error\" keys\n\n#### `delete_model(model_name)`\nRemove a model from local cache.\n\n**Parameters:**\n- `model_name` (str): Name of the model to delete\n\n**Returns:**\n- Dictionary with \"success\" and \"output\"/\"error\" keys\n\n#### `show_model(model_name)`\nDisplay detailed information about a model.\n\n**Parameters:**\n- `model_name` (str): Name of the model\n\n**Returns:**\n- Formatted string with model information\n\n#### `is_model_installed(model_name)`\nCheck if a model is installed locally.\n\n**Parameters:**\n- `model_name` (str): Name of the model\n\n**Returns:**\n- Boolean indicating if the model is installed\n\n### Streamlit Helpers\n\n#### `model_selector(label=\"Select a local model\", sidebar=True)`\nCreate a dropdown selector for available models.\n\n**Parameters:**\n- `label` (str): Label for the selector\n- `sidebar` (bool): Whether to place in sidebar\n\n**Returns:**\n- Selected model name or None\n\n#### `chat_ui(model_name=None, streaming=True)`\nComplete chat interface with history and controls.\n\n**Parameters:**\n- `model_name` (str, optional): Model to use (if None, shows selector)\n- `streaming` (bool): Enable streaming responses\n\n## Advanced Usage\n\n### Custom Parameters\n\n```python\n# Fine-tune model behavior\nresponse = generate_with_model(\n \"llama3.2:latest\",\n \"Explain machine learning\",\n temperature=0.8, # Creativity (0.0-2.0)\n top_p=0.9, # Nucleus sampling (0.0-1.0)\n top_k=40, # Top-k sampling (1-100)\n repeat_penalty=1.1, # Repetition penalty (0.0-2.0)\n num_predict=1000, # Max tokens to generate\n)\n```\n\n### Error Handling\n\n```python\nfrom ollama_utils import chat_with_model\n\ntry:\n response = chat_with_model(\"nonexistent-model\", messages)\n if response.startswith(\"Chat error\"):\n print(f\"Error occurred: {response}\")\n else:\n print(f\"Response: {response}\")\nexcept Exception as e:\n print(f\"Unexpected error: {e}\")\n```\n\n## Demo Application\n\nRun the included demo to test all features:\n\n```bash\ngit clone https://github.com/malpasocodes/ollama-utils.git\ncd ollama-utils\nuv sync\nuv run streamlit run demo_app.py\n```\n\nThe demo includes:\n- Model management interface\n- Text generation testing\n- Chat interface\n- API parameter testing\n- Full chat UI demonstration\n\n## Requirements\n\n- Python 3.8+\n- [Ollama](https://ollama.com) installed and running\n- `requests` library\n- `streamlit` library (for Streamlit helpers)\n\n## Contributing\n\n1. Fork the repository\n2. Clone and set up development environment:\n ```bash\n git clone https://github.com/your-username/ollama-utils.git\n cd ollama-utils\n uv sync\n ```\n3. Create a feature branch (`git checkout -b feature/amazing-feature`)\n4. Run tests: `uv run pytest`\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/malpasocodes/ollama-utils/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/malpasocodes/ollama-utils/discussions)\n- **Documentation**: [API Reference](https://github.com/malpasocodes/ollama-utils#api-reference)\n\n## Changelog\n\n### 0.1.0\n- Initial release\n- Full HTTP API integration\n- Streaming support\n- Streamlit helpers\n- Model management functions\n- Chat and generation capabilities\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python utilities for integrating Ollama with Streamlit and building LLM applications",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/malpasocodes/ollama-utils#readme",
"Homepage": "https://github.com/malpasocodes/ollama-utils",
"Issues": "https://github.com/malpasocodes/ollama-utils/issues",
"Repository": "https://github.com/malpasocodes/ollama-utils"
},
"split_keywords": [
"ollama",
" llm",
" streamlit",
" ai",
" chatbot",
" language-model",
" ml",
" nlp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cdaa0b4ebda0a9594605ba2f63cb25d629d2bb45ef5247717737f6682995791b",
"md5": "1636c676f88fd55a56b4b02fb2b79057",
"sha256": "8c19d1a7a20a1e0f0c8f80f42263597aa34c0ca9e5acd8411174d2bdf669bd05"
},
"downloads": -1,
"filename": "ollama_utils-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1636c676f88fd55a56b4b02fb2b79057",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9433,
"upload_time": "2025-07-18T23:27:35",
"upload_time_iso_8601": "2025-07-18T23:27:35.178664Z",
"url": "https://files.pythonhosted.org/packages/cd/aa/0b4ebda0a9594605ba2f63cb25d629d2bb45ef5247717737f6682995791b/ollama_utils-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7dc2e241fc0c0abd876bc7c546660e5402ba933ca7f39e9f383061ad9ca15550",
"md5": "67205e3f3c67071be3cb73301c5ea429",
"sha256": "48dc1d402f88461f25fa0379bb0a9848a6868ab428ebf1715aab0f6504890b69"
},
"downloads": -1,
"filename": "ollama_utils-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "67205e3f3c67071be3cb73301c5ea429",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18059,
"upload_time": "2025-07-18T23:27:36",
"upload_time_iso_8601": "2025-07-18T23:27:36.207166Z",
"url": "https://files.pythonhosted.org/packages/7d/c2/e241fc0c0abd876bc7c546660e5402ba933ca7f39e9f383061ad9ca15550/ollama_utils-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 23:27:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "malpasocodes",
"github_project": "ollama-utils#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ollama-utils"
}
JSON
