oshepherd 0.0.23

The Oshepherd guiding the Ollama(s) inference orchestration.

oshepherd

The Oshepherd guiding the Ollama(s) inference orchestration.

A centralized FastAPI service, using Celery and Redis to orchestrate multiple Ollama servers as workers.

Install

pip install oshepherd

Usage

1. Setup Redis:

   Celery uses Redis as message broker and backend. You'll need a Redis instance, which you can provision for free in redislabs.com.

2. Setup FastAPI Server:

   # define configuration env file
   # use credentials for redis as broker and backend
   cp .api.env.template .api.env
   
   # start api
   oshepherd start-api --env-file .api.env
   

3. Setup Celery/Ollama Worker(s):

   # install ollama https://ollama.com/download
   # optionally pull the model
   ollama pull mistral
   
   # define configuration env file
   # use credentials for redis as broker and backend
   cp .worker.env.template .worker.env
   
   # start worker
   oshepherd start-worker --env-file .worker.env
   

Logging

Oshepherd uses Python's standard logging library for both the API server and Celery worker.

Set LOGLEVEL in either .api.env or .worker.env to control verbosity:

LOGLEVEL="info"

Valid values include debug, info, warning, error, and critical. API access logs from Uvicorn are disabled by default; enable them with:

UVICORN_ACCESS_LOG=true

Request and response payload bodies are only logged at debug level because they may contain prompts, model output, or other sensitive data.

4. Now you're ready to execute Ollama completions remotely. You can point your Ollama client to your oshepherd api server by setting the host, and it will return your requested completions from any of the workers:

   • ollama-python client:

   import ollama
   
   client = ollama.Client(host="http://127.0.0.1:5001")
   
   # Standard request
   response = client.generate(model="mistral", prompt="Why is the sky blue?")
   
   # Streaming request
   for chunk in client.generate(model="mistral", prompt="Why is the sky blue?", stream=True):
       print(chunk['response'], end='', flush=True)
   

   For a complete Python example with streaming support, see examples/pretty_streaming.py.

   • ollama-js client:

   import { Ollama } from "ollama/browser";
   
   const ollama = new Ollama({ host: "http://127.0.0.1:5001" });
   
   // Standard request
   const response = await ollama.generate({
       model: "mistral",
       prompt: "Why is the sky blue?",
   });
   
   // Streaming request
   const streamResponse = await ollama.generate({
       model: "mistral",
       prompt: "Why is the sky blue?",
       stream: true
   });
   
   for await (const chunk of streamResponse) {
       process.stdout.write(chunk.response);
   }
   

   For a complete TypeScript/JavaScript example with streaming support, see examples/ts-scripts/README.md.

   • Raw http request:

   curl -X POST -H "Content-Type: application/json" -L http://127.0.0.1:5001/api/generate/ \
   -d '{"model":"mistral","prompt":"Why is the sky blue?","stream":true}' \
   --no-buffer
   

Example: PyCon Austria 2025

For a practical example of how oshepherd can be used to orchestrate on-premise open-source LLMs, see the companion repository from the PyCon Austria 2025 talk "Beyond the Cloud: On-Premise Orchestration for Open-Source LLMs":

• Repository: https://github.com/mnemonica-ai/on-premise-orchestration-os-llms
• Deck: https://speakerdeck.com/p1nox/beyond-the-cloud-on-premise-orchestration-for-open-source-llms

Disclaimers 🚨

This package is in alpha, its architecture and api might change in the near future. Currently this is getting tested in a controlled environment by real users, but haven't been audited, nor tested thorugly. Use it at your own risk.

As this is an alpha version, support and responses might be limited. We'll do our best to address questions and issues as quickly as possible.

API server parity

• Generate a completion: POST /api/generate
• Generate a chat completion: POST /api/chat
• Generate Embeddings: POST /api/embeddings
• List Local Models: GET /api/tags
• Version: GET /api/version
• Show Model Information: POST /api/show
• List Running Models: GET /api/ps

Oshepherd API server currently supports the endpoints listed above, enabling full compatibility with official Ollama clients (i.e.: ollama-python, ollama-js). These endpoints provide comprehensive functionality for the most common use cases. Additional endpoints from the official Ollama API are not planned for the near future. For more details on the full Ollama API specifications, refer to the Ollama API documentation.

Contribution guidelines

We welcome contributions! If you find a bug or have suggestions for improvements, please open an issue or submit a pull request pointing to development branch. Before creating a new issue/pull request, take a moment to search through the existing issues/pull requests to avoid duplicates.

Conda Support

To run and build locally you can use conda:

conda create -n oshepherd python=3.12
conda activate oshepherd
pip install -r requirements.txt

# install oshepherd
pip install -e .

Tests

The e2e tests require the following models to be available on your local Ollama instance:

ollama pull mistral        # used by generate, chat, and show tests
ollama pull embeddinggemma # used by embeddings tests

Then follow the usage instructions to start the API server and Celery worker, and run:

pytest -s tests/

Author

This is a project developed and maintained by mnemonica.ai.

License

MIT