What Is Tinkuy?

Tinkuy (Quechua: "where rivers meet") is where your tools, models, and budgets converge into one agent loop. Call LLM → parse tool_calls → execute → feed back → repeat. No vendor lock-in, no heavy dependencies, no framework opinions.

import { Agent, defineTool } from '@carloscortezcloud/tinkuy-agent';
import { StyrRouter } from '@carloscortezcloud/styrr-llm';
import { SayayGuard, MemoryStorage } from '@carloscortezcloud/sayay-guard';

const getWeather = defineTool({
  name: 'get_weather',
  description: 'Get current weather for a city',
  parameters: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
  execute: async ({ city }) => ({ temp: 22, condition: 'sunny', city }),
});

const agent = new Agent({
  router: new StyrRouter({
    apiKey: process.env.OPENROUTER_API_KEY!,
    models: [{ id: 'meta-llama/llama-3.3-70b-instruct:free' }],
  }),
  guard: new SayayGuard({
    storage: new MemoryStorage(),
    budget: { dailyUsd: 5.0 },
  }),
  tools: [getWeather],
  systemPrompt: 'You are a helpful assistant. Use tools when needed.',
});

const result = await agent.run('What is the weather in Lima?');
console.log(result.text);           // "The weather in Lima is 22°C and sunny."
console.log(result.iterations);     // 2
console.log(result.totalLatencyMs); // ~3500

Install

npm install @carloscortezcloud/tinkuy-agent

Quick Start

1. Install

npm install @carloscortezcloud/tinkuy-agent @carloscortezcloud/styrr-llm @carloscortezcloud/sayay-guard

2. Run your first agent

import { Agent, defineTool } from '@carloscortezcloud/tinkuy-agent';

const agent = new Agent({
  router: { call: async () => ({ text: 'Hello!', modelUsed: 'mock', latencyMs: 0 }) },
  tools: [],
  systemPrompt: 'You are a helpful assistant.',
});

const result = await agent.run('Say hello');
console.log(result.text);

How It Works

User: "What's the weather?"
  │
  ▼ iteration 1
Agent → LLM: "Here are my tools: [get_weather]. User asks about weather."
LLM → Agent: tool_call { name: "get_weather", args: { city: "Lima" } }
Agent → Tool: execute get_weather({ city: "Lima" })
Tool → Agent: { temp: 22, condition: "sunny" }
  │
  ▼ iteration 2
Agent → LLM: "Tool returned: {temp: 22, sunny}. Answer the user."
LLM → Agent: "The weather in Lima is 22°C and sunny."
  │
  ▼ done
Agent → User: { text, iterations, toolsUsed, totalLatencyMs }

Features

| Feature | Description | |---------|-------------| | Tool loop | Call LLM → parse tool_calls → execute → feed back → repeat | | Budget guard | Sayay integration — block/degrade/warn before each call | | Multi-model | Styrr integration — fallback chain, cheapest, fastest | | Streaming | Agent.stream() yields AG-UI events (text_delta, tool_call_result, done, blocked) | | SSE helper | agentToSSE() converts stream to Cloudflare Worker Response | | Observable | onIteration + onToolCall + onComplete hooks | | Deterministic grounding | ontology module — validate output vs strict graph, zero-token cost (TokenOps) | | Conversation state | MemoryConversationStore / KVConversationStore with sliding windows | | Max iterations | Infinite loop protection (default 10) | | Error resilient | Tool errors fed back to LLM — it recovers | | Zero deps (core) | Core agent loop is dependency-free; only yaml for the optional ontology module | | Tiny | ~200 lines core logic, ~5KB bundled |

Streaming

import { Agent, agentToSSE } from '@carloscortezcloud/tinkuy-agent';

const stream = agent.stream(message, { sessionId });

// In a Cloudflare Worker:
return new Response(agentToSSE(stream), {
  headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },
});

Stream events follow the AG-UI format:

{ type: 'iteration_start', iteration: 1, modelUsed: '...' }
{ type: 'text_delta', text: 'The weather' }
{ type: 'tool_call_result', tool: 'get_weather', toolResult: {...} }
{ type: 'done', iterations: 2, toolsUsed: ['get_weather'], totalLatencyMs: 3500 }

Observability

const agent = new Agent({
  router,
  tools,
  onIteration: (event) => console.log('iteration', event.iteration),
  onToolCall: (event) => console.log('tool', event.tool, event.durationMs),
  onComplete: (event) => {
    console.log('run done', event.result);
    // Push to Qhaway for cost/latency observability
  },
});

BYO Router (No Styrr/Sayay Required)

import { Agent } from '@carloscortezcloud/tinkuy-agent';
import type { Router, RouterResponse, Message } from '@carloscortezcloud/tinkuy-agent';

const myRouter: Router = {
  async call(messages: Message[]): Promise<RouterResponse> {
    const res = await fetch('https://api.openai.com/v1/chat/completions', { ... });
    return { text: '...', modelUsed: 'gpt-4o', latencyMs: 1200 };
  }
};

const agent = new Agent({ router: myRouter, tools: [...], systemPrompt: '...' });

Architecture

┌─────────────────────────────────────┐
│ Tinkuy Agent                        │
│                                     │
│  ┌─────────┐  ┌───────┐  ┌──────┐  │
│  │ Router  │  │ Guard │  │Tools │  │
│  │ (Styrr) │  │(Sayay)│  │(yours)│  │
│  └────┬────┘  └───┬───┘  └──┬───┘  │
│       │            │         │      │
│       ▼            ▼         ▼      │
│  ┌──────────────────────────────┐   │
│  │     Agent Loop (core)        │   │
│  │  for each iteration:         │   │
│  │    guard.check() → allow?    │   │
│  │    router.call() → response  │   │
│  │    guard.record() → track    │   │
│  │    if tool_calls → execute   │   │
│  │    if text → return          │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘

Ecosystem

| Package | Role | npm | |---------|------|-----| | Tinkuy | Agent framework (this) | @carloscortezcloud/tinkuy-agent | | Styrr | LLM router | styrr | | Sayay | Cost guardrails | GitHub | | Qhaway | Agent observability | @carloscortezcloud/qhaway | | TideRAG | Edge RAG pipeline | @carloscortezcloud/tiderag |

Deterministic Ontology Validation

Validate LLM output against a strict T-Box schema (entities + allowed relations + property types) in pure CPU/memory — zero token cost. This replaces LLM-as-a-judge for grounding decisions, per the TokenOps research. New to ontologies? Start with the Ontologies 101 guide.

import { Agent } from '@carloscortezcloud/tinkuy-agent';
import { loadOntology } from '@carloscortezcloud/tinkuy-agent/ontology';

const ontology = await loadOntology('schema/tokenops_ontology.yaml');

const agent = new Agent({
  router,
  tools,
  ontology,                 // optional — without it, behavior is unchanged
  onOntologyValidated: ({ validation }) => console.log('grounded', validation.relations),
});

With fail_on_unknown_relation: true in the schema, a hallucinated entity/relation throws OntologyViolationException and the response is not persisted or billed. The validator also compresses the payload to pure data relations, feeding prompt caching.

Schema v1.1 adds deterministic grounding depth beyond type checking: required properties, enum constraints, relation cardinality (1:1/1:N/N:1/N:M), min/max instance counts, and a governance meta block. Property shorthand (id: "UUID") still works — full specs are optional.

# schema/tokenops_ontology.yaml (v1.1)
meta:
  description: "Dominio de operaciones de clientes"
  owner: "finops-platform"
ontology:
  entities:
    - name: "Client"
      min_instances: 1
      properties:
        id: { type: "UUID", required: true }
        status:
          type: "STRING"
          enum: ["ACTIVE", "INACTIVE", "BLOCKED"]
          required: true
    - name: "Invoice"
      properties:
        id: { type: "UUID", required: true }
        amount: { type: "FLOAT", required: true }
        currency:
          type: "STRING"
          enum: ["USD", "EUR", "PEN"]
          required: true
  allowed_relations:
    - origin: "Client"
      relation: "HAS_BILLING_DISPUTE"
      target: "Invoice"
      cardinality: "1:N"   # un Client, muchas disputas
    - origin: "Invoice"
      relation: "BELONGS_TO"
      target: "Client"
      cardinality: "1:1"   # una factura, un único cliente
harness_constraints:
  enforce_json_schema: true
  fail_on_unknown_relation: true   # KILL SWITCH on hallucination

Violations are surfaced with structured kinds for observability (Qhaway/Phoenix): unknown_entity, unknown_relation, invalid_target, invalid_property_type, missing_required_property, invalid_enum_value, cardinality_exceeded, min_instances_not_met.

License

Apache 2.0 — see LICENSE.