AbstractCore Troubleshooting Guide

from abstractcore import create_llm, tool

# Use @tool decorator for automatic tool definition
@tool
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Weather in {city}: sunny, 72°F"

llm = create_llm("openai", model="gpt-4o-mini")
response = llm.generate(
    "What's the weather in Tokyo?",
    tools=[get_weather]  # Pass decorated function directly
)

from abstractcore import create_llm
from abstractcore.exceptions import ProviderAPIError, RateLimitError

providers = [
    ("openai", "gpt-4o-mini"),
    ("anthropic", "claude-haiku-4-5"),
    ("ollama", "qwen3-coder:30b")
]

def generate_with_fallback(prompt):
    for provider, model in providers:
        try:
            llm = create_llm(provider, model=model)
            return llm.generate(prompt)
        except (ProviderAPIError, RateLimitError) as e:
            print(f"Failed with {provider}: {e}")
            continue
    raise Exception("All providers failed")

# Optimize memory and performance
response = llm.generate(
    "Complex task",
    max_tokens=1000,  # Limit response length
    timeout=30,       # Set reasonable timeout
    temperature=0.7   # Control creativity/randomness
)

import os
from abstractcore import create_llm

# Best practice: Load from environment
OPENAI_API_KEY = os.getenv('OPENAI_API_KEY')
DEFAULT_MODEL = os.getenv('DEFAULT_LLM_MODEL', 'gpt-4o-mini')

llm = create_llm(
    "openai",
    model=DEFAULT_MODEL,
    api_key=OPENAI_API_KEY
)

# Check Python version
python --version  # Should be 3.9+

# Check AbstractCore installation
pip show abstractcore

# Test core library
python -c "from abstractcore import create_llm; print('✓ Core library OK')"

# Test server (if installed)
curl http://localhost:8000/health  # Should return {"status":"healthy"}

ModuleNotFoundError: No module named .abstractcore.
ModuleNotFoundError: No module named 'openai'

# Install AbstractCore
pip install abstractcore

# Install with specific provider
pip install "abstractcore[openai]"
pip install "abstractcore[anthropic]"
# Local OpenAI-compatible servers (Ollama, LMStudio, vLLM, llama.cpp, ...) work with the core install.

# Install the full feature set (pick one)
pip install "abstractcore[all-apple]"    # macOS/Apple Silicon (includes MLX, excludes vLLM)
pip install "abstractcore[all-non-mlx]"  # Linux/Windows/Intel Mac (excludes MLX and vLLM)
pip install "abstractcore[all-gpu]"      # Linux NVIDIA GPU (includes vLLM, excludes MLX)

# Verify installation
pip list | grep abstract

ERROR: pip's dependency resolver does not currently take into account all the packages...

# Create clean environment
python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# OR
.venv\Scripts\activate  # Windows

# Fresh install
pip install --upgrade pip
pip install "abstractcore[all-apple]"    # macOS/Apple Silicon
# or: pip install "abstractcore[all-non-mlx]"  # Linux/Windows/Intel Mac
# or: pip install "abstractcore[all-gpu]"      # Linux NVIDIA GPU

# If still failing, try one provider at a time
pip install "abstractcore[openai]"

Error: OpenAI API key not found
Error: Authentication failed
Error: Invalid API key

# Check if API key is set
echo $OPENAI_API_KEY  # Should show your key
echo $ANTHROPIC_API_KEY

# Set API key
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Add to shell profile for persistence
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.bashrc
source ~/.bashrc

# Verify key format
# OpenAI: starts with "sk-"
# Anthropic: starts with "sk-ant-"

# Test authentication
python -c "from abstractcore import create_llm; llm = create_llm('openai', model='gpt-4o-mini'); print(llm.generate('test').content)"

Error: Model 'qwen3-coder:30b' not found
Error: Unsupported model

# Check available models
ollama list

# Pull missing model
ollama pull qwen3-coder:30b

# Verify Ollama is running
ollama serve

# Check LMStudio server
curl http://localhost:1234/v1/models

# In LMStudio GUI:
# 1. Go to "Local Server" tab
# 2. Select model from dropdown
# 3. Click "Start Server"

# Use correct model names
llm = create_llm("openai", model="gpt-4o-mini")  # ✓ Correct
llm = create_llm("openai", model="gpt4")  # ✗ Wrong

llm = create_llm("anthropic", model="claude-haiku-4-5")  # ✓ Correct
llm = create_llm("anthropic", model="claude-3")  # ✗ Wrong

Connection refused
Timeout error
Network error

# Start Ollama service
ollama serve

# Check if running
curl http://localhost:11434/api/tags

# If using custom host
export OLLAMA_HOST="http://localhost:11434"

# Verify server is running
curl http://localhost:1234/v1/models

# Check port in LMStudio GUI (usually 1234)

# Test network connection
ping api.openai.com
ping api.anthropic.com

# Check proxy settings
echo $HTTP_PROXY
echo $HTTPS_PROXY

# Disable proxy if needed
unset HTTP_PROXY
unset HTTPS_PROXY

from abstractcore import create_llm, tool

# Ensure @tool decorator is used
@tool
def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"Weather in {city}: sunny, 72°F"

# Use tool correctly
llm = create_llm("openai", model="gpt-4o-mini")
response = llm.generate(
    "What's the weather in Paris?",
    tools=[get_weather]  # Pass as list
)

# Check if tool was called
if hasattr(response, 'tool_calls') and response.tool_calls:
    print("Tools were called")

Address already in use
Port 8000 is already allocated

# Check what's using port 8000
lsof -i :8000  # Linux/Mac
netstat -ano | findstr :8000  # Windows

# Kill process on port
kill -9 $(lsof -t -i:8000)  # Linux/Mac

# Use different port
uvicorn abstractcore.server.app:app --port 3000

# Most OpenAI-compatible clients accept a dummy key for local servers.
export OPENAI_BASE_URL="http://localhost:8000/v1"
export OPENAI_API_KEY="unused"

# Verify they're set
echo "$OPENAI_BASE_URL"
echo "$OPENAI_API_KEY"

# Check server is actually running
curl http://localhost:8000/health

# Check server logs
tail -f logs/abstractcore_*.log

# Enable debug mode
export ABSTRACTCORE_DEBUG=true
uvicorn abstractcore.server.app:app --host 0.0.0.0 --port 8000

# Test with simple request
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "test"}]}'

curl http://localhost:8000/v1/models returns empty list

# Check if providers are configured
curl http://localhost:8000/providers

# Verify provider setup:

# For Ollama
ollama list  # Should show models
ollama serve  # Make sure it's running

# For OpenAI
echo $OPENAI_API_KEY  # Should be set

# For Anthropic
echo $ANTHROPIC_API_KEY  # Should be set

# For LMStudio
curl http://localhost:1234/v1/models  # Should return models

# AbstractCore Server controls tool-call syntax via `agent_format` (request field) or auto-detection.
# - OpenAI/Codex style: structured tool calls are returned in `tool_calls` fields.
# - Tag-based formats: tool calls are emitted as tagged content for clients that parse from assistant text.

# If you control requests (curl/custom client), force a format with `agent_format`:
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ollama/qwen3:4b-instruct-2507-q4_K_M",
    "messages": [{"role": "user", "content": "Use the tool."}],
    "tools": [{"type":"function","function":{"name":"get_weather","description":"...","parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}}],
    "agent_format": "llama3"
  }'

# Restart Ollama
pkill ollama
ollama serve

# Check status
curl http://localhost:11434/api/tags

# List models
ollama list

# Pull model if missing
ollama pull qwen3-coder:30b

# Use smaller models
ollama pull gemma3:1b  # Only 1GB
ollama pull qwen3:4b-instruct-2507-q4_K_M  # 4GB

# Check system memory
free -h  # Linux
vm_stat  # macOS

# Close other applications

# Check your rate limits
# https://platform.openai.com/account/rate-limits

# Implement backoff in code
import time
try:
    response = llm.generate("prompt")
except RateLimitError:
    time.sleep(20)  # Wait before retry

# Check billing dashboard
# https://platform.openai.com/account/billing

# Verify payment method is added
# Check usage limits aren't exceeded

# Anthropic keys start with "sk-ant-"
echo $ANTHROPIC_API_KEY  # Should start with sk-ant-

# Get key from console
# https://console.anthropic.com/

# Verify LMStudio server is running
# Check LMStudio GUI shows "Server running"

# Test connection
curl http://localhost:1234/v1/models

# Check port number in LMStudio (usually 1234)

# CRITICAL: Ensure LM Studio server is enabled in the GUI
# 1. Open LM Studio application
# 2. Look for "Status: Running" toggle switch in the interface
# 3. Make sure the toggle is switched to "ON" (green background, white handle on right)
# 4. If the toggle shows "OFF", click it to enable the server
# 5. Verify the server is running by checking the status indicator

# Test server availability
curl http://localhost:1234/v1/models

# If still failing, check LM Studio logs for any error messages

# Problem: LLM returns 400 Bad Request, truncated output, or errors with long inputs
# Root Cause: Insufficient context length configured for the model or server

# Solution 1: Increase Default Context Length (RECOMMENDED)
# This is the most robust way to ensure all models use maximum available context
# 1. Open LM Studio application
# 2. Go to "App Settings" → "General" tab
# 3. Find "Model Defaults" → "Default Context Length"
# 4. Set dropdown to "Model Maximum" (or highest available value like 131072)
# 5. Restart LM Studio server for changes to take effect

# Solution 2: Increase Context Length per Model (Alternative)
# This method applies context length setting to a specific model
# 1. Open LM Studio application
# 2. Go to "My Models" tab
# 3. Select the specific model you are using
# 4. Look for "Context Length" slider/input (usually under "Load" or "Context" tab)
# 5. Adjust slider to maximum value (e.g., 131072 tokens)
# 6. Reload the model for changes to take effect

# Solution 3: Increase Context Length via API Request (Advanced)
# For Ollama, or if you need to override settings for LM Studio via API
# For Ollama:
ollama run <model_name> -c <context_length>
# Example: ollama run llama2 -c 4096

# For LM Studio via API (often handled automatically by AbstractCore):
# Include in request payload:
# {
#   "model": "your-model-name",
#   "prompt": "Your long prompt here...",
#   "options": {
#     "num_ctx": 4096  # Or your desired context length
#   }
# }

# Verification:
# After adjusting, test with a long prompt that previously failed
# Check server logs for any warnings or errors related to context

# Time a request
time python -c "from abstractcore import create_llm; llm = create_llm('ollama', model='qwen3:4b-instruct-2507-q4_K_M'); print(llm.generate('test').content)"

# Faster cloud models
llm = create_llm("openai", model="gpt-4o-mini")  # Fast
llm = create_llm("anthropic", model="claude-haiku-4-5")  # Fast

# Faster local models
llm = create_llm("ollama", model="gemma3:1b")  # Very fast
llm = create_llm("ollama", model="qwen3:4b-instruct-2507-q4_K_M")  # Balanced

# Improves perceived speed
for chunk in llm.generate("Long response", stream=True):
    print(chunk.content, end="", flush=True)

response = llm.generate(
    "prompt",
    max_tokens=500,      # Limit length
    temperature=0.3      # Lower = faster
)

# Use smaller models
ollama pull gemma3:1b  # 1GB instead of 30GB

# Close other applications

# For MLX on Mac
# Use 4-bit quantized models
llm = create_llm("mlx", model="mlx-community/Llama-3.2-3B-Instruct-4bit")

import logging
logging.basicConfig(level=logging.DEBUG)

from abstractcore import create_llm
llm = create_llm("openai", model="gpt-4o-mini")

# Enable debug mode
export ABSTRACTCORE_DEBUG=true

# Start with debug logging
uvicorn abstractcore.server.app:app --log-level debug

# Monitor logs
tail -f logs/abstractcore_*.log

# Find errors
grep '"level": "error"' logs/abstractcore_*.log

# Track specific request
grep "req_abc123" logs/abstractcore_*.log

# Monitor latency
cat logs/verbatim_*.jsonl | jq '.metadata.latency_ms'

# Token usage
cat logs/verbatim_*.jsonl | jq '.metadata.tokens | .input + .output' | \
  awk '{sum+=$1} END {print "Total:", sum}'

# Test provider directly
from abstractcore import create_llm

try:
    llm = create_llm("openai", model="gpt-4o-mini")
    response = llm.generate("Hello")
    print(f"✓ Success: {response.content}")
except Exception as e:
    print(f"✗ Error: {e}")

# Create debug report
echo "=== System ===" > debug_report.txt
uname -a >> debug_report.txt
python --version >> debug_report.txt

echo "=== Packages ===" >> debug_report.txt
pip freeze | grep -E "abstract|openai|anthropic" >> debug_report.txt

echo "=== Environment ===" >> debug_report.txt
env | grep -E "ABSTRACT|OPENAI|ANTHROPIC|OLLAMA" >> debug_report.txt

echo "=== Tests ===" >> debug_report.txt
python -c "from abstractcore import create_llm; print('Core library: OK')" >> debug_report.txt 2>&1
curl http://localhost:8000/health >> debug_report.txt 2>&1

cat debug_report.txt