LLM Integration
Field Manual

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE chunks (
  id        bigserial PRIMARY KEY,
  doc_id    text,
  content   text,
  metadata  jsonb,
  embedding vector(1024)        -- must match your model
);
-- Approximate-NN index: HNSW (fast, accurate) for cosine
CREATE INDEX ON chunks USING hnsw (embedding vector_cosine_ops);

import psycopg, numpy as np
from openai import OpenAI
client = OpenAI()
EMB = "text-embedding-3-large"; CHAT = "gpt-5.5"

# 1. CHUNK — recursive-ish: paragraphs, then pack to a token budget w/ overlap
def chunk(text, size=800, overlap=120):
    words = text.split()
    step = size - overlap
    return [" ".join(words[i:i+size]) for i in range(0, len(words), step)]

# 2. EMBED (batch the calls in real code)
def embed(texts):
    r = client.embeddings.create(model=EMB, input=texts)
    return [d.embedding for d in r.data]

# 3. INGEST → pgvector
def ingest(conn, doc_id, text):
    parts = chunk(text)
    for c, v in zip(parts, embed(parts)):
        conn.execute("INSERT INTO chunks(doc_id,content,embedding) VALUES (%s,%s,%s)",
                     (doc_id, c, v))

# 4. RETRIEVE — ANN top-k by cosine distance
def retrieve(conn, query, k=5):
    qv = embed([query])[0]
    rows = conn.execute(
        "SELECT content FROM chunks ORDER BY embedding <=> %s LIMIT %s",
        (qv, k)).fetchall()
    return [r[0] for r in rows]

# 5. GROUND — stuff context, instruct the model to cite & abstain
def answer(conn, question):
    ctx = "\n\n---\n\n".join(retrieve(conn, question))
    sys = ("Answer ONLY from the context. "
           "If it's not there, say you don't know.")
    r = client.chat.completions.create(model=CHAT, messages=[
        {"role":"system","content":sys},
        {"role":"user","content":f"Context:\n{ctx}\n\nQ: {question}"}])
    return r.choices[0].message.content

tools = [{
  "name": "get_order_status",
  "description": "Look up an order's status by ID.",
  "input_schema": {"type":"object",
    "properties":{"order_id":{"type":"string"}},
    "required":["order_id"]}
}]

msg = client.messages.create(model="claude-sonnet-4-6", max_tokens=1024,
    tools=tools, messages=[{"role":"user","content":"Where's order A-91?"}])

if msg.stop_reason == "tool_use":
    call = next(b for b in msg.content if b.type=="tool_use")
    result = get_order_status(**call.input)   # YOU execute
    # …append tool_result and call again to get the final answer