OWAQA 1.0 Documentation

# OWAQA - Open Web AI Query Architecture

## Site Information
- Name: Your Business Name
- Description: Brief description of what you offer
- Purpose: Help AI systems understand and query your products/services

## API Endpoints
- Base URL: https://yourdomain.com/api
- Query: POST /api/query
- Products: GET /api/products
- Product Details: GET /api/products/{id}

## Query Format
POST /api/query
{
  "query": "user's natural language question",
  "context": {
    "intent": "discovery|comparison|decision",
    "audience": "optional audience segment"
  }
}

## Response Format
{
  "product_id": "unique-identifier",
  "name": "Product Name",
  "description": "Detailed description",
  "features": ["feature1", "feature2"],
  "metadata": {
    "audience": "target audience",
    "use_case": "primary use case",
    "price_range": "pricing tier"
  },
  "confidence": 0.95
}

## Authentication
- Type: none (public API)
- Rate Limits: 100 requests/minute per IP

## Additional Resources
- Documentation: https://yourdomain.com/docs
- Status: https://yourdomain.com/status
- Contact: api@yourdomain.com

from flask import Flask, request, jsonify
from flask_cors import CORS
import pinecone
from openai import OpenAI

app = Flask(__name__)
CORS(app)

# Initialize vector database
pinecone.init(api_key="your-key", environment="us-west1-gcp")
index = pinecone.Index("products")

# Initialize OpenAI for embeddings
client = OpenAI(api_key="your-key")

@app.route('/api/query', methods=['POST'])
def query():
    """Semantic search endpoint"""
    data = request.json
    query_text = data.get('query')
    context = data.get('context', {})
    
    # Generate embedding for query
    response = client.embeddings.create(
        input=query_text,
        model="text-embedding-3-small"
    )
    query_embedding = response.data[0].embedding
    
    # Search vector database
    results = index.query(
        vector=query_embedding,
        top_k=1,
        include_metadata=True,
        filter={
            "audience": context.get('audience')
        } if context.get('audience') else None
    )
    
    if results['matches']:
        match = results['matches'][0]
        return jsonify({
            'product_id': match['metadata']['product_id'],
            'variation_id': match['id'],
            'name': match['metadata']['name'],
            'description': match['metadata']['description'],
            'features': match['metadata']['features'],
            'metadata': {
                'audience': match['metadata']['audience'],
                'intent': match['metadata']['intent']
            },
            'confidence': match['score']
        })
    
    return jsonify({'error': 'No matching product found'}), 404

@app.route('/api/products', methods=['GET'])
def list_products():
    """List all products with optional filtering"""
    audience = request.args.get('audience')
    intent = request.args.get('intent')
    limit = int(request.args.get('limit', 50))
    
    # Query your product database
    # This is pseudo-code - adapt to your DB
    products = db.products.find({
        'audience': audience,
        'intent': intent
    } if audience or intent else {}).limit(limit)
    
    return jsonify({
        'products': [format_product(p) for p in products],
        'total': products.count(),
        'limit': limit
    })

@app.route('/api/products/<product_id>', methods=['GET'])
def get_product(product_id):
    """Get specific product details"""
    variation = request.args.get('variation')
    
    # Query your database
    if variation:
        product = db.variations.find_one({
            'product_id': product_id,
            'variation_id': variation
        })
    else:
        product = db.products.find_one({'product_id': product_id})
    
    if product:
        return jsonify(format_product(product))
    
    return jsonify({'error': 'Product not found'}), 404

if __name__ == '__main__':
    app.run(debug=True)

const express = require('express');
const cors = require('cors');
const { PineconeClient } = require('@pinecone-database/pinecone');
const { OpenAI } = require('openai');

const app = express();
app.use(cors());
app.use(express.json());

// Initialize services
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const pinecone = new PineconeClient();
await pinecone.init({
  apiKey: process.env.PINECONE_API_KEY,
  environment: 'us-west1-gcp'
});
const index = pinecone.Index('products');

app.post('/api/query', async (req, res) => {
  try {
    const { query, context = {} } = req.body;
    
    // Generate embedding
    const embedding = await openai.embeddings.create({
      input: query,
      model: 'text-embedding-3-small'
    });
    
    // Search vector database
    const queryRequest = {
      vector: embedding.data[0].embedding,
      topK: 1,
      includeMetadata: true
    };
    
    if (context.audience) {
      queryRequest.filter = { audience: context.audience };
    }
    
    const results = await index.query(queryRequest);
    
    if (results.matches.length > 0) {
      const match = results.matches[0];
      return res.json({
        product_id: match.metadata.product_id,
        variation_id: match.id,
        name: match.metadata.name,
        description: match.metadata.description,
        features: match.metadata.features,
        metadata: {
          audience: match.metadata.audience,
          intent: match.metadata.intent
        },
        confidence: match.score
      });
    }
    
    res.status(404).json({ error: 'No matching product found' });
  } catch (error) {
    console.error(error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.get('/api/products', async (req, res) => {
  const { audience, intent, limit = 50 } = req.query;
  
  // Query your database
  const filter = {};
  if (audience) filter.audience = audience;
  if (intent) filter.intent = intent;
  
  const products = await db.collection('products')
    .find(filter)
    .limit(parseInt(limit))
    .toArray();
  
  res.json({
    products: products.map(formatProduct),
    total: products.length,
    limit: parseInt(limit)
  });
});

app.get('/api/products/:id', async (req, res) => {
  const { id } = req.params;
  const { variation } = req.query;
  
  const query = { product_id: id };
  if (variation) query.variation_id = variation;
  
  const product = await db.collection('products').findOne(query);
  
  if (product) {
    return res.json(formatProduct(product));
  }
  
  res.status(404).json({ error: 'Product not found' });
});

const PORT = process.env.PORT || 5000;
app.listen(PORT, () => {
  console.log(`OWAQA API running on port ${PORT}`);
});

// Shopify App Proxy endpoint
// Route: /apps/owaqa/api/query

app.post('/apps/owaqa/api/query', async (req, res) => {
  const shop = req.query.shop;
  const { query, context } = req.body;
  
  // Get Shopify products
  const shopify = new Shopify({
    shopName: shop,
    accessToken: await getAccessToken(shop)
  });
  
  // Search products using Shopify's built-in search
  const products = await shopify.product.search({
    query: query,
    limit: 10
  });
  
  // Get product variations from metafields
  const enrichedProducts = await Promise.all(
    products.map(async (product) => {
      const metafields = await shopify.metafield.list({
        metafield: { owner_resource: 'product', owner_id: product.id }
      });
      
      // Find variation matching context
      const variations = metafields.find(m => 
        m.namespace === 'owaqa' && m.key === 'variations'
      );
      
      if (variations) {
        const variationData = JSON.parse(variations.value);
        const match = variationData.find(v => 
          v.audience === context.audience
        );
        
        if (match) {
          return {
            product_id: product.id,
            variation_id: match.id,
            name: product.title,
            description: match.description,
            features: match.features,
            metadata: match.metadata
          };
        }
      }
      
      // Fallback to default description
      return {
        product_id: product.id,
        name: product.title,
        description: product.body_html
      };
    })
  );
  
  res.json(enrichedProducts[0] || { error: 'No match' });
});

# Python/Flask: Add query logging to your endpoint

import json
from datetime import datetime

@app.route('/api/query', methods=['POST'])
def query():
    data = request.json
    query_text = data.get('query')
    context = data.get('context', {})
    
    # Generate embedding and search (your existing code)
    # ...
    result = search_vector_db(query_text, context)
    
    # LOG THE QUERY DATA
    query_log = {
        'timestamp': datetime.utcnow().isoformat(),
        'query': query_text,
        'context': context,
        'result': {
            'product_id': result['product_id'],
            'variation_id': result['variation_id'],
            'confidence': result['confidence']
        },
        'ip': request.remote_addr,
        'user_agent': request.headers.get('User-Agent')
    }
    
    # Store in database
    db.query_logs.insert_one(query_log)
    
    # Also send to analytics pipeline (optional)
    send_to_analytics(query_log)
    
    return jsonify(result)

# Store query logs in a separate collection/table
# Schema: queries
# - timestamp (datetime)
# - query (text) - indexed for search
# - context (json)
# - result_product_id (string) - indexed
# - result_variation_id (string) - indexed
# - confidence (float)
# - ip (string)
# - user_agent (string)

# Python: Generate business intelligence reports

from collections import Counter
import pandas as pd

def analyze_query_trends(days=30):
    """Analyze query patterns over the last N days"""
    
    # Get recent queries
    queries = db.query_logs.find({
        'timestamp': {'$gte': datetime.utcnow() - timedelta(days=days)}
    })
    
    df = pd.DataFrame(list(queries))
    
    # Top 20 most common query patterns
    query_patterns = df['query'].str.lower().value_counts().head(20)
    
    # Audience distribution
    audience_dist = df['context'].apply(lambda x: x.get('audience', 'unknown')).value_counts()
    
    # Intent distribution
    intent_dist = df['context'].apply(lambda x: x.get('intent', 'unknown')).value_counts()
    
    # Average confidence by product
    confidence_by_product = df.groupby('result.product_id')['result.confidence'].mean()
    
    # Queries with low confidence (potential gaps)
    low_confidence = df[df['result.confidence'] < 0.7]
    product_gaps = low_confidence['query'].tolist()
    
    # Daily query volume trend
    df['date'] = pd.to_datetime(df['timestamp']).dt.date
    daily_volume = df.groupby('date').size()
    
    return {
        'total_queries': len(df),
        'unique_queries': df['query'].nunique(),
        'top_patterns': query_patterns.to_dict(),
        'audience_breakdown': audience_dist.to_dict(),
        'intent_breakdown': intent_dist.to_dict(),
        'product_confidence': confidence_by_product.to_dict(),
        'potential_gaps': product_gaps[:10],  # Top 10 unmet needs
        'daily_trend': daily_volume.to_dict()
    }

# Use this for weekly reports
@app.route('/api/analytics/summary')
def analytics_summary():
    """Provide business intelligence summary"""
    data = analyze_query_trends(days=7)
    return jsonify(data)

# Export query-response pairs for LLM training datasets

def export_training_data(output_file='owaqa_training_data.jsonl'):
    """
    Export query logs as training data for future LLMs.
    Format: JSONL (JSON Lines) - one query-response pair per line
    """
    
    queries = db.query_logs.find({
        'result.confidence': {'$gte': 0.8}  # Only high-confidence matches
    })
    
    with open(output_file, 'w') as f:
        for query in queries:
            # Get full product details
            product = db.products.find_one({
                'product_id': query['result']['product_id'],
                'variation_id': query['result']['variation_id']
            })
            
            training_example = {
                'query': query['query'],
                'context': query['context'],
                'response': {
                    'product': product['name'],
                    'description': product['description'],
                    'features': product['features'],
                    'explanation': f"This product matches because: {product['metadata']['reasoning']}"
                },
                'confidence': query['result']['confidence'],
                'timestamp': query['timestamp']
            }
            
            f.write(json.dumps(training_example) + '\\n')
    
    print(f"Exported {queries.count()} training examples to {output_file}")

# This creates a dataset that can be used to:
# 1. Fine-tune your own models
# 2. Share with LLM providers as high-quality training data
# 3. Contribute to open-source AI training datasets
# 4. Validate and improve your product variations