Skip to content

API.md

Latest commit

 

History

History
294 lines (243 loc) · 4.96 KB

API.md

File metadata and controls

294 lines (243 loc) · 4.96 KB

ByeBrief API Documentation

Overview

ByeBrief provides local API endpoints for AI model interaction. All endpoints are designed for local-first operation with Ollama.

Base URL

http://localhost:11434/api

Endpoints

Ollama Generate

POST /generate

Generate text completion from investigation data.

Request:

{
  "model": "llama3.2",
  "prompt": "Analyze the following investigation nodes: [nodes JSON]",
  "stream": false,
  "options": {
    "temperature": 0.7,
    "top_p": 0.9,
    "num_predict": 2048
  }
}

Response:

{
  "model": "llama3.2",
  "response": "The analysis shows that...",
  "done": true
}

Ollama Chat

POST /chat

Chat completion for interactive analysis.

Request:

{
  "model": "llama3.2",
  "messages": [
    {
      "role": "user",
      "content": "Analyze these claims for contradictions: [claims]"
    }
  ],
  "stream": false
}

Response:

{
  "model": "llama3.2",
  "message": {
    "role": "assistant",
    "content": "After reviewing the claims..."
  },
  "done": true
}

Health Check

GET /version

Check Ollama service status.

Response:

{
  "version": "0.5.4"
}

Canvas Payload Schema

When sending investigation data to the model, the following JSON structure is used:

Node Types

interface CanvasNode {
  id: string;
  type: 'cause' | 'timeline' | 'evidence' | 'person' | 
       'location' | 'law' | 'note' | 'analysis' | 
       'hypothesis' | 'conclusion';
  position: { x: number; y: number };
  data: {
    label: string;
    content: string;
    confidence: 'high' | 'medium' | 'low';
    source?: string;
    date?: string;
  };
}

Complete Payload Example

{
  "nodes": [
    {
      "id": "node-1",
      "type": "evidence",
      "position": { "x": 100, "y": 200 },
      "data": {
        "label": "Email Records",
        "content": "Email from 2024-01-15 shows communication between parties",
        "confidence": "high",
        "source": "FOIA Request #2024-001"
      }
    },
    {
      "id": "node-2",
      "type": "person",
      "position": { "x": 300, "y": 150 },
      "data": {
        "label": "John Smith",
        "content": "CEO of Company XYZ, present at meeting",
        "confidence": "high"
      }
    }
  ],
  "notes": [
    {
      "id": "note-1",
      "content": "Need to verify timestamp accuracy"
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "source": "node-1",
      "target": "node-2"
    }
  ]
}

Example Responses

AI Optimize Response

{
  "type": "structure-analysis",
  "suggestions": [
    {
      "type": "missing-evidence",
      "description": "No timeline events found - add dated entries",
      "priority": "high"
    },
    {
      "type": "gap-analysis",
      "description": "Missing location data for key events",
      "priority": "medium"
    }
  ],
  "missingInfo": [
    "Timeline nodes",
    "Source verification for claim #3"
  ]
}

Cross-Examine Response

{
  "type": "contradiction-analysis",
  "analysis": {
    "contradictions": [
      {
        "claimA": "Witness states meeting was at 2pm",
        "claimB": "Email timestamp shows 3pm",
        "severity": "high"
      }
    ],
    "riskRating": "7/10",
    "claimSupportChains": [
      {
        "claim": "Company knew about issue",
        "supporting": ["Email #1", "Meeting notes"],
        "strength": "strong"
      }
    ],
    "remediationActions": [
      "Request email server logs",
      "Interview witness about timeline"
    ]
  }
}

Generate Draft Response

{
  "type": "legal-report",
  "content": "EXECUTIVE SUMMARY\n\nThe evidence establishes that Company XYZ...",
  "sections": {
    "issue": "Whether Company XYZ violated Section 4...",
    "rule": "Under Sherman Act Section 4, liability requires...",
    "application": "The facts demonstrate that... (see Evidence nodes 1-5)",
    "conclusion": "Based on the foregoing, the plaintiff has established..."
  },
  "metadata": {
    "nodesReferenced": ["node-1", "node-2", "node-5"],
    "confidence": "high",
    "dateGenerated": "2024-03-15T10:30:00Z"
  }
}

Search API (Optional)

When web search is enabled:

Brave Search

GET https://api.search.brave.com/res/v1/web/search

Headers:

X-Subscription-Token: <your-api-key>

Tavily Search

POST https://api.tavily.com/search

Body:

{
  "api_key": "<your-api-key>",
  "query": "search query",
  "max_results": 10
}

Error Handling

Connection Failed

{
  "error": "connection_failed",
  "message": "Cannot connect to Ollama at http://localhost:11434",
  "suggestion": "Ensure Ollama is running: ollama serve"
}

Model Not Found

{
  "error": "model_not_found",
  "message": "Model 'gemma3' not found",
  "suggestion": "Pull the model: ollama pull gemma3"
}

Rate Limit

{
  "error": "rate_limit",
  "message": "Too many requests",
  "retryAfter": 30
}