PhrasIQ Developer Hub

Welcome to the PhrasIQ platform documentation. Our API-first architecture allows you to embed multi-agent intelligence directly into your enterprise applications. Unlike traditional "Chat APIs" which simply generate text, PhrasIQ's InSightOS provides a runtime for autonomous agents that can plan, reason, use tools, and persist state over long-running workflows.

Get up and running with a simple reasoning agent in less than 5 minutes. First, ensure you have your API key from the dashboard settings.

pip install phrasiq

Initialize the client and run a basic workflow:

import phrasiq
import os

client = phrasiq.Client(api_key=os.getenv("PHRASIQ_API_KEY"))

response = client.workflows.run(
    agent="finance_analyst_v2",
    input="Analyze the Q3 margin impact if supplier costs increase by 4%.",
    context={"current_margin": 0.22, "supplier_cost_ratio": 0.40}
)

print(f"Final Answer: {response.output}")

Agents are the core building blocks of InSightOS. Unlike a standard LLM chat completion, an Agent is a stateful entity that maintains Persona Coherence, manages Tool Execution, and enforces Grounding Rules throughout a conversation or workflow.

Agent Configuration Parameters

The `workflows.run` endpoint is the primary method to invoke an agent. It accepts an input prompt and optional structured context.

const response = await client.workflows.run({
  agentId: "logistics_router",
  input: "Route shipment #8892 to nearest hub with capacity.",
  context: { priority: "high", region: "NA_WEST" }
});

console.log(response.output);

For real-time applications, use workflows.stream. This returns a Server-Sent Events (SSE) stream. Events include not just the final text delta, but also "Thought Traces" (the agent's internal reasoning) and "Tool Calls".

Event Types

• text_delta: Partial chunk of the final answer.
• thought: Internal reasoning step (hidden from end-user typically).
• tool_start: Agent is beginning to execute a tool.
• tool_end: Tool execution completed with result.
• finish: Stream complete.

const stream = await client.workflows.stream({
  agentId: "support_agent",
  input: "Where is my order?"
});

for await (const event of stream) {
  if (event.type === 'thought') {
    console.debug("Thinking:", event.content);
  } else if (event.type === 'text_delta') {
    process.stdout.write(event.content);
  }
}

Tools allow agents to interact with the outside world. Tools are defined using standard JSON Schema. When an agent decides to call a tool, the InSightOS runtime pauses, executes the function (server-side or client-side), and feeds the result back to the model.

Defining a Tool

{
  "name": "get_weather",
  "description": "Retrieves current weather conditions for a specific city.",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { 
        "type": "string",
        "description": "The name of the city, e.g. 'London'"
      },
      "units": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      }
    },
    "required": ["city"]
  },
  "config": {
    "http": {
      "url": "https://api.weather.com/v2/current",
      "method": "GET",
      "headers": {
        "Authorization": "Bearer {{SECRETS.WEATHER_API_KEY}}"
      }
    }
  }
}

Note: You can securely store API keys in the PhrasIQ Secrets Manager and reference them in tool definitions using the {{SECRETS.KEY}} syntax.

Knowledge Bases provide long-term semantic memory for agents (RAG). Instead of stuffing documents into the context window, you connect data sources to a Knowledge Base. The agent automatically retrieves relevant chunks during reasoning.

Supported Connectors

curl -X POST https://api.phrasiq.com/v1/knowledge/connect \
  -H "Authorization: Bearer $API_KEY" \
  -d '{ 
    "name": "corporate_policy",
    "type": "s3", 
    "config": { 
      "bucket": "corp-docs-prod",
      "prefix": "hr/policies/",
      "region": "us-east-1"
    },
    "refresh_schedule": "daily"
  }'

For ad-hoc data ingestion, upload files directly. PhrasIQ handles parsing (PDF/OCR), chunking, embedding generation, and indexing automatically.

curl -X POST https://api.phrasiq.com/v1/vectors/upload \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@contract_v2.pdf" \
  -F "collection=legal_docs"

Loktak is the data engineering component. It provides a programmatic pipeline for generating synthetic training data, curating datasets, and fine-tuning models.

The `loktak.generate` method creates high-fidelity synthetic data based on a prompt or a seed dataset.

import phrasiq.loktak as loktak

job = loktak.generate(
    instruction="Generate clinical notes for cardiac symptoms.",
    count=5000,
    privacy="strict",
    output_format="jsonl"
)

print(f"Job ID: {job.id}")

Define a strict schema to ensure generated data is machine-readable and valid.

{
  "fields": [
    { "name": "patient_age", "type": "integer", "min": 18, "max": 99 },
    { "name": "symptoms", "type": "array", "items": "string" },
    { "name": "triage_category", "type": "categorical", "options": ["routine", "urgent", "emergency"] }
  ]
}

For large-scale operations (generating 1M+ rows or labeling huge datasets), use the asynchronous batch API.

curl https://api.phrasiq.com/v1/loktak/jobs/batch_label \
  -H "Authorization: Bearer $API_KEY" \
  -d '{ 
    "dataset_id": "ds_raw_emails_2025", 
    "instruction": "Extract the sentiment (Positive, Negative, Neutral) and the primary topic.",
    "callback_url": "https://api.acme.com/webhooks/loktak"
  }'

Fine-tuning allows you to create a custom version of an InSightOS foundation model. Loktak uses LoRA (Low-Rank Adaptation) to efficiently train adapter layers on your specific data.

Why Fine-Tune?
1. Style Alignment: Force the model to speak in your brand voice.
2. Domain Knowledge: Teach the model specific industry acronyms or codes.
3. Behavior Control: Strictly enforce JSON output formats even in complex edge cases.

const tune = await loktak.fineTune({
  baseModel: "insight-reasoning-v3",
  datasetId: "dataset_v9_curated",
  hyperparameters: {
    epochs: 3,
    learningRate: 0.0002
  },
  suffix: "custom-finance-v1"
});

console.log("Training started:", tune.id);

API limits depend on your organization's tier.

Authenticate requests using the `Authorization: Bearer` header. Keep your API keys secure.