Dropstone SDK

Dropstone JS/TS SDK ஆனது Dropstone agent runtime-உடன் தொடர்புகொள்வதற்கான type-safe கிளையன்ட்டை வழங்குகிறது. இது dropstone serve-ஐ ஒரு subprocess ஆக இயக்கி, அதை நோக்கி ஒரு typed HTTP கிளையன்ட்டை வழங்குகிறது. இது CLI பயன்படுத்தும் அதே உள்ளூர் agent-ஐ இயக்குவதால், ஒவ்வொரு SDK அமர்வும் உங்கள் கணக்கு நினைவகத்தைப் பெறுகிறது — CLI, அரட்டை அல்லது SDK-இல் ஒருமுறை கற்றுக்கொடுத்தால், ஒவ்வொரு மேற்பரப்பும் அதை ஏற்கனவே அறிந்திருக்கும் (பார்க்க Memory (Continuity)).

அடிப்படை HTTP API எவ்வாறு செயல்படுகிறது என்பதற்கு Server பக்கத்தைப் பார்க்கவும்.

நிறுவல்

npm-இலிருந்து SDK-ஐ நிறுவவும்:

npm install @blankline/dropstone-sdk

Headless API கிளையன்ட்

CI pipelines, automation மற்றும் serverless-க்கு உங்களுக்கு CLI தேவையில்லை. API key உடன் Dropstone HTTP API-யுடன் நேரடியாகப் பேசும் headless கிளையன்ட்டைப் பயன்படுத்தவும்:

import { createDropstoneApi } from "@blankline/dropstone-sdk"

// சூழலில் இருந்து DROPSTONE_API_KEY-ஐ தானாகவே படிக்கிறது.
const dropstone = createDropstoneApi()

const resp = await dropstone.chat.completions.create({
  model: "dropstone-fast", // அல்லது "dropstone-pro" / "dropstone-heavy"
  messages: [{ role: "user", content: "டீபகிங் பற்றி ஒரு ஹைக்கு எழுது." }],
})

console.log(resp.choices[0].message.content)
console.log("Cost: $" + resp.usage?.cost) // வசூலிக்கப்பட்ட தொகை, USD-இல்

API key பெறுதல்

1. dropstone.io/dashboard-இல் உள்நுழையவும்.
2. dropstone.io/dashboard/settings-இல் Settings → API-ஐத் திறந்து ஒரு key-ஐ உருவாக்கவும் — அது dsk_live_<43 chars> போல இருக்கும்.
3. அதை ஒரு environment variable ஆக அமைக்கவும் (அல்லது createDropstoneApi-க்கு apiKey-ஐ அனுப்பவும்):

export DROPSTONE_API_KEY=dsk_live_...

ஸ்ட்ரீமிங் அதே வழியில் செயல்படுகிறது, மேலும் கிளையன்ட் OpenAI-இணக்கமானது — OpenAI SDK-ஐ Dropstone-இன் base URL-ஐ நோக்கி சுட்டிக்காட்டலாம்:

const stream = await dropstone.chat.completions.create({
  model: "dropstone-fast",
  stream: true,
  messages: [{ role: "user", content: "5 வரை எண்ணு." }],
})

for await (const chunk of stream) {
  process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "")
}

முழு குறிப்புக்கு HTTP API பக்கத்தைப் பார்க்கவும்.

கிளையன்ட் உருவாக்கம்

dropstone-இன் ஒரு நிகழ்வை உருவாக்கவும்:

import { createDropstone } from "@blankline/dropstone-sdk"

const { client } = await createDropstone()

இது ஒரு சர்வர் மற்றும் ஒரு கிளையன்ட் இரண்டையும் தொடங்குகிறது. ஒவ்வொரு SDK முறையும் { data, request, response }-ஐ திருப்பித் தருகிறது, எனவே payload-ஐ .data வழியாக அணுகவும்.

இயல்பாக, சர்வர் அந்த இயந்திரத்தில் dropstone auth login யார் இயக்கினாரோ அவராக உள்நுழைகிறது. கவனிக்கப்படாத host-இல் அத்தகைய கணக்கு இல்லை, எனவே config வழியாக API key மற்றும் வெளிப்படையான permission allowlist-ஐ அனுப்பவும்:

const { client } = await createDropstone({
  config: {
    provider: {
      dropstone: {
        options: {
          apiKey: process.env.DROPSTONE_API_KEY,
          baseURL: "https://api.dropstone.io/api/v1",
        },
      },
    },
    permission: { "*": "deny", read: "allow", edit: "allow", glob: "allow", grep: "allow", bash: "allow" },
  },
})

இரண்டு பகுதிகளும் தேவை. API keys /v1-இல் நிராகரிக்கப்படுகின்றன, மேலும் இயல்பான build agent ஒவ்வொரு tool அழைப்பிற்கு முன்பும் கேட்கிறது, எனவே allowlist இல்லாமல் இயக்கம் யாரும் கொடுக்க முடியாத ஒப்புதலுக்காக காத்திருந்து, தோல்வியடைவதற்குப் பதிலாக தொங்குகிறது. Allowlist-க்கு மாற்றாக prompt-இல் "agent": "accept all" அனுப்புவது. பார்க்க Server மற்றும் Permissions.

விருப்பங்கள்

கட்டமைப்பு

நடத்தையைத் தனிப்பயனாக்க ஒரு கட்டமைப்பு பொருளை அனுப்பலாம். நிகழ்வு உங்கள் dropstone.json-ஐ இன்னும் எடுக்கிறது, ஆனால் நீங்கள் கட்டமைப்பை inline ஆக மேலெழுதலாம் அல்லது சேர்க்கலாம்:

import { createDropstone } from "@blankline/dropstone-sdk"

const dropstone = await createDropstone({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    model: "dropstone/dropstone-pro",
  },
})

console.log(`Server running at ${dropstone.server.url}`)

dropstone.server.close()

Memory (Continuity)

Dropstone ஒவ்வொரு கணக்கிற்கும் ஒரு நிலையான நினைவகத்தை வைத்திருக்கிறது. அதை நாங்கள் Continuity என்று அழைக்கிறோம் — CLI, அரட்டை, VS Code மற்றும் SDK ஆகியவற்றால் பகிரப்பட்ட ஒரு குறுக்கு-மேற்பரப்பு நினைவகம். எங்கும் ஒருமுறை கற்றுக்கொடுத்தால், ஒவ்வொரு மேற்பரப்பும் அதை ஏற்கனவே அறிந்திருக்கும்.

SDK வழியாக நீங்கள் இயக்கும் அமர்வுகள் CLI போன்ற அதே கணக்கு நினைவகத்தைப் பயன்படுத்துகின்றன. CLI-க்கு நீங்கள் கற்றுக்கொடுப்பது SDK அமர்வுகளுக்கு ஏற்கனவே தெரியும், மேலும் SDK அமர்வு பதிவு செய்வது CLI மற்றும் அரட்டையில் மீண்டும் கிடைக்கிறது. ஒவ்வொரு திருப்பத்திலும், agent பதிலளிக்கும் முன் தொடர்புடைய நினைவகத்தை தானாகவே நினைவுபடுத்துகிறது, எனவே அது ஏற்கனவே தெரிந்ததை மீண்டும் கற்காது.

SDK agent நினைவகத்தை நேரடியாகப் படிக்கவும் எழுதவும் முடியும், CLI போன்ற அதே கருவிகளுடன்:

எடுத்துக்காட்டு

குறியீட்டிலிருந்து ஒரு விருப்பத்தைக் கூறுங்கள், அது CLI-இல் பதிவு செய்யப்படும் அதே வழியில் பதிவு செய்யப்படுகிறது — பின்னர் CLI மற்றும் அரட்டையில் தெரியும்:

const { client } = await createDropstone()

const session = await client.session.create({ body: { title: "Teach memory" } })

await client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "இதை ஒரு நிலையான விதியாக நினைவில் வை: எப்போதும் bun பயன்படுத்து, npm அல்ல." }],
  },
})

Continuity vs AGENTS.md

AGENTS.md என்பது குழு மரபுகளுக்காக நீங்கள் Git-இல் commit செய்யும் ஒரு திட்ட கோப்பு — நிலையானது, repo-ஸ்கோப் செய்யப்பட்டது, மற்றும் அதை clone செய்யும் எவருடனும் பகிரப்படுகிறது. Continuity உங்கள் தனிப்பட்ட கணக்கு நினைவகம்: CLI, அரட்டை அல்லது SDK-இல் நீங்கள் கற்றுக்கொடுப்பது உங்கள் கணக்கை மேற்பரப்புகள் மற்றும் திட்டங்களுக்கு இடையில் பின்தொடர்கிறது. அவை வெவ்வேறு சிக்கல்களைத் தீர்க்கின்றன மற்றும் சிறப்பாக ஒன்றாக வேலை செய்கின்றன — திட்ட விதிகள் AGENTS.md-இல், தனிப்பட்ட குறுக்கு-மேற்பரப்பு நினைவகம் Continuity-இல். பார்க்க Rules மற்றும் Memory.

என்ன நினைவில் வைக்கப்படுகிறது

நினைவகம் நீங்கள் வெளிப்படையாக கற்றுக்கொடுக்கும் விதிகள் மற்றும் உண்மைகளை மட்டுமே சேமிக்கிறது — விருப்பங்கள், மரபுகள் மற்றும் திருத்தங்கள் அமர்வுகளுக்கு இடையில் எடுத்துச் செல்லத்தக்கவை. இது ஒரு அமர்வின் நிலையற்ற சூழலில் இருந்து வேறுபட்டது, இது அமர்வு முடிந்த பிறகு வைக்கப்படாது.

Dropstone என்ன வைக்க வேண்டும் என்பதை எவ்வாறு தீர்மானிக்கிறது என்பதற்கு Memory பக்கத்தைப் பார்க்கவும்.

கிளையன்ட் மட்டும்

உங்களிடம் ஏற்கனவே இயங்கும் dropstone நிகழ்வு இருந்தால், அதனுடன் இணைக்க ஒரு கிளையன்ட் நிகழ்வை உருவாக்கலாம்:

import { createDropstoneClient } from "@blankline/dropstone-sdk"

const client = createDropstoneClient({
  baseUrl: "http://localhost:4096",
})

விருப்பங்கள்

வகைகள்

SDK அனைத்து API வகைகளுக்கான TypeScript வரையறைகளை உள்ளடக்கியது. அவற்றை நேரடியாக இறக்குமதி செய்யவும்:

import type { Session, Message, Part } from "@blankline/dropstone-sdk"

அனைத்து வகைகளும் சர்வரின் OpenAPI விவரக்குறிப்பிலிருந்து உருவாக்கப்படுகின்றன, எனவே TypeScript-இல் நீங்கள் காணும் பெயர்கள் server கோரிக்கை மற்றும் பதில் வடிவங்களுடன் ஒன்றுக்கு ஒன்று ஒத்துப்போகின்றன.

பிழைகள்

SDK நீங்கள் பிடித்து கையாளக்கூடிய பிழைகளை எறியலாம்:

try {
  await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
  console.error("Failed to get session:", (error as Error).message)
}

கட்டமைக்கப்பட்ட வெளியீடு

JSON schema உடன் ஒரு format-ஐக் குறிப்பிடுவதன் மூலம் மாதிரியிலிருந்து கட்டமைக்கப்பட்ட JSON வெளியீட்டைக் கோரலாம். மாதிரி உங்கள் schema-உடன் பொருந்தக்கூடிய சரிபார்க்கப்பட்ட JSON-ஐத் திருப்பித் தர StructuredOutput கருவியைப் பயன்படுத்தும்.

அடிப்படை பயன்பாடு

const result = await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: "text", text: "Dropstone-ஐ ஆராய்ந்து நிறுவன தகவலை வழங்கு" }],
    format: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          company: { type: "string", description: "நிறுவன பெயர்" },
          founded: { type: "number", description: "நிறுவப்பட்ட ஆண்டு" },
          products: {
            type: "array",
            items: { type: "string" },
            description: "முக்கிய தயாரிப்புகள்",
          },
        },
        required: ["company", "founded"],
      },
    },
  },
})

// கட்டமைக்கப்பட்ட வெளியீட்டை அணுகவும்
console.log(result.data.info.structured_output)
// { company: "Dropstone", founded: 2024, products: ["Dropstone CLI"] }

வெளியீட்டு வடிவ வகைகள்

JSON Schema வடிவம்

type: 'json_schema' பயன்படுத்தும்போது, வழங்கவும்:

பிழை கையாளுதல்

அனைத்து மறுமுயற்சிகளுக்குப் பிறகும் மாதிரி சரியான கட்டமைக்கப்பட்ட வெளியீட்டை உருவாக்கத் தவறினால், பதில் ஒரு StructuredOutputError-ஐ உள்ளடக்கும்:

if (result.data.info.error?.name === "StructuredOutputError") {
  console.error("Failed to produce structured output:", result.data.info.error.message)
  console.error("Attempts:", result.data.info.error.retries)
}

சிறந்த நடைமுறைகள்

1. தெளிவான விளக்கங்களை வழங்கவும் உங்கள் schema பண்புகளில் மாதிரி என்ன தரவைப் பிரித்தெடுக்க வேண்டும் என்பதைப் புரிந்துகொள்ள உதவ
2. required பயன்படுத்தவும் எந்த புலங்கள் இருக்க வேண்டும் என்பதைக் குறிப்பிட
3. Schemas-ஐ கவனம் செலுத்தி வைக்கவும் - சிக்கலான உள்ளமைந்த schemas மாதிரி சரியாக நிரப்ப கடினமாக இருக்கலாம்
4. பொருத்தமான retryCount அமைக்கவும் - சிக்கலான schemas-க்கு அதிகரிக்கவும், எளியவற்றுக்கு குறைக்கவும்

APIs

SDK அனைத்து சர்வர் API-களையும் type-safe கிளையன்ட் மூலம் வெளிப்படுத்துகிறது.

Global

எடுத்துக்காட்டுகள்

const health = await client.global.health()
console.log(health.data.version)

App

எடுத்துக்காட்டுகள்

// ஒரு log பதிவை எழுதவும்
await client.app.log({
  body: {
    service: "my-app",
    level: "info",
    message: "Operation completed",
  },
})

// கிடைக்கக்கூடிய agents-ஐ பட்டியலிடவும்
const agents = await client.app.agents()

Project

எடுத்துக்காட்டுகள்

// அனைத்து திட்டங்களையும் பட்டியலிடவும்
const projects = await client.project.list()

// தற்போதைய திட்டத்தைப் பெறவும்
const currentProject = await client.project.current()

Path

எடுத்துக்காட்டுகள்

// தற்போதைய பாதை தகவலைப் பெறவும்
const pathInfo = await client.path.get()

Config

எடுத்துக்காட்டுகள்

const config = await client.config.get()

Sessions

எடுத்துக்காட்டுகள்

// அமர்வுகளை உருவாக்கி நிர்வகிக்கவும்
const session = await client.session.create({
  body: { title: "My session" },
})

const sessions = await client.session.list()

// ஒரு prompt செய்தியை அனுப்பவும்
const result = await client.session.prompt({
  path: { id: session.data.id },
  body: {
    model: { providerID: "dropstone", modelID: "dropstone-pro" },
    parts: [{ type: "text", text: "Hello!" }],
  },
})

// AI பதிலைத் தூண்டாமல் சூழலை செருகவும் (plugins-க்கு பயனுள்ளது)
await client.session.prompt({
  path: { id: session.data.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "You are a helpful assistant." }],
  },
})

Files

find.files சில விருப்ப query புலங்களை ஆதரிக்கிறது:

• type: "file" அல்லது "directory"
• directory: தேடலுக்கான திட்ட மூலத்தை மேலெழுதவும்
• limit: அதிகபட்ச முடிவுகள் (1–200)

எடுத்துக்காட்டுகள்

// கோப்புகளைத் தேடி படிக்கவும்
const textResults = await client.find.text({
  query: { pattern: "function.*dropstone" },
})

const files = await client.find.files({
  query: { query: "*.ts", type: "file" },
})

const directories = await client.find.files({
  query: { query: "packages", type: "directory", limit: 20 },
})

const content = await client.file.read({
  query: { path: "src/index.ts" },
})

Auth

எடுத்துக்காட்டுகள்

await client.auth.set({
  path: { id: "dropstone" },
  body: { type: "api", key: "your-dropstone-api-key" },
})

Events

எடுத்துக்காட்டுகள்

// நிகழ்நேர நிகழ்வுகளைக் கேளுங்கள்
const events = await client.event.subscribe()
for await (const event of events.stream) {
  console.log("Event:", event.type, event.properties)
}

v2 API

SDK ஒரு நிலையான v1 மேற்பரப்பை (மேலே உள்ள எடுத்துக்காட்டுகளில் பயன்படுத்தப்படுகிறது) மற்றும் புதிய Effect HttpApi ஒப்பந்தத்தை பிரதிபலிக்கும் ஒரு v2 மேற்பரப்பை வழங்குகிறது. புதிய ஒருங்கிணைப்புகளுக்கு v2-ஐ விரும்புங்கள்:

import { createDropstone } from "@blankline/dropstone-sdk/v2"

const { client, server } = await createDropstone()
// v2 ஒரு பணக்கார வள படிநிலையை வெளிப்படுத்துகிறது: workspace, worktree, file, find, போன்றவை.
const files = await client.file.list({ path: "src" })

v1 மேற்பரப்பு பின்னோக்கி இணக்கத்திற்காக வைக்கப்படுகிறது. புதிய endpoints v2-இல் மட்டுமே வருகின்றன.