> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common pitfalls

> Avoid common QWED integration mistakes like calling LLM directly instead of through QWED. Includes correct and incorrect code examples for reference.

## ❌ Pitfall #1: calling the LLM directly

### The mistake

```python theme={null}
# ❌ WRONG!
import openai
from qwed import QWEDClient

# User calls LLM themselves
response = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "What is 2+2?"}]
)

# Then tries to verify
qwed = QWEDClient(api_key="...")
result = qwed.verify(response.content)  # TOO LATE!
```

### Why it's wrong

* 🚫 QWED can't control LLM prompting
* 🚫 No DSL enforcement
* 🚫 Vulnerable to prompt injection
* 🚫 Can't guarantee structured output

### The fix

```python theme={null}
# ✅ CORRECT!
from qwed import QWEDClient

qwed = QWEDClient(api_key="...")

# Just call QWED directly
result = qwed.verify("What is 2+2?")
print(result.verified)  # True
```

**Rule:** Let QWED handle the LLM internally.

***

## ❌ Pitfall #2: trusting LLM output without verification

### The mistake

```python theme={null}
# ❌ DANGEROUS!
llm_calculation = llm.generate("Calculate loan payment for $50k at 5%")

# Use directly without verification
charge_customer(llm_calculation)  # LAWSUIT WAITING TO HAPPEN!
```

### Why it's wrong

* LLMs make mistakes (12% error rate in benchmarks)
* Financial errors = legal liability
* No audit trail

### The fix

```python theme={null}
# ✅ SAFE!
result = qwed.verify("Calculate loan payment for $50k at 5%")

if result.verified:
    charge_customer(result.value)
    log_verification(result.evidence)  # Audit trail
else:
    alert_human_review(result.reason)
```

***

## ❌ Pitfall #3: wrong verification method

### The mistake

```python theme={null}
# ❌ WRONG METHOD!
code_to_verify = """
def login(username, password):
    query = f"SELECT * FROM users WHERE name='{username}'"
"""

# Using general verify() instead of verify_code()
result = qwed.verify(code_to_verify)  # Won't detect SQL injection!
```

### Why it's wrong

* Different engines for different domains
* `verify()` won't analyze code security
* Misses vulnerabilities

### The fix

```python theme={null}
# ✅ USE CORRECT METHOD!
result = qwed.verify_code(code_to_verify, language="python")

if result.blocked:
    print(f"Security issue: {result.vulnerabilities}")
```

**Available methods:**

* `verify()` - General (auto-detects domain)
* `verify_math()` - Mathematical expressions
* `verify_logic()` - Logical statements
* `verify_code()` - Code security
* `verify_sql()` - SQL injection
* `verify_fact()` - Fact checking

***

## ❌ Pitfall #4: ignoring verification results

### The mistake

```python theme={null}
# ❌ IGNORING ERRORS!
result = qwed.verify("Calculate 15% of 200")

# Using result without checking verification status
value = result.value  # Might be wrong!
process_payment(value)
```

### Why it's wrong

* Verification might have failed
* Using unverified data
* No error handling

### The fix

```python theme={null}
# ✅ ALWAYS CHECK VERIFICATION STATUS!
result = qwed.verify("Calculate 15% of 200")

if result.verified:
    # Safe to use
    process_payment(result.value)
else:
    # Handle failure
    logger.error(f"Verification failed: {result.reason}")
    notify_admin(result.trace)
    use_fallback_method()
```

***

## ❌ Pitfall #5: not handling errors

### The mistake

```python theme={null}
# ❌ NO ERROR HANDLING!
result = qwed.verify("malformed input!!!@#$")
# Might crash or return unexpected result
```

### Why it's wrong

* Network failures happen
* API quotas exist
* Invalid input exists

### The fix

```python theme={null}
# ✅ PROPER ERROR HANDLING!
from qwed.exceptions import (
    AuthenticationError,
    ValidationError,
    TimeoutError,
    QuotaExceededError
)

try:
    result = qwed.verify("your query")
    
    if result.verified:
        use_result(result.value)
    else:
        handle_failed_verification(result.reason)
        
except AuthenticationError:
    logger.error("Invalid API key")
    notify_admin("QWED authentication failed")
    
except QuotaExceededError:
    logger.warning("QWED quota exceeded")
    use_fallback_method()
    
except TimeoutError:
    logger.warning("QWED timeout")
    retry_with_backoff()
    
except ValidationError as e:
    logger.error(f"Invalid input: {e}")
    sanitize_and_retry()
```

***

## ❌ Pitfall #6: missing API key configuration

### The mistake

```python theme={null}
# ❌ HARDCODED API KEY!
client = QWEDClient(api_key="qwed_1234567890abcdef")  # Committed to Git!
```

### Why it's wrong

* Security risk (API key exposed)
* Can't change keys without code changes
* Different keys for dev/prod

### The fix

```python theme={null}
# ✅ ENVIRONMENT VARIABLE!
import os
from qwed import QWEDClient

api_key = os.getenv("QWED_API_KEY")
if not api_key:
    raise ValueError("QWED_API_KEY environment variable not set")

client = QWEDClient(api_key=api_key)
```

**Or use config file:**

```python theme={null}
# config.py
from dotenv import load_dotenv
import os

load_dotenv()  # Load from .env file

QWED_API_KEY = os.getenv("QWED_API_KEY")
```

***

## ❌ Pitfall #7: not using batch processing

### The mistake

```python theme={null}
# ❌ SLOW! (N individual API calls)
results = []
for query in queries:  # 100 queries
    result = qwed.verify(query)  # 100 API calls!
    results.append(result)
```

### Why it's wrong

* Slow (sequential API calls)
* Expensive (more API credits)
* Poor user experience

### The fix

```python theme={null}
# ✅ FAST! (1 batch API call)
from qwed import BatchItem

items = [
    BatchItem(query=q, type="math") 
    for q in queries
]

result = qwed.verify_batch(items)  # Single API call!

for item_result in result.items:
    if item_result.verified:
        process(item_result.value)
```

**Performance comparison:**

* Individual: 100 queries × 2s = 200s
* Batch: 1 request × 5s = 5s
* **40x faster!**

***

## ❌ Pitfall #8: wrong timeout settings

### The mistake

```python theme={null}
# ❌ TOO SHORT!
client = QWEDClient(api_key="...", timeout=1)  # 1 second!

result = client.verify("complex calculation")  # Likely to timeout
```

### Why it's wrong

* Complex queries need time
* Causes unnecessary failures
* Poor user experience

### The fix

```python theme={null}
# ✅ REASONABLE TIMEOUT!
client = QWEDClient(
    api_key="...",
    timeout=30  # 30 seconds (default)
)

# Or per-request timeout
result = client.verify(
    "complex query",
    timeout=60  # Override for this request
)
```

**Recommended timeouts:**

* Simple queries: 10-15s
* Complex queries: 30-60s
* Batch processing: 60-120s

***

## ❌ Pitfall #9: not running the backend server

### The mistake

```python theme={null}
# ❌ WRONG - SDK without backend!
from qwed import QWEDClient

# Trying to use SDK directly
client = QWEDClient(api_key="qwed_123")
result = client.verify("2+2=4")  # Connection refused!
```

### Why it's wrong

* QWED requires a backend server
* SDK is just a client that connects to backend
* Backend needs YOUR LLM API keys

### The fix

```bash theme={null}
# ✅ Terminal 1: Run backend first
cd qwed-verification
cp .env.example .env
# Add your LLM API key to .env
python -m qwed_api

# ✅ Terminal 2: Then use SDK
python your_app.py
```

**Correct SDK usage:**

```python theme={null}
from qwed import QWEDClient

# Connect to local backend
client = QWEDClient(
    api_key="qwed_local",
    base_url="http://localhost:8000"  # Your running backend!
)

result = client.verify("2+2=4")
```

**Architecture:**

```text theme={null}
Your App → SDK → Backend Server (YOU run) → LLM (YOUR key) → Verifiers
```

**See:** [Getting started](./getting-started) for full backend setup

***

## ✅ Integration checklist

Before deploying to production, verify:

* **Backend server is running** with your LLM API key configured
* Not calling LLM directly (QWED handles it)
* Using correct verification methods for each domain
* Checking `result.verified` before using output
* Proper error handling (try/except blocks)
* API key in environment variable (not hardcoded)
* Using batch processing for multiple queries
* Reasonable timeout settings
* Logging verification results for audit trails
* Testing integration (see [Testing guide](./testing))
* Monitoring QWED in production (see [Monitoring](./monitoring))

***

## Need help?

Still stuck? We're here to help:

* 📖 [Testing guide](./testing) - Validate your integration
* 💬 [Community support](https://github.com/QWED-AI/qwed-verification/discussions)
* 📧 Enterprise Support: [support@qwedai.com](mailto:support@qwedai.com)