ollamafreeapi 0.1.0

A lightweight client for interacting with LLMs served via Ollama

OllamaFreeAPI

A lightweight, zero-configuration Python client for interacting with LLMs served via Ollama across distributed servers.

Relationship with ollama-python

OllamaFreeAPI builds upon the official ollama-python library with these key enhancements:

• Zero Configuration: No need to set up endpoints or API keys
• Pre-configured Models: Access to ready-to-use models across distributed servers
• Automatic Failover: Built-in load balancing across multiple Ollama instances
• Simplified Interface: Higher-level abstractions for common use cases

ℹ️ Under the hood, OllamaFreeAPI uses the official ollama Python client to communicate with Ollama servers.

Features

• 🚀 Instant Setup - Works out-of-the-box with no configuration
• 🌐 Distributed Network - Automatic routing to available servers
• 🔍 Model Discovery - Browse available models with list_families() and list_models()
• ⚡ Performance Optimized - Intelligent server selection based on latency
• 🔄 Seamless Integration - Compatible with existing Ollama deployments

Installation

pip install ollamafreeapi

Quick Start

from ollamafreeapi import OllamaFreeAPI

# Connect to the distributed Ollama network
client = OllamaFreeAPI()

# Discover available models
print("Available families:", client.list_families())
print("Mistral models:", client.list_models(family='mistral'))

# Have a conversation
response = client.chat(
    model_name="llama3:latest",
    prompt="Explain the difference between Python and JavaScript",
    temperature=0.7
)
print(response)

# Stream a response
for chunk in client.stream_chat("mistral:latest", "Write a short story about AI:"):
    print(chunk, end='', flush=True)

Advanced Features

Server Information

# Get all servers hosting a model
servers = client.get_model_servers("llama2:13b")
for server in servers:
    print(f"Server: {server['url']}")
    print(f"Location: {server['location']['country']}")
    print(f"Performance: {server['performance']['tokens_per_second']} tokens/s")

Request Generation

# Generate the raw API request
request = client.generate_api_request(
    model_name="deepseek-r1:7b",
    prompt="Explain blockchain technology",
    temperature=0.8,
    top_p=0.95,
    num_predict=256
)

Model Parameters

All API calls support these optional parameters:

Parameter	Type	Default	Description
temperature	float	0.7	Controls randomness (lower = more deterministic)
top_p	float	0.9	Probability threshold for nucleus sampling
num_predict	int	128	Maximum number of tokens to generate
stop	list[str]	[]	Sequences where the model will stop generating
repeat_penalty	float	1.1	Penalty for repeated content

Frequently Asked Questions

Q: How is this different from ollama-python?
A: OllamaFreeAPI provides pre-configured access to a distributed network of Ollama servers with automatic failover, while ollama-python requires manual server configuration.

Q: Do I need to run my own Ollama server?
A: No! OllamaFreeAPI connects to our managed network of servers by default.

Q: Can I use this with my existing Ollama installation?
A: Yes, you can configure it to use your local Ollama instance if preferred.

License

Distributed under the MIT License. See LICENSE for more information.

Support

For support, feature requests, or to report issues, please open an issue.