SDK Reference

chat.create(messages, **kwargs) → ChatResponse

Send a conversation and get a response.

response = client.chat.create(
    messages=[
        {"role": "user", "content": "Explain quantum computing"}
    ],
    model="llama-3.3-70b-versatile",  # optional
    max_tokens=512,  # optional
    temperature=0.7  # optional
)
print(response.text)        # str: The generated response
print(response.model)       # str: Model used
print(response.tokens_used) # int: Token count
print(response.latency_ms)  # int: Milliseconds to generate

chat.stream(messages, **kwargs) → Generator[ChatStreamChunk]

Stream response tokens in real-time.

for chunk in client.chat.stream(
    messages=[{"role": "user", "content": "Write a poem about AI"}]
):
    print(chunk.delta, end="", flush=True)  # str: Token delta
    # chunk.done == True on last chunk

agents.list() → List[AgentInfo]

List all 109 available agents.

agents = client.agents.list()
for agent in agents:
    print(f"{agent.id}: {agent.description}")
    print(f"  Category: {agent.category}")
    print(f"  Parameters: {agent.parameters}")

agents.run(agent_type: str, prompt: str, params: dict) → RunAgentResponse

Execute an agent with a task prompt.

result = client.agents.run(
    "harika",
    prompt="Analyze security posture of this codebase",
    params={"depth": "comprehensive", "include_deps": True}
)
print(result.task_id)  # str: ID for polling
print(result.status)   # str: Current status

The memory API persists key-value data and supports semantic search across stored entries.

# Store a value
client.memory.store("project_context", {
    "name": "my-app",
    "stack": "Next.js + FastAPI",
    "last_review": "2026-03-27"
})

# Retrieve by key
ctx = client.memory.get("project_context")
print(ctx)  # dict: stored value

# Semantic search across all stored entries
results = client.memory.search("project stack technology")
for item in results:
    print(f"{item.key}: {item.score:.2f} — {item.preview}")

Use AsyncLydosClient for async/await workflows. All methods mirror the synchronous client.

import asyncio
from lydos import AsyncLydosClient

async def main() -> None:
    async with AsyncLydosClient(token="lyd_sk_...") as client:
        response = await client.chat.create(
            messages=[{"role": "user", "content": "Hello"}]
        )
        print(response.text)

        result = await client.agents.run(
            "harika",
            prompt="Scan ./src for security issues"
        )
        print(result.task_id)

asyncio.run(main())

tasks.list(status: str = None) → List[TaskInfo]

List tasks with optional status filter.

# List running tasks
tasks = client.tasks.list(status="running")

# List all tasks
all_tasks = client.tasks.list()

tasks.get(id: str) → TaskInfo

Get full task details including result.

task = client.tasks.get("task_3f8c9d2e1b4a5e7f")
print(task.status)           # str: running | completed | failed
print(task.result)           # str: Final result (when completed)
print(task.elapsed_seconds)  # int: Execution time

tasks.cancel(id: str) → None

Cancel a running or pending task.

client.tasks.cancel("task_3f8c9d2e1b4a5e7f")

health() → HealthResponse

Get system health and metrics.

health = client.health()
print(health.score)            # int: 0-100
print(health.status)           # str: operational | degraded | outage
print(health.engines_active)   # int: Number of active Q-engines
print(health.agents_available) # int: Number of available agents

engines.list() → List[EngineInfo]

List all Q-engines (Q1–Q248) with details.

engines = client.engines.list()
for engine in engines:
    print(f"{engine.id}: {engine.name}")

All exceptions inherit from LydosError. Catch specific subclasses for granular handling:

from lydos import LydosClient, LydosError, LydosAuthError, LydosRateLimitError

client = LydosClient(token="lyd_sk_...")

try:
    response = client.chat.create(
        messages=[{"role": "user", "content": "Hello"}]
    )
except LydosAuthError:
    # Token is invalid or has been revoked
    print("Invalid token — run: lydos login")
except LydosRateLimitError as e:
    # HTTP 429 — back off and retry
    print(f"Rate limit hit. Retry after {e.retry_after}s")
except LydosError as e:
    # Catch-all for any other API or network error
    print(f"LyDos error: {e.status_code} — {e.message}")

chat.create(options): Promise<ChatResponse>

Send a conversation and get a response.

const response = await client.chat.create({
  messages: [{ role: 'user', content: 'Explain async/await' }],
  model: 'llama-3.3-70b-versatile', // optional
  maxTokens: 512,                    // optional
});
console.log(response.text);        // Response text
console.log(response.model);       // Model name
console.log(response.tokensUsed);  // Token count
console.log(response.latencyMs);   // Latency in ms

chat.stream(options): AsyncGenerator<ChatStreamChunk>

Stream response tokens.

for await (const chunk of client.chat.stream({
  messages: [{ role: 'user', content: 'Write a poem' }],
})) {
  process.stdout.write(chunk.delta);
}

import {
  LydosClient,
  LydosAuthError,
  LydosRateLimitError,
  LydosError,
} from '@lydos/sdk';

const client = new LydosClient({ token: process.env.LYDOS_TOKEN });

try {
  const response = await client.chat.create({
    messages: [{ role: 'user', content: 'Hello' }],
  });
  console.log(response.text);
} catch (err) {
  if (err instanceof LydosAuthError) {
    console.error('Invalid token — run: lydos login');
  } else if (err instanceof LydosRateLimitError) {
    console.error(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof LydosError) {
    console.error(`API error ${err.statusCode}: ${err.message}`);
  } else {
    throw err;
  }
}

Connect to the real-time event stream for live health, task, and metrics updates:

import { LydosWebSocket } from '@lydos/sdk';

const ws = new LydosWebSocket({
  url: 'wss://lydos.ailydian.com/v1/stream',
  token: process.env.LYDOS_TOKEN!,
});

ws.on('health', (data) => {
  console.log(`Health: ${data.score}/100`);
});

ws.on('task_update', (data) => {
  console.log(`Task ${data.taskId}: ${data.status}`);
});

ws.on('metrics', (data) => {
  console.log(`Active agents: ${data.agentsActive}`);
});

ws.connect();

// Cleanup
ws.disconnect();