elephant-gun 0.1.3

Elephant Gun 🐘🔫 - Hybrid SQL + semantic search CLI for Postgres (local-first)

Elephant Gun 🐘🔫

A local-first CLI for hybrid SQL + semantic search on PostgreSQL.

Elephant Gun lets you query your existing PostgreSQL tables with a mix of:

• Structured filters (SQL) — e.g., created_at < 30 days
• Semantic search (pgvector + embeddings) — e.g., “things that look like trouble”
• Natural language time parsing — e.g., “last week”, “since 2024-01-01”

No external APIs, no servers. Everything runs locally on your Postgres + Python.

---

✨ Features

• CLI commands for setup, embedding, and querying
• Schema scanning — Auto-discover tables and suggest text templates
• Natural language time parsing — Understands “last week”, “since 2024-01-01”, etc.
• pgvector integration (cosine similarity search)
• Sentence-transformers embeddings
• Hybrid search — Combines semantic similarity with lexical ranking
• Multi-table search — Query across all configured tables with RRF ranking
• Local-first — Your data never leaves your database

---

🚀 Quickstart (Recommended path)

🐍 1. Install (via PyPI)

Option A: pipx (recommended)

brew install pipx
pipx ensurepath
pipx install elephant-gun

Option B: Virtual environment

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install elephant-gun

⚠️ macOS (Homebrew Python): System Python is “externally managed” (PEP 668). Please use pipx or a virtual environment instead of pip install --user.

---

🐘 2. Start PostgreSQL with pgvector

The easiest way is using Docker:

docker run --name pg-vec -p 5433:5432 \
  -e POSTGRES_PASSWORD=postgres \
  -d pgvector/pgvector:pg14

export DATABASE_URL="postgresql://postgres:postgres@localhost:5433/postgres"

---

⚙️ 3. Create your sample table

psql "$DATABASE_URL" <<'SQL'
CREATE TABLE IF NOT EXISTS reviews (
  id BIGSERIAL PRIMARY KEY,
  created_at TIMESTAMPTZ DEFAULT now(),
  title TEXT,
  body  TEXT,
  deleted_at TIMESTAMPTZ
);
INSERT INTO reviews (title, body) VALUES
('Refund requested', 'Customer reports double charge and asks for refund'),
('Great service', 'Loved the dashboard and support response time'),
('Chargeback received', 'Bank notified chargeback due to fraud suspicion');
SQL

---

🧩 4. Create your config file

elephant_gun.yaml (place in your working directory):

embed_dim: 768
model: sentence-transformers/all-mpnet-base-v2

targets:
  - table: reviews
    key: id
    text_template: "title || ' ' || body"
    time_column: "created_at"
    filters:
      - "deleted_at IS NULL"

---

⚡ 5. Run commands

# Enable pgvector extension
elephant-gun ensure-ext

# Initialize embedding column + index
elephant-gun init

# Embed rows into vectors
elephant-gun embed --table reviews

# Query semantically (auto time parsing)
elephant-gun query --table reviews --q "refund issues last 30 days"

✅ Example output:

[1] sim01=0.747 lex=0.076  Refund requested Customer reports double charge and asks for refund
[3] sim01=0.651 lex=0.000  Chargeback received Bank notified chargeback due to fraud suspicion
[2] sim01=0.580 lex=0.000  Great service Loved the dashboard and support response time

---

🧠 CLI Commands

Main commands:

elephant-gun scan              # Scan DB schema and suggest text templates
elephant-gun ensure-ext        # CREATE EXTENSION vector
elephant-gun init              # Add embedding column + index
elephant-gun embed --table T   # Embed rows into vectors
elephant-gun query --table T --q "text" [options]

Query options:

--table T          # Target table (omit to search all tables)
--q "text"         # Natural language query (required)
--days N           # Manual time filter (optional - auto-parsing preferred)
--limit M          # Max results (default: 20)
--min-sim X        # Minimum similarity score (0.0–1.0)
--dry-run          # Show SQL without executing
--per-table-limit  # Results per table in multi-table mode (default: 50)

Automatic time parsing: Understands:

"last 7 days", "past 2 weeks", "last month",
"this week", "yesterday", "since 2024-01-01", "2024-01-01..2024-01-31"

Alias:

egun    # short alias for elephant-gun

---

🔍 Schema Scanning

Automatically discovers tables and suggests optimal text_template for embedding.

elephant-gun scan
# → writes profiles/current/schema.yaml

What it does:

• Finds text and time columns
• Suggests SQL expressions like title || ' ' || body
• Previews first few rows for inspection

---

🛠 Requirements

• Python 3.9+
• PostgreSQL 14+ with pgvector extension
• Docker (optional but easiest for setup)

---

🧪 Example Multi-table Query

Once multiple targets are defined in elephant_gun.yaml:

elephant-gun query --q "refund complaints this week" --limit 20

→ Automatically merges results from all tables using RRF ranking (semantic + lexical fusion).

---

🔬 Fine-tuning (Optional)

If you want to adapt Elephant Gun’s embeddings to your own domain:

1. Prepare training data

train/data/train.csv:

query	text	label
positive feedback	Great service, loved the dashboard	1
refund dispute	Customer claims double charge	0
fraud issues	Chargeback received due to fraud	1

2. Fine-tune locally

cd train
python train_st.py

→ Outputs train/models/eg-miniLM-finetuned/

3. Use fine-tuned model

Update your config:

model: train/models/eg-miniLM-finetuned
embed_dim: 384

Re-embed your data:

elephant-gun embed --table reviews

---

🧩 Troubleshooting

Symptom	Fix
FileNotFoundError: elephant_gun.yaml	Make sure the config file exists in the current directory
embedded 0	All rows already have embeddings (embedding IS NULL none left)
psycopg[binary] conflict on install	Use constraint workaround: printf "psycopg==3.2.10\npsycopg-binary==3.2.10\n" > /tmp/eg_constraints.txt PIP_CONSTRAINT=/tmp/eg_constraints.txt pipx install --python python3.12 elephant-gun
macOS says “externally managed environment”	Use pipx or venv instead of system pip

---

🔖 Uninstall

pipx uninstall elephant-gun
# or
pip uninstall elephant-gun

---

📦 Release Info

• PyPI: https://pypi.org/project/elephant-gun/
• Source: https://github.com/tomoharutsutsumi/elephant-gun
• License: MIT