Chat

await client.sources.ask({
  question: string,                                          // Required
  conversation_id?: string | null,
  reset?: boolean | null,
  file_ids?: string[] | null,
  file_names?: string[] | null,                              // Deprecated
  output_schema?: Record<string, unknown> | null,
  thinking_level?: 'fast' | 'balanced' | 'accurate' | null,
  include_citation_images?: boolean | null,
  include_citation_markup?: boolean | null,
}): Promise<SourceAskResponse>

import Graphor from 'graphor';

const client = new Graphor();

// Ask a simple question
const response = await client.sources.ask({
  question: 'What are the main findings in this report?',
});

console.log(`Answer: ${response.answer}`);
console.log(`Conversation ID: ${response.conversation_id}`);

import Graphor from 'graphor';

const client = new Graphor();

// First question
const response = await client.sources.ask({
  question: 'What products are mentioned in the catalog?',
});

console.log(`Answer: ${response.answer}`);

// Follow-up question using conversation memory
const followUp = await client.sources.ask({
  question: 'Which one is the most expensive?',
  conversation_id: response.conversation_id,
});

console.log(`Follow-up: ${followUp.answer}`);

// Another follow-up
const another = await client.sources.ask({
  question: 'What are its specifications?',
  conversation_id: response.conversation_id,
});

console.log(`Answer: ${another.answer}`);

import Graphor from 'graphor';

const client = new Graphor();

// Start a conversation
const response = await client.sources.ask({
  question: "What is the company's revenue?",
});

// Switch to a new topic - reset the conversation
const newResponse = await client.sources.ask({
  question: 'What are the safety guidelines?',
  conversation_id: response.conversation_id,
  reset: true, // Ignores previous conversation history
});

console.log(`Answer: ${newResponse.answer}`);

import Graphor from 'graphor';

const client = new Graphor();

// Ask about specific documents using file_ids (preferred)
const response = await client.sources.ask({
  question: 'What is the total amount due?',
  file_ids: ['file_abc123', 'file_def456'],
});

console.log(`Answer: ${response.answer}`);

// Or using file_names (deprecated)
const response2 = await client.sources.ask({
  question: 'What is the total amount due?',
  file_names: ['invoice-2024.pdf', 'invoice-2023.pdf'],
});

console.log(`Answer: ${response2.answer}`);

import Graphor from 'graphor';

const client = new Graphor();

// Default: lazy-load screenshots when needed
const response = await client.sources.ask({
  question: 'What was the revenue in 2025?',
  file_ids: ['file_abc123'],
});

console.log(response.answer);
// -> "Revenue grew 23% year-over-year, reaching $4.2B [1]…"

for (const c of response.citations ?? []) {
  console.log(`[${c.index}] ${c.file_name} p${c.page_number}`);
  // When the user hovers/clicks on [N], fetch the page screenshot
  const screenshot = await client.sources.getPageScreenshot(
    c.page_number!,
    { file_id: c.file_id!, max_width: 900 },
  );
  // screenshot.image_base64 is a ready-to-render PNG
}

const response = await client.sources.ask({
  question: 'Confirm the invoice number and due date.',
  file_ids: ['invoice_abc123'],
  include_citation_images: true, // base64 PNG embedded per citation
});

for (const c of response.citations ?? []) {
  if (c.image_base64) {
    const bytes = Buffer.from(c.image_base64, 'base64');
    await fs.promises.writeFile(`page_${c.page_number}.png`, bytes);
  }
}

import Graphor from 'graphor';

const client = new Graphor();

// Fast mode for simple questions
const response = await client.sources.ask({
  question: 'What is the document title?',
  thinking_level: 'fast',
});

console.log(`Answer: ${response.answer}`);

// Accurate mode for complex analysis
const analysis = await client.sources.ask({
  question: 'Analyze the legal implications of the termination clause and identify potential risks.',
  file_names: ['contract.pdf'],
  thinking_level: 'accurate',
});

console.log(`Analysis: ${analysis.answer}`);

import Graphor from 'graphor';

const client = new Graphor();

// Define the output schema
const invoiceSchema = {
  type: 'object',
  properties: {
    invoice_number: { type: ['string', 'null'] },
    total_amount_due: { type: ['number', 'null'] },
    currency: { type: ['string', 'null'] },
    due_date: { type: ['string', 'null'] },
  },
};

// Ask with structured output
const response = await client.sources.ask({
  question: 'Extract the invoice number, total amount, currency, and due date.',
  file_names: ['invoice-2024.pdf'],
  output_schema: invoiceSchema,
});

// Access the structured data
if (response.structured_output) {
  const data = response.structured_output as Record<string, unknown>;
  console.log(`Invoice: ${data.invoice_number}`);
  console.log(`Amount: ${data.total_amount_due} ${data.currency}`);
  console.log(`Due: ${data.due_date}`);
}

// Raw JSON is also available
console.log(`Raw JSON: ${response.raw_json}`);

import Graphor from 'graphor';

const client = new Graphor();

// Schema for extracting a list of products
const productsSchema = {
  type: 'array',
  items: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      price: { type: ['number', 'null'] },
      quantity: { type: ['integer', 'null'] },
    },
  },
};

const response = await client.sources.ask({
  question: 'Extract all products with their prices and quantities from the order.',
  file_names: ['order.pdf'],
  output_schema: productsSchema,
});

if (response.structured_output) {
  const products = response.structured_output as Array<Record<string, unknown>>;
  for (const product of products) {
    console.log(`- ${product.name}: $${product.price ?? 'N/A'} x ${product.quantity ?? 'N/A'}`);
  }
}

import Graphor from 'graphor';

const client = new Graphor();

async function askQuestions() {
  // Ask a question
  const response = await client.sources.ask({
    question: 'What are the key terms in this contract?',
  });

  console.log(`Answer: ${response.answer}`);

  // Follow-up
  const followUp = await client.sources.ask({
    question: 'When does it expire?',
    conversation_id: response.conversation_id,
  });

  console.log(`Follow-up: ${followUp.answer}`);
}

await askQuestions();

import Graphor from 'graphor';

const client = new Graphor();

try {
  const response = await client.sources.ask({
    question: 'What is the summary of this document?',
  });
  console.log(`Answer: ${response.answer}`);
} catch (err) {
  if (err instanceof Graphor.BadRequestError) {
    console.log(`Invalid request: ${err.message}`);
  } else if (err instanceof Graphor.AuthenticationError) {
    console.log(`Invalid API key: ${err.message}`);
  } else if (err instanceof Graphor.NotFoundError) {
    console.log(`Document not found: ${err.message}`);
  } else if (err instanceof Graphor.UnprocessableEntityError) {
    console.log(`Invalid output_schema or validation failed: ${err.message}`);
  } else if (err instanceof Graphor.RateLimitError) {
    console.log(`Rate limit exceeded: ${err.message}`);
  } else if (err instanceof Graphor.APIConnectionError) {
    console.log(`Connection error: ${err.message}`);
  } else if (err instanceof Graphor.APIError) {
    console.log(`API error (status ${err.status}): ${err.message}`);
  } else {
    throw err;
  }
}

import Graphor from 'graphor';

interface ChatEntry {
  question: string;
  answer: string;
}

class DocumentChatbot {
  private client: Graphor;
  private conversationId: string | null = null;
  private history: ChatEntry[] = [];

  constructor(apiKey?: string) {
    this.client = apiKey ? new Graphor({ apiKey }) : new Graphor();
  }

  async ask(question: string, fileNames?: string[]): Promise<string> {
    try {
      const response = await this.client.sources.ask({
        question,
        conversation_id: this.conversationId ?? undefined,
        file_names: fileNames,
      });

      // Update conversation ID
      this.conversationId = response.conversation_id ?? null;

      // Store in history
      this.history.push({ question, answer: response.answer });

      return response.answer;
    } catch (err) {
      if (err instanceof Graphor.APIError) {
        return `Error: ${err.message}`;
      }
      throw err;
    }
  }

  reset(): void {
    this.conversationId = null;
    this.history = [];
  }

  getHistory(): ChatEntry[] {
    return [...this.history];
  }
}

// Usage
const chatbot = new DocumentChatbot();

// Have a conversation
console.log(await chatbot.ask('What products are available?'));
console.log(await chatbot.ask('Tell me more about the first one'));
console.log(await chatbot.ask("What's its price?"));

// View history
for (const entry of chatbot.getHistory()) {
  console.log(`Q: ${entry.question}`);
  console.log(`A: ${entry.answer.slice(0, 100)}...`);
  console.log();
}

// Reset for a new topic
chatbot.reset();
console.log(await chatbot.ask('What are the shipping options?'));

import Graphor from 'graphor';

const client = new Graphor();

async function compareDocuments(fileNames: string[], question: string): Promise<string> {
  const response = await client.sources.ask({
    question,
    file_names: fileNames,
  });
  return response.answer;
}

// Compare financial reports
const answer = await compareDocuments(
  ['report-2023.pdf', 'report-2024.pdf'],
  'How did revenue change between 2023 and 2024?',
);
console.log(answer);

import Graphor from 'graphor';

const client = new Graphor();

interface ExtractionResult {
  file: string;
  data: Record<string, unknown> | null;
  success: boolean;
  error?: string;
}

async function extractStructuredData(
  fileNames: string[],
  question: string,
  schema: Record<string, unknown>,
): Promise<ExtractionResult[]> {
  const results: ExtractionResult[] = [];

  for (const fileName of fileNames) {
    try {
      const response = await client.sources.ask({
        question,
        file_names: [fileName],
        output_schema: schema,
      });

      if (response.structured_output) {
        results.push({
          file: fileName,
          data: response.structured_output as Record<string, unknown>,
          success: true,
        });
      } else {
        results.push({
          file: fileName,
          data: null,
          success: false,
          error: 'No structured output returned',
        });
      }
    } catch (err) {
      results.push({
        file: fileName,
        data: null,
        success: false,
        error: err instanceof Graphor.APIError ? err.message : String(err),
      });
    }
  }

  return results;
}

// Extract invoice data from multiple invoices
const invoiceSchema = {
  type: 'object',
  properties: {
    invoice_number: { type: ['string', 'null'] },
    vendor: { type: ['string', 'null'] },
    total: { type: ['number', 'null'] },
    date: { type: ['string', 'null'] },
  },
};

const invoices = ['invoice1.pdf', 'invoice2.pdf', 'invoice3.pdf'];
const results = await extractStructuredData(
  invoices,
  'Extract the invoice number, vendor name, total amount, and date.',
  invoiceSchema,
);

for (const result of results) {
  if (result.success && result.data) {
    console.log(`OK - ${result.file}: #${result.data.invoice_number} - $${result.data.total}`);
  } else {
    console.log(`FAIL - ${result.file}: ${result.error}`);
  }
}

import Graphor from 'graphor';

const client = new Graphor();

async function askParallelQuestions(questions: string[]) {
  const promises = questions.map((question) =>
    client.sources
      .ask({ question })
      .then((response) => ({ question, answer: response.answer }))
      .catch((err) => ({
        question,
        error: err instanceof Graphor.APIError ? err.message : String(err),
      })),
  );

  return Promise.all(promises);
}

// Usage
const questions = [
  'What is the total revenue?',
  'Who are the main competitors?',
  'What are the key risks?',
];

const results = await askParallelQuestions(questions);

for (const result of results) {
  console.log(`Q: ${result.question}`);
  if ('answer' in result) {
    console.log(`A: ${result.answer.slice(0, 200)}...`);
  } else {
    console.log(`Error: ${result.error}`);
  }
  console.log();
}

import Graphor from 'graphor';
import readline from 'readline';

async function interactiveQA() {
  const client = new Graphor();
  let conversationId: string | null = null;

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  });

  const prompt = (query: string): Promise<string> =>
    new Promise((resolve) => rl.question(query, resolve));

  console.log('Document Q&A Session');
  console.log("Type 'quit' to exit, 'reset' to start a new conversation");
  console.log('-'.repeat(50));

  while (true) {
    const question = (await prompt('\nYou: ')).trim();

    if (question.toLowerCase() === 'quit') {
      console.log('Goodbye!');
      rl.close();
      break;
    }

    if (question.toLowerCase() === 'reset') {
      conversationId = null;
      console.log('Conversation reset.');
      continue;
    }

    if (!question) continue;

    try {
      const response = await client.sources.ask({
        question,
        conversation_id: conversationId ?? undefined,
      });

      conversationId = response.conversation_id ?? null;
      console.log(`\nAssistant: ${response.answer}`);
    } catch (err) {
      if (err instanceof Graphor.APIError) {
        console.log(`\nError: ${err.message}`);
      } else {
        throw err;
      }
    }
  }
}

// Run interactive session
// await interactiveQA();

// Simple object
const personSchema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: ['integer', 'null'] },
    email: { type: ['string', 'null'] },
  },
};

// Array of objects
const itemsSchema = {
  type: 'array',
  items: {
    type: 'object',
    properties: {
      item: { type: 'string' },
      quantity: { type: 'integer' },
      price: { type: 'number' },
    },
  },
};

// Nested objects
const orderSchema = {
  type: 'object',
  properties: {
    order_id: { type: 'string' },
    customer: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        address: { type: ['string', 'null'] },
      },
    },
    total: { type: 'number' },
  },
};

// Good: Specific question with context
const response = await client.sources.ask({
  question: 'What was the total revenue for Q4 2024 compared to Q4 2023?',
  file_names: ['annual-report-2024.pdf'],
});

// Good: Follow-up with conversation memory
const followUp = await client.sources.ask({
  question: 'What were the main drivers of this change?',
  conversation_id: response.conversation_id,
});