KDeps

KDeps is an all-in-one, offline-ready AI framework for building Dockerized full-stack applications with declarative PKL configuration, featuring integrated open-source LLMs for AI-powered APIs and workflows. Runs fully local with no external AI APIs required.

📋 New: Read our comprehensive KDeps Whitepaper for detailed technical insights, architecture overview, and competitive analysis.

About the name

“KDeps, short for ‘knowledge dependencies,’ is inspired by the principle that knowledge—whether from AI, machines, or humans—can be represented, organized, orchestrated, and interacted with through graph-based systems. The name grew out of my work on Kartographer, a lightweight graph library for organizing and interacting with information. KDeps builds on Kartographer’s foundation and serves as a RAG-first (Retrieval-Augmented Generation) AI agent framework.” — Joel Bryan Juliano, KDeps creator

Why Offline-First?

Privacy and compliance: Keep sensitive data on your own machines (PII, GDPR, HIPAA).
Reliability: Operates without internet or in degraded networks.
Low latency: Local inference avoids network round-trips.
Predictable cost: No per-token fees; models run locally.
Control and independence: Avoids vendor lock-in; reproducible on-prem.
Data residency: Meets jurisdictional requirements.
Security: Minimizes external attack surface, no third-party AI APIs.
Edge readiness: Process data where it’s generated.
Productivity: Self-contained Docker images for local dev and deployment.

KDeps achieves offline-first by integrating open-source LLMs via Ollama and packaging full applications—including models and runtimes—into Docker images. No external AI APIs are required.

Key Features

KDeps is loaded with features to streamline full-stack AI apps development:

🧩 Low-code/no-code capabilities

Build operational full-stack AI apps, enabling accessible development for non-technical users.

pkl

// workflow.pkl
Name = "ticketResolutionAgent"
Description = "Automates customer support ticket resolution with LLM responses."
Version = "1.0.0"
TargetActionID = "responseResource"
Settings {
  APIServerMode = true
  APIServer {
    HostIP = "127.0.0.1"
    PortNum = 3000
    Routes {
      new { Path = "/api/v1/ticket"; Methods { "POST" } }
    }
    CORS { EnableCORS = true; AllowOrigins { "http://localhost:8080" } }
  }
  AgentSettings {
    Timezone = "Etc/UTC"
    Models { "llama3.2:1b" }
    OllamaImageTag = "0.6.8"
  }
}

pkl

// resources/fetch_data.pkl
ActionID = "httpFetchResource"
Name = "CRM Fetch"
Description = "Fetches ticket data via CRM API."
run {
  RestrictToHTTPMethods { "POST" }
  RestrictToRoutes { "/api/v1/ticket" }
  PreflightCheck {
    Validations { "@(request.data().ticket_id)" != "" }
  }
  HTTPClient {
    Method = "GET"
    Url = "https://crm.example.com/api/ticket/@(request.data().ticket_id)"
    Headers { ["Authorization"] = "Bearer @(session.getRecord('crm_token'))" }
    TimeoutDuration = 30.s
  }
}

pkl

// resources/llm.pkl
ActionID = "llmResource"
Name = "LLM Ticket Response"
Description = "Generates responses for customer tickets."
Requires { "httpFetchResource" }
run {
  RestrictToHTTPMethods { "POST" }
  RestrictToRoutes { "/api/v1/ticket" }
  Chat {
    Model = "llama3.2:1b"
    Role = "assistant"
    Prompt = "Provide a professional response to the customer query: @(request.data().query)"
    Scenario {
      new { Role = "system"; Prompt = "You are a customer support assistant. Be polite and concise." }
      new { Role = "system"; Prompt = "Ticket data: @(client.responseBody("httpFetchResource"))" }
    }
    JSONResponse = true
    JSONResponseKeys { "response_text" }
    TimeoutDuration = 60.s
  }
}

pkl

// resources/response.pkl
ActionID = "responseResource"
Name = "API Response"
Description = "Returns ticket resolution response."
Requires { "llmResource" }
run {
  RestrictToHTTPMethods { "POST" }
  RestrictToRoutes { "/api/v1/ticket" }
  APIResponse {
    Success = true
    Response {
      Data { "@(llm.response('llmResource'))" }
    }
    Meta { Headers { ["Content-Type"] = "application/json" } }
  }
}

🐳 Dockerized full-stack AI apps

Build applications with batteries included for seamless development and deployment, as detailed in the AI agent settings.

pkl

# Creating a Docker image of the kdeps AI agent is easy!
# First, package the AI agent project.
$ kdeps package tickets-ai/
INFO kdeps package created package-file=tickets-ai-1.0.0.kdeps
# Then build a docker image and run.
$ kdeps run tickets-ai-1.0.0.kdeps
# It also creates a Docker compose configuration file.

pkl

# docker-compose.yml
version: '3.8'
services:
  kdeps-tickets-ai-cpu:
    image: kdeps-tickets-ai:1.0.0
    ports:
      - "127.0.0.1:3000"
    restart: on-failure
    volumes:
      - ollama:/root/.ollama
      - kdeps:/agent/volume
volumes:
  ollama:
    external:
      name: ollama
  kdeps:
    external:
      name: kdeps

🖼️ Support for vision or multimodal LLMs

Process text, images, and other data types in a single workflow with vision or multimodal LLMs.

pkl

// workflow.pkl
Name = "visualTicketAnalyzer"
Description = "Analyzes images in support tickets for defects using a vision model."
Version = "1.0.0"
TargetActionID = "responseResource"
Settings {
  APIServerMode = true
  APIServer {
    HostIP = "127.0.0.1"
    PortNum = 3000
    Routes {
      new { Path = "/api/v1/visual-ticket"; Methods { "POST" } }
    }
    CORS { EnableCORS = true; AllowOrigins { "http://localhost:8080" } }
  }
  AgentSettings {
    Timezone = "Etc/UTC"
    Models { "llama3.2-vision" }
    OllamaImageTag = "0.6.8"
  }
}

pkl

// resources/fetch_data.pkl
ActionID = "httpFetchResource"
Name = "CRM Fetch"
Description = "Fetches ticket data via CRM API."
run {
  RestrictToHTTPMethods { "POST" }
  RestrictToRoutes { "/api/v1/ticket" }
  PreflightCheck {
    Validations { "@(request.data().ticket_id)" != "" }
  }
  HTTPClient {
    Method = "GET"
    Url = "https://crm.example.com/api/ticket/@(request.data().ticket_id)"
    Headers { ["Authorization"] = "Bearer @(session.getRecord('crm_token'))" }
    TimeoutDuration = 30.s
  }
}

pkl

// resources/llm.pkl
ActionID = "llmResource"
Name = "Visual Defect Analyzer"
Description = "Analyzes ticket images for defects."
Requires { "httpFetchResource" }
run {
  RestrictToHTTPMethods { "POST" }
  RestrictToRoutes { "/api/v1/visual-ticket" }
  PreflightCheck {
    Validations { "@(request.filecount())" > 0 }
  }
  Chat {
    Model = "llama3.2-vision"
    Role = "assistant"
    Prompt = "Analyze the image for product defects and describe any issues found."
    Files { "@(request.files()[0])" }
    Scenario {
      new { Role = "system"; Prompt = "You are a support assistant specializing in visual defect detection." }
      new { Role = "system"; Prompt = "Ticket data: @(client.responseBody("httpFetchResource"))" }
    }
    JSONResponse = true
    JSONResponseKeys { "defect_description"; "severity" }
    TimeoutDuration = 60.s
  }
}

pkl

// resources/response.pkl
ActionID = "responseResource"
Name = "API Response"
Description = "Returns defect analysis result."
Requires { "llmResource" }
run {
  RestrictToHTTPMethods { "POST" }
  RestrictToRoutes { "/api/v1/visual-ticket" }
  APIResponse {
    Success = true
    Response {
      Data { "@(llm.response('llmResource'))" }
    }
    Meta { Headers { ["Content-Type"] = "application/json" } }
  }
}

🔌 Create custom AI APIs

Serve open-source LLMs through custom AI APIs for robust AI-driven applications.

🌐 Pair APIs with frontend apps

Integrate with frontend apps like Streamlit, NodeJS, and more for interactive AI-driven user interfaces, as outlined in web server settings.

pkl

// workflow.pkl
Name = "frontendAIApp"
Description = "Pairs an AI API with a Streamlit frontend for text summarization."
Version = "1.0.0"
TargetActionID = "responseResource"
Settings {
  APIServerMode = true
  WebServerMode = true
  APIServer {
    HostIP = "127.0.0.1"
    PortNum = 3000
    Routes {
      new { Path = "/api/v1/summarize"; Methods { "POST" } }
    }
  }
  WebServer {
    HostIP = "127.0.0.1"
    PortNum = 8501
    Routes {
      new {
        Path = "/app"
        PublicPath = "/fe/1.0.0/web/"
        ServerType = "app"
        AppPort = 8501
        Command = "streamlit run app.py"
      }
    }
  }
  AgentSettings {
    Timezone = "Etc/UTC"
    PythonPackages { "streamlit" }
    Models { "llama3.2:1b" }
    OllamaImageTag = "0.6.8"
  }
}

pkl

// data/fe/web/app.py (Streamlit frontend)
import streamlit as st
import requests

st.title("Text Summarizer")
text = st.text_area("Enter text to summarize")
if st.button("Summarize"):
  response = requests.post("http://localhost:3000/api/v1/summarize", json={"text": text})
  if response.ok:
    st.write(response.json()['response']['data']['summary'])
  else:
    st.error("Error summarizing text")

pkl

// resources/llm.pkl
ActionID = "llmResource"
Name = "Text Summarizer"
Description = "Summarizes input text using an LLM."
run {
  RestrictToHTTPMethods { "POST" }
  RestrictToRoutes { "/api/v1/summarize" }
  Chat {
    Model = "llama3.2:1b"
    Role = "assistant"
    Prompt = "Summarize this text in 50 words or less: @(request.data().text)"
    JSONResponse = true
    JSONResponseKeys { "summary" }
    TimeoutDuration = 60.s
  }
}

🛠️ Let LLMs run tools automatically (script-based)

Enhance functionality through scripts and sequential tool pipelines with external tools and chained tool workflows. Scripts can also call external systems via adapters (e.g., an MCP server or Google A2A) when needed.

pkl

// workflow.pkl
Name = "toolChainingAgent"
Description = "Uses LLM to query a database and generate a report via tools."
Version = "1.0.0"
TargetActionID = "responseResource"
Settings {
  APIServerMode = true
  APIServer {
    HostIP = "127.0.0.1"
    PortNum = 3000
    Routes {
      new { Path = "/api/v1/report"; Methods { "POST" } }
    }
  }
  AgentSettings {
    Timezone = "Etc/UTC"
    Models { "llama3.2:1b" }
    OllamaImageTag = "0.6.8"
  }
}

pkl

// resources/llm.pkl
ActionID = "llmResource"
Name = "Report Generator"
Description = "Generates a report using a database query tool."
run {
  RestrictToHTTPMethods { "POST" }
  RestrictToRoutes { "/api/v1/report" }
  Chat {
    Model = "llama3.2:1b"
    Role = "assistant"
    Prompt = "Generate a sales report based on database query results. Date range: @(request.params("date_range"))"
    Tools {
      new {
        Name = "query_sales_db"
        Script = "@(data.filepath('tools/1.0.0', 'query_sales.py'))"
        Description = "Queries the sales database for recent transactions"
        Parameters {
          ["date_range"] { Required = true; Type = "string"; Description = "Date range for query (e.g., '2025-01-01:2025-05-01')" }
        }
      }
    }
    JSONResponse = true
    JSONResponseKeys { "report" }
    TimeoutDuration = 60.s
  }
}

pkl

// data/tools/query_sales.py
import sqlite3
import sys

def query_sales(date_range):
  start, end = date_range.split(':')
  conn = sqlite3.connect('sales.db')
  cursor = conn.execute("SELECT * FROM transactions WHERE date BETWEEN ? AND ?", (start, end))
  results = cursor.fetchall()
  conn.close()
  return results

print(query_sales(sys.argv[1]))

Additional Features

📈 Context-aware RAG workflows

Enable accurate, knowledge-intensive tasks with RAG workflows.

📊 Generate structured outputs

Create consistent, machine-readable responses from LLMs, as described in the chat block documentation.

pkl

// workflow.pkl
Name = "structuredOutputAgent"
Description = "Generates structured JSON responses from LLM."
Version = "1.0.0"
TargetActionID = "responseResource"
Settings {
  APIServerMode = true
  APIServer {
    HostIP = "127.0.0.1"
    PortNum = 3000
    Routes {
      new { Path = "/api/v1/structured"; Methods { "POST" } }
    }
  }
  AgentSettings {
    Timezone = "Etc/UTC"
    Models { "llama3.2:1b" }
    OllamaImageTag = "0.6.8"
  }
}

pkl

// resources/llm.pkl
ActionID = "llmResource"
Name = "Structured Response Generator"
Description = "Generates structured JSON output."
run {
  RestrictToHTTPMethods { "POST" }
  RestrictToRoutes { "/api/v1/structured" }
  Chat {
    Model = "llama3.2:1b"
    Role = "assistant"
    Prompt = "Analyze this text and return a structured response: @(request.data().text)"
    JSONResponse = true
    JSONResponseKeys { "summary"; "keywords" }
    TimeoutDuration = 60.s
  }
}

🔄 Items iteration

Iterate over multiple items in a resource to process them sequentially, using items iteration with `item.current()`, `item.prev()`, and `item.next()`.

pkl

// workflow.pkl
Name = "mtvScenarioGenerator"
Description = "Generates MTV video scenarios based on song lyrics."
Version = "1.0.0"
TargetActionID = "responseResource"
Settings {
  APIServerMode = true
  APIServer {
    HostIP = "127.0.0.1"
    PortNum = 3000
    Routes {
      new { Path = "/api/v1/mtv-scenarios"; Methods { "GET" } }
    }
    CORS { EnableCORS = true; AllowOrigins { "http://localhost:8080" } }
  }
  AgentSettings {
    Timezone = "Etc/UTC"
    Models { "llama3.2:1b" }
    OllamaImageTag = "0.6.8"
  }
}

pkl

// resources/llm.pkl
ActionID = "llmResource"
Name = "MTV Scenario Generator"
Description = "Generates MTV video scenarios for song lyrics."
Items {
  "A long, long time ago"
  "I can still remember"
  "How that music used to make me smile"
  "And I knew if I had my chance"
}
run {
  RestrictToHTTPMethods { "GET" }
  RestrictToRoutes { "/api/v1/mtv-scenarios" }
  SkipCondition {
    "@(item.current())" == "And I knew if I had my chance" // Skip this lyric
  }
  Chat {
    Model = "llama3.2:1b"
    Role = "assistant"
    Prompt = """
    Based on the lyric @(item.current()) from the song "American Pie," generate a suitable scenario for an MTV music video. The scenario should include a vivid setting, key visual elements, and a mood that matches the lyric's tone.
    """
    Scenario {
      new { Role = "system"; Prompt = "You are a creative director specializing in music video production." }
    }
    JSONResponse = true
    JSONResponseKeys { "setting"; "visual_elements"; "mood" }
    TimeoutDuration = 60.s
  }
}

pkl

// resources/response.pkl
ActionID = "responseResource"
Name = "API Response"
Description = "Returns MTV video scenarios."
Requires { "llmResource" }
run {
  RestrictToHTTPMethods { "GET" }
  RestrictToRoutes { "/api/v1/mtv-scenarios" }
  APIResponse {
    Success = true
    Response {
      Data { "@(llm.response('llmResource'))" }
    }
    Meta { Headers { ["Content-Type"] = "application/json" } }
  }
}

🤖 Leverage multiple open-source LLMs

Use LLMs from Ollama and Huggingface for diverse AI capabilities.

pkl

// workflow.pkl
Models {
  "tinydolphin"
  "llama3.3"
  "llama3.2-vision"
  "llama3.2:1b"
  "mistral"
  "gemma"
  "mistral"
}

🗂️ Upload documents or files

Process documents for LLM analysis, ideal for document analysis tasks, as shown in the file upload tutorial.

pkl

// workflow.pkl
Name = "docAnalysisAgent"
Description = "Analyzes uploaded documents with LLM."
Version = "1.0.0"
TargetActionID = "responseResource"
Settings {
  APIServerMode = true
  APIServer {
    HostIP = "127.0.0.1"
    PortNum = 3000
    Routes {
      new { Path = "/api/v1/doc-analyze"; Methods { "POST" } }
    }
  }
  AgentSettings {
    Timezone = "Etc/UTC"
    Models { "llama3.2-vision" }
    OllamaImageTag = "0.6.8"
  }
}

pkl

// resources/llm.pkl
ActionID = "llmResource"
Name = "Document Analyzer"
Description = "Extracts text from uploaded documents."
run {
  RestrictToHTTPMethods { "POST" }
  RestrictToRoutes { "/api/v1/doc-analyze" }
  PreflightCheck {
    Validations { "@(request.filecount())" > 0 }
  }
  Chat {
    Model = "llama3.2-vision"
    Role = "assistant"
    Prompt = "Extract key information from this document."
    Files { "@(request.files()[0])" }
    JSONResponse = true
    JSONResponseKeys { "key_info" }
    TimeoutDuration = 60.s
  }
}

🔄 Reusable AI agents

Create flexible workflows with reusable AI agents.

pkl

// workflow.pkl
Name = "docAnalysisAgent"
Description = "Analyzes uploaded documents with LLM."
Version = "1.0.0"
TargetActionID = "responseResource"
Workflows { "@ticketResolutionAgent" }
Settings {
  APIServerMode = true
  APIServer {
    HostIP = "127.0.0.1"
    PortNum = 3000
    Routes {
      new { Path = "/api/v1/doc-analyze"; Methods { "POST" } }
    }
  }
  AgentSettings {
    Timezone = "Etc/UTC"
    Models { "llama3.2-vision" }
    OllamaImageTag = "0.6.8"
  }
}

pkl

// resources/response.pkl
ActionID = "responseResource"
Name = "API Response"
Description = "Returns defect analysis result."
Requires {
  "llmResource"
  "@ticketResolutionAgent/llmResource:1.0.0"
}
run {
  RestrictToHTTPMethods { "POST" }
  RestrictToRoutes { "/api/v1/doc-analyze" }
  APIResponse {
    Success = true
    Response {
      Data {
        "@(llm.response("llmResource"))"
        "@(llm.response('@ticketResolutionAgent/llmResource:1.0.0'))"
      }
    }
    Meta { Headers { ["Content-Type"] = "application/json" } }
  }
}

🐍 Execute Python in isolated environments

Run Python code securely using Anaconda in isolated environments.

pkl

// resources/python.pkl
ActionID = "pythonResource"
Name = "Data Formatter"
Description = "Formats extracted data for storage."
run {
  RestrictToHTTPMethods { "POST" }
  RestrictToRoutes { "/api/v1/scan-document" }
  Python {
    Script = """
import pandas as pd

def format_data(data):
  df = pd.DataFrame([data])
  return df.to_json()

print(format_data(@(llm.response('llmResource'))))
"""
    TimeoutDuration = 60.s
  }
}

🌍 Make API calls

Perform API calls directly from configuration, as detailed in the client documentation.

pkl

// resources/http_client.pkl
ActionID = "httpResource"
Name = "DMS Submission"
Description = "Submits extracted data to document management system."
run {
  RestrictToHTTPMethods { "POST" }
  RestrictToRoutes { "/api/v1/scan-document" }
  HTTPClient {
    Method = "POST"
    Url = "https://dms.example.com/api/documents"
    Data { "@(python.stdout('pythonResource'))" }
    Headers { ["Authorization"] = "Bearer @(session.getRecord('dms_token'))" }
    TimeoutDuration = 30.s
  }
}

🚀 Run in Lambda or API mode

Operate in Lambda mode or API mode for flexible deployment.

✅ Built-in validations and checks

Utilize API request validations, custom validation checks, and skip conditions for robust workflows.

pkl

RestrictToHTTPMethods { "POST" }
RestrictToRoutes { "/api/v1/scan-document" }
PreflightCheck {
  Validations { "@(request.filetype('document'))" == "image/jpeg" }
}
SkipCondition { "@(request.data().query.length)" < 5 }

📁 Serve static websites or reverse-proxied apps

Host static websites or reverse-proxied apps directly.

pkl

// workflow.pkl
Name = "frontendAIApp"
Description = "Pairs an AI API with a Streamlit frontend for text summarization."
Version = "1.0.0"
TargetActionID = "responseResource"
Settings {
  APIServerMode = true
  WebServerMode = true
  APIServer {
    HostIP = "127.0.0.1"
    PortNum = 3000
    Routes {
      new { Path = "/api/v1/summarize"; Methods { "POST" } }
    }
  }
  WebServer {
    HostIP = "127.0.0.1"
    PortNum = 8501
    Routes {
      new {
        Path = "/app"
        ServerType = "app"
        AppPort = 8501
        Command = "streamlit run app.py"
      }
    }
  }
  AgentSettings {
    Timezone = "Etc/UTC"
    PythonPackages { "streamlit" }
    Models { "llama3.2:1b" }
    OllamaImageTag = "0.6.8"
  }
}

💾 Manage state with memory operations

Store, retrieve, and clear persistent data using memory operations.

pkl

expr {
  "@(memory.setRecord('user_data', request.data().data))"
}
local user_data = "@(memory.getRecord('user_data'))"

🔒 Configure CORS rules

Set CORS rules directly in the workflow for secure API access.

pkl

// workflow.pkl
CORS {
  EnableCORS = true
  AllowOrigins { "https://example.com" }
  AllowMethods { "GET"; "POST" }
}

🛡️ Set trusted proxies

Enhance API and frontend security with trusted proxies.

pkl

// workflow.pkl
APIServerMode = true
APIServer {
  HostIP = "127.0.0.1"
  PortNum = 3000
  Routes {
    new { Path = "/api/v1/proxy"; Methods { "GET" } }
  }
  TrustedProxies { "192.168.1.1"; "10.0.0.0/8" }
}

🖥️ Run shell scripts

Execute shell scripts seamlessly within workflows.

pkl

// resources/exec.pkl
ActionID = "execResource"
Name = "Shell Script Runner"
Description = "Runs a shell script."
run {
  Exec {
    Command = """
echo "Processing request at $(date)"
"""
    TimeoutDuration = 60.s
  }
}

📦 Install Ubuntu packages

Install Ubuntu packages via configuration for customized environments.

pkl

// workflow.pkl
AgentSettings {
  Timezone = "Etc/UTC"
  Packages {
    "tesseract-ocr"
    "poppler-utils"
    "npm"
    "ffmpeg"
  }
  OllamaImageTag = "0.6.8"
}

📜 Define Ubuntu repositories or PPAs

Configure Ubuntu repositories or PPAs for additional package sources.

pkl

// workflow.pkl
Repositories {
  "ppa:alex-p/tesseract-ocr-devel"
}

⚡ Written in high-performance Golang

Benefit from the speed and efficiency of Golang for high-performance applications.

📥 Easy to install

Install and use KDeps with a single command, as outlined in the installation guide.

shell

# On macOS
brew install kdeps/tap/kdeps
# Windows, Linux, and macOS
curl -LsSf https://raw.githubusercontent.com/kdeps/kdeps/refs/heads/main/install.sh | sh

Getting Started

Ready to explore KDeps? Install it with a single command: Installation Guide.

Check out practical examples to jumpstart your projects.

📋 Whitepaper

For a comprehensive technical overview of KDeps, including architecture, use cases, and competitive analysis, read our KDeps Whitepaper.

The whitepaper covers:

Architecture Overview: Detailed breakdown of KDeps' modular design
Core Components: Workflow engine, resource system, and dependency resolver
Technical Implementation: Technology stack and performance characteristics
Use Cases: Real-world applications and implementation examples
Competitive Analysis: Comparison with existing AI development platforms
Future Roadmap: Development plans and strategic vision

Workflow

API Server Settings

Web Server Settings

Web Server Routes

AI Agent Settings

Resource Functions

Global Functions

About the name

Why Offline-First?

Key Features

Additional Features

Getting Started

📋 Whitepaper

API Server Settings

Web Server Settings

Web Server Routes

AI Agent Settings

About the name ​

Why Offline-First? ​

Key Features ​

Additional Features ​

Getting Started ​

📋 Whitepaper ​

About the name

Why Offline-First?

Key Features

Additional Features

Getting Started

📋 Whitepaper