dilnaka 0.0.4

Python SDK for Dilnaka file uploads

Dilnaka Python SDK

Python SDK for uploading files through the Dilnaka Upload API.

The SDK reads configuration from explicit arguments first, then environment variables. It requests a presigned S3 upload URL from your Dilnaka backend, uploads the file directly to S3, and calls the completion endpoint.

Install

pip install dilnaka

To create the workspace AI instruction file explicitly after install:

dilnaka-sync-instructions --print-path

The SDK also attempts a best-effort sync when dilnaka is imported, and again the first time Dilnaka(...) is constructed in an application workspace. That creates .github/instructions/dilnaka.instructions.md when the current project root can be detected.

Configure

You can pass configuration directly to Dilnaka(...), or set environment variables for your application.

If you use a .env file, create it in your application project:

DILNAKA_API_KEY=dlk_dev_your_api_key_here
DILNAKA_BASE_URL=https://dilnaka.tsnc.tech
DILNAKA_TIMEOUT=60

DILNAKA_BASE_URL defaults to https://dilnaka.tsnc.tech and DILNAKA_TIMEOUT defaults to 60.

Basic upload

from dilnaka import Dilnaka

client = Dilnaka()

uploaded = client.upload("./test-upload.txt")

print(uploaded.id)
print(uploaded.key)
print(uploaded.status)

Explicit configuration

from dilnaka import Dilnaka

client = Dilnaka(
    api_key="dlk_dev_your_api_key_here",
    base_url="https://dilnaka.tsnc.tech",
)

uploaded = client.upload("./avatar.png", folder="avatars")
print(uploaded)

Expected backend endpoints

The SDK expects your Caspian backend to expose:

POST /v1/uploads/presign
POST /v1/uploads/complete
GET  /v1/files
GET  /v1/files/{file_id}
DELETE /v1/files/{file_id}

Presign response shape

{
  "fileId": "clx_file_id",
  "fileKey": "uploads/2026/05/clx_file_id-test.txt",
  "uploadUrl": "https://s3-presigned-url",
  "expiresIn": 300,
  "method": "PUT",
  "headers": {
    "Content-Type": "text/plain"
  }
}

Complete response shape

{
  "fileId": "clx_file_id",
  "status": "uploaded",
  "key": "uploads/2026/05/clx_file_id-test.txt",
  "originalName": "test.txt",
  "contentType": "text/plain",
  "size": 94,
  "publicUrl": null
}

Security model

The SDK never receives AWS credentials. It only receives a temporary presigned upload URL from your Dilnaka backend.

Your backend remains responsible for API key validation, scope checking, file validation, S3 key generation, metadata persistence, and upload completion verification.

AI workspace instructions

Python packaging does not provide a reliable cross-environment post-install hook for wheel installs, so the SDK ships its own instruction-file generator instead of trying to mutate arbitrary projects during pip install or uv add.

Use dilnaka-sync-instructions in install scripts when you need deterministic creation, or rely on the SDK's best-effort sync on import and first client use.