Octagon

Appearance

Chat Completions API ​

IMPORTANT

Starting a new project? We recommend trying Responses to take advantage of the latest OpenAI SDK features. Compare Chat Completions with Responses.

The Chat Completions API provides a simple, OpenAI-compatible interface for interacting with Octagon's specialized agents. This guide explains how to use the API effectively.

Overview of the Chat Completions API ​

Chat Completions is a straightforward way to integrate with Octagon's financial agents using the familiar OpenAI-compatible format. It offers:

  1. Simple message-based format: Easy to implement with a standard chat interface
  2. OpenAI compatibility: Works with existing OpenAI client libraries
  3. Structured Citations: Provides source references in a consistent format
  4. Multi-turn conversations: Supports context from previous messages

Installation ​

Install the OpenAI SDK:

bash
pip install openai
bash
npm install openai

Request Parameters ​

ParameterTypeRequiredDescription
messagesarrayYesAn array of message objects representing the conversation so far.
modelstringYesThe ID of the agent model to use. See Available Agents.
streambooleanNoWhen set to true, enables event streaming of the response.

Each message object in the messages array should have the following structure:

FieldTypeDescription
rolestringThe role of the message sender. Can be "user" or "assistant".
contentstringThe content of the query or response.

Basic Usage Example ​

Python
from openai import OpenAI

client = OpenAI(
    # Note: Replace with your API key or use environment variables
    api_key="your-octagon-api-key",
    base_url="https://api-gateway.octagonagents.com/v1"
)

# Make the API call using the chat completions endpoint
response = client.chat.completions.create(
    model="octagon-sec-agent",
    messages=[
        {"role": "user", "content": "What were Apple's revenue numbers in Q3 2023?"}
    ]
)

message = response.choices[0].message

# Extract and print the analysis text
print("ANALYSIS:", message.content)

# Extract and print citations
print("\nSOURCES:")
for annotation in message.annotations:
    print(f"{annotation.order}. {annotation.name}: {annotation.url}")

# Example output:

# ANALYSIS:
# In the third quarter of 2023, Apple's total net sales were $81,797 million. This included $60,584 million from products and $21,213 million from services [1], [2].

# SOURCES:
# 1. Apple Inc. (10-Q) - 2023-Q3, Page: 10: https://octagon-sec-filings.s3.amazonaws.com/320193/0000320193-23-000077/aapl-20230701.pdf?response-content-disposition=inline&response-content-type=application%2Fpdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYGEZZN2EGRGVN56Y%2F20250401%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250401T220525Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=783c748f003e66bbdb61b2da4b49e3a31da0213617ff2237d1316da2885ca515#page=10
# 2. Apple Inc. (10-Q) - 2023-Q3, Page: 4: https://octagon-sec-filings.s3.amazonaws.com/320193/0000320193-23-000077/aapl-20230701.pdf?response-content-disposition=inline&response-content-type=application%2Fpdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYGEZZN2EGRGVN56Y%2F20250401%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250401T220525Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=783c748f003e66bbdb61b2da4b49e3a31da0213617ff2237d1316da2885ca515#page=4
JavaScript
import OpenAI from 'openai';

const openai = new OpenAI({
  // Note: Replace with your API key or use environment variables
  apiKey: 'your-octagon-api-key',
  baseURL: 'https://api-gateway.octagonagents.com/v1',
});

async function getAnalysis() {
  // Make the API call using the chat completions endpoint
  const response = await openai.chat.completions.create({
    model: 'octagon-sec-agent',
    messages: [
      { role: 'user', content: 'What were Apple's revenue numbers in Q3 2023?' }
    ]
  });

  const message = response.choices[0].message;

  // Extract and print the analysis text
  console.log("ANALYSIS:", message.content);

  // Extract and print citations
  console.log("\nSOURCES:");
  message.annotations.forEach(annotation => {
    console.log(`${annotation.order}. ${annotation.name}: ${annotation.url}`);
  });
}

getAnalysis();

// Example output:

// ANALYSIS:
// In the third quarter of 2023, Apple's total net sales were $81,797 million. This included $60,584 million from products and $21,213 million from services [1], [2].

// SOURCES:
// 1. Apple Inc. (10-Q) - 2023-Q3, Page: 10: https://octagon-sec-filings.s3.amazonaws.com/320193/0000320193-23-000077/aapl-20230701.pdf?response-content-disposition=inline&response-content-type=application%2Fpdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYGEZZN2EGRGVN56Y%2F20250401%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250401T220525Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=783c748f003e66bbdb61b2da4b49e3a31da0213617ff2237d1316da2885ca515#page=10
// 2. Apple Inc. (10-Q) - 2023-Q3, Page: 4: https://octagon-sec-filings.s3.amazonaws.com/320193/0000320193-23-000077/aapl-20230701.pdf?response-content-disposition=inline&response-content-type=application%2Fpdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYGEZZN2EGRGVN56Y%2F20250401%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250401T220525Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=783c748f003e66bbdb61b2da4b49e3a31da0213617ff2237d1316da2885ca515#page=4
cURL
curl -X POST https://api-gateway.octagonagents.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-octagon-api-key" \
  -d '{
    "model": "octagon-sec-agent",
    "messages": [
      {
        "role": "user",
        "content": "What were Apple'\''s revenue numbers in Q3 2023?"
      }
    ],
    "stream": true
  }' \
  --no-buffer

# Note: Handling the stream response with cURL requires additional
# processing to extract the deltas and citations

Streaming Example ​

Python
from openai import OpenAI

client = OpenAI(
    api_key="your-octagon-api-key",
    base_url="https://api-gateway.octagonagents.com/v1"
)

response = client.chat.completions.create(
    model="octagon-sec-agent",
    messages=[
        {"role": "user", "content": "What was Apple's revenue growth rate in Q3 2023 compared to Q3 2022?"}
    ],
    stream=True
)

full_analysis = ""
citations = []

# Process each chunk of the streaming response
for chunk in response:
    if chunk.choices[0].delta.content:
        content = chunk.choices[0].delta.content
        full_analysis += content
        print(content, end="")
    
    # Check if this is the final chunk with citations
    if hasattr(chunk.choices[0], 'citations'):
        citations = chunk.choices[0].citations

print("\n\nSOURCES:")
for citation in citations:
    print(f"{citation.order}. {citation.name}: {citation.url}")
JavaScript
import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'your-octagon-api-key',
  baseURL: 'https://api-gateway.octagonagents.com/v1',
});

async function getAnalysis() {
  const stream = await openai.chat.completions.create({
    model: 'octagon-sec-agent',
    messages: [
      { role: 'user', content: 'What was Apple\'s revenue growth rate in Q3 2023 compared to Q3 2022?' }
    ],
    stream: true
  });

  let fullAnalysis = '';
  let citations = [];

  for await (const chunk of stream) {
    // Accumulate content
    const content = chunk.choices[0]?.delta?.content || '';
    if (content) {
      fullAnalysis += content;
      process.stdout.write(content);
    }
    
    // Check for citations in the final chunk
    if (chunk.choices[0]?.finish_reason === 'stop' && chunk.choices[0]?.citations) {
      citations = chunk.choices[0].citations;
    }
  }

  console.log("\n\nSOURCES:");
  citations.forEach(citation => {
    console.log(`${citation.order}. ${citation.name}: ${citation.url}`);
  });
}

getAnalysis();
cURL
curl -X POST https://api-gateway.octagonagents.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-octagon-api-key" \
  -d '{
    "model": "octagon-sec-agent",
    "messages": [
      {
        "role": "user",
        "content": "What was Apple'\''s revenue growth rate in Q3 2023 compared to Q3 2022?"
      }
    ],
    "stream": true
  }' \
  --no-buffer

# Note: Handling the stream response with cURL requires additional
# processing to extract the deltas and citations

Understanding Streaming Format ​

The API returns a stream of data chunks in OpenAI-compatible format. Each chunk is a JSON object prefixed with data: and followed by two newline characters (\n\n). The final chunk is indicated by data: [DONE]\n\n.

Each chunk has the following structure:

json
{
  "id": "response_id",
  "object": "chat.completion.chunk",
  "created": 1700000000,
  "model": "octagon-sec-agent",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "Part of the content..."
      },
      "finish_reason": null
    }
  ]
}

The final chunk will have a finish_reason of "stop" and may include additional metadata like citations to sources.

Best Practices ​

  1. Provide Clear Queries: Be specific in your messages to get more accurate and relevant responses.
  2. Use Conversation Context: You can include previous messages in the messages array to maintain context in multi-turn interactions.
  3. Handle Streaming Efficiently: Update your UI incrementally as new content arrives rather than waiting for the full response.
  4. Display Citations: When available, display citations to show where information was sourced from.
  5. Implement Error Handling: Have robust error handling for network disruptions during streaming.

Next Steps ​