📦 Installation#

AI Cortex is published on PyPI and installs with a single command. No account, no API key, no configuration file required.

Requirements#

Requirement	Version
Python	3.8 or higher
Ollama	Any recent version (local or remote)

💡 No Ollama? No problem. AI Cortex ships with bundled metadata for community-hosted Ollama endpoints, so you can start chatting even without a local Ollama installation. For production use, running your own Ollama server is recommended.

Basic Installation#

Install the core package — one dependency (ollama), nothing else:

pip install aicortex-core

That’s all you need for chat(), model discovery, and streaming.

Installation with Extras#

🖥️ Server Mode#

To run the OpenAI-compatible REST API proxy, install the server extras:

pip install aicortex-core[server]

This additionally installs:

Package	Purpose
`fastapi`	High-performance async web framework
`uvicorn`	ASGI server for running FastAPI
`pydantic`	Request/response data validation

🛠️ Development#

For contributing or running the test suite:

pip install aicortex-core[dev]

Or install directly from source with all extras:

git clone https://github.com/eirasmx/aicortex.git
cd aicortex
pip install -e ".[server,dev]"

Installing Ollama (Optional but Recommended)#

For the best performance and privacy, run Ollama locally:

macOS / Linux:

curl -fsSL https://ollama.com/install.sh | sh

Windows: Download the installer from ollama.com.

Then pull a model to use locally:

ollama pull llama3.2:3b      # Fast, 3B parameter Llama model
ollama pull mistral:7b       # Mistral 7B — great all-rounder
ollama pull gemma2:9b        # Google Gemma 2 9B
ollama pull deepseek-r1:7b   # DeepSeek reasoning model

Start the server (it auto-starts on macOS/Linux after install):

ollama serve

Verify Your Installation#

Run this in Python to confirm everything is working:

import aicortex

# Check the version
print(aicortex.__version__)   # e.g. 1.0.3

# List available model families
print(aicortex.families())    # ['llama', 'mistral', 'gemma', 'deepseek', 'qwen']

# Quick connectivity check
print(aicortex.models("llama")[:3])  # First 3 Llama models

For a live end-to-end test (requires an Ollama server):

from aicortex import chat

response = chat("Say hello in one sentence.", model="llama3.2:3b")
print(response)

Upgrading#

pip install --upgrade aicortex-core

Troubleshooting#

ModuleNotFoundError: No module named 'aicortex' → Make sure you installed into the correct Python environment. Try python -m pip install aicortex-core.

RuntimeError: No servers available for model '...' → No live Ollama server was found for that model. Run ollama serve locally, or check that your remote server is reachable.

ImportError: FastAPI server requires additional dependencies → You tried to call run_server() without the server extras. Run pip install aicortex-core[server].

ValueError: Model '...' not found → The model name doesn’t exist in the bundled metadata. Use aicortex.models() to see all available names, or update the model database with the tools pipeline.

Next Steps#

→ Quick Start — get your first response in 5 minutes → Basic Usage — explore all parameters and patterns

📦 Installation

Contents