bearjcc/quack-language-model

QLM - Quack Language Model 🦆

A humorous open-source project that brings the rubber duck back to debugging! QLM is a fake Large Language Model that responds to API requests with duck sounds instead of actual AI content.

  

What is QLM?

While others chase AGI, we've achieved ADI: Artificial Duck Intelligence.

QLM (Quack Language Model) is an OpenAI-compatible API that responds exclusively with duck sounds. Some might be stuck on a high horse. We're not sure how to get down from a duck.

Use Cases:

• —Rubber Duck Debugging: Now with actual ducks
• —API Testing: Mock OpenAI-compatible responses
• —Humor: Bringing joy back to development
• —Demonstrating API Compatibility: Educational and entertaining

Features

• —✅ OpenAI API Compatible: Full compatibility with /v1/* endpoints
• —✅ API Key Authentication: Secure authentication with duck-themed keys (sk-v1-42...)
• —✅ Duck Reasoning: reasoning_effort parameter for OpenAI-compatible reasoning
• —✅ Multiple Models: Standard (quack-model) and reasoning (reasoning-duck) models
• —✅ Rich Duck Emojis: 24+ different duck sounds, emojis, and combinations
• —✅ Varied Responses: No consecutive duplicates for more entertaining interactions
• —✅ Web Interface: Interactive demo via GitHub Pages
• —✅ Production Ready: CORS support, error handling, logging

Quick Start

Local Development

1. 1.Clone and setup:

git clone https://github.com/bearjcc/QLM.git
cd QLM
pip install -r requirements.txt

1. 1.Run the API server:

cd api
python main.py

1. 1.Test the API (requires authentication):

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-v1-42your-api-key-here" \
  -d '{
    "model": "quack-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

⚠️ Authentication Required: All API endpoints require an API key starting with sk-v1-42. Requests without proper authentication will return a 401 error.

With Reasoning:

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-v1-42your-api-key-here" \
  -d '{
    "model": "reasoning-duck",
    "messages": [{"role": "user", "content": "Help debug this code!"}],
    "reasoning_effort": "high"
  }'

1. 1.Open the web interface:

cd frontend
# Open index.html in your browser

Using with OpenAI Client

QLM works as a drop-in replacement for OpenAI API:

import openai

# Point to QLM instead of OpenAI
openai.api_base = "http://localhost:8000/v1"
openai.api_key = "sk-v1-42test"

response = openai.ChatCompletion.create(
    model="quack-model",
    messages=[{"role": "user", "content": "Help me debug this code!"}]
)

print(response.choices[0].message.content)  # "Quack!" or similar

Duck Sound Distribution

QLM generates responses based on realistic duck sound probabilities:

Duck Thinking Feature

Enable duck-themed thinking messages by setting quack_thinking: true in your request:

Example Response with Thinking:

{
  "choices": [{
    "message": {
      "content": "🦆💦 splash... quack... splash...\n\n🦆🫧",
      "role": "assistant"
    }
  }]
}

Available Thinking Messages:

• —🦆💦 splash... quack... splash...
• —🦆💭 Hmm... bread? No. Let's think about this...
• —🦆🫧 *bubbling thoughts*
• —🦆🔍 *inspecting the pond*
• —And 11 more silly duck-themed thinking variations!

The system uses cryptographically secure random generation to ensure fair distribution of all duck sounds.

Available Models

• —`quack-model`: Standard duck responses with basic functionality
• —`reasoning-duck`: Advanced model with reasoning capabilities and enhanced responses

API Endpoints

All endpoints require authentication with an API key starting with sk-v1-42.

Chat Completions (OpenAI Compatible)

POST /v1/chat/completions

Standard OpenAI chat completion format with duck responses.

Request:

{
  "model": "quack-model",
  "messages": [
    {"role": "user", "content": "Your message here"}
  ],
  "reasoning_effort": "medium",  // Optional: "low", "medium", "high"
  "quack_thinking": true         // Optional: Enable duck-themed thinking messages
}

Authentication:

Authorization: Bearer sk-v1-42your-api-key-here

Response (Reasoning Model):

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "reasoning-duck",
  "choices": [{
    "message": {
      "content": "🦆🔬 *conducting aquatic research...*\n\n🦆",
      "role": "assistant"
    },
    "reasoning": "🦆🔬 *conducting aquatic research...*",
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 3,
    "completion_tokens": 5,
    "reasoning_tokens": 4,
    "total_tokens": 12
  }
}

Response:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699123456,
  "model": "quack-model",
  "choices": [{
    "message": {
      "content": "Quack!",
      "role": "assistant"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 4,
    "completion_tokens": 1,
    "total_tokens": 5
  }
}

Legacy Completions

POST /v1/completions

Backwards compatible with older OpenAI API format.

Request:

{
  "model": "quack-model",
  "prompt": "Your message here",
  "reasoning_effort": "high",  // Optional: "low", "medium", "high"
  "quack_thinking": true       // Optional: Enable duck-themed thinking messages
}

Authentication:

Authorization: Bearer sk-v1-42your-api-key-here

Health Check

GET /health

Returns API health status.

Models List

GET /v1/models

Lists available models (currently just "quack-model").

Deployment

GitHub Pages (Frontend Only)

1. 1.Enable GitHub Pages:
2. 2.Go to repository Settings > Pages
3. 3.Set source to "Deploy from a branch"
4. 4.Select "main" branch and "/frontend" folder

1. 1.Access the demo:
2. 2.Frontend: https://bearjcc.github.io/QLM/
3. 3.Note: GitHub Pages doesn't support server-side APIs

Production Server

For full API functionality, deploy to a server with Python support:

# Using gunicorn
pip install gunicorn
gunicorn api.main:app -w 4 -k uvicorn.workers.UvicornWorker

Or use Docker:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY api/ ./api/
EXPOSE 8000
CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "8000"]

Configuration

Environment variables:

• —PORT: Server port (default: 8000)
• —No authentication required (intentionally public)

Testing

Run the included tests:

# Install test dependencies
pip install pytest

# Run tests
pytest tests/

Contributing

1. 1.Fork the repository
2. 2.Create a feature branch
3. 3.Make your changes
4. 4.Add tests if applicable
5. 5.Submit a pull request

License

MIT License - feel free to use in your projects!

Why QLM?

State-of-the-art ADI Technology: While competitors focus on billions of parameters, we've mastered the most important one: quack.

Unparalleled Accuracy: 100% of our responses are duck sounds. Other models can only dream of such consistency.

Ethical AI: Our ducks never hallucinate. They're just ducks.

Energy Efficient: Trained on a single pond. Carbon footprint: one bread crumb.

Acknowledgments

• —Inspired by rubber duck debugging methodology
• —Powered by ADI (Artificial Duck Intelligence)
• —Built with FastAPI for maximum quackability
• —Hosted on Hugging Face Spaces

Made with 🦆 and ADI by BearJCC

"Rubber Duckie, you're the one..." — Inspired by Ernie's timeless wisdom