kdeps-templates-api-service

version: 1.0.0
files:
    README.md.j2: |
        # {{ name }}

        {{ description }}

        ## Quick Start

        1. Run in development mode:
           ```bash
           export KDEPS_API_AUTH_TOKEN=dev-token   # the API server will not start without a token
           kdeps run workflow.yaml --dev
           ```

        2. Test the API:
           ```bash
           curl -X POST http://localhost:{{ port }}/api/v1/chat \
             -H "Authorization: Bearer $KDEPS_API_AUTH_TOKEN" \
             -H "Content-Type: application/json" \
             -d '{"q": "Hello!"}'
           ```

        ## Project Structure

        ```
        {{ name }}/
        ├── workflow.yaml        # Workflow config: API server, routing, target resource
        ├── resources/
        │   ├── llm.yaml         # LLM resource: validates input, calls the model
        │   └── response.yaml    # Response resource: formats the API response
        └── README.md
        ```

        ## API Endpoint

        ### POST /api/v1/chat

        **Request:**
        ```json
        { "q": "Hello!" }
        ```

        **Response:**
        ```json
        {
          "success": true,
          "response": {
            "answer": "..."
          }
        }
        ```

        ## Deployment

        ```bash
        kdeps package .
        kdeps build {{ name }}-{{ version }}.kdeps
        docker run -p {{ port }}:{{ port }} {{ name }}:{{ version }}
        ```
    env.example.j2: |
        # .env — copy to .env and fill in the values you need.
        # kdeps reads this file at startup. Variables are also available inside
        # resource YAML files via the env('VAR') expression.
        #
        # Only uncomment lines you actually need — unset vars fall back to
        # kdeps built-in defaults or ~/.kdeps/config.yaml values.

        # ---------------------------------------------------------------------------
        # API server
        # ---------------------------------------------------------------------------

        # Port the API server listens on. Must match portNum in workflow.yaml.
        API_PORT={{ port }}

        # Override the bind address (default: 0.0.0.0). Use 127.0.0.1 to restrict
        # to loopback only.
        # KDEPS_BIND_HOST=0.0.0.0

        # Required when apiServer is enabled. Bearer token on every request except /health.
        # KDEPS_API_AUTH_TOKEN=change-me

        # Bearer token required for write operations on the management API
        # (/management/...). Leave unset to disable management endpoints.
        # KDEPS_MANAGEMENT_TOKEN=change-me

        # ---------------------------------------------------------------------------
        # LLM backend
        # ---------------------------------------------------------------------------

        # Backend to use: file | ollama | openai | anthropic | groq | mistral | cohere |
        #                 deepseek | google | together | openrouter | perplexity
        # Default is "file": models run as local llamafiles, no server install needed.
        # KDEPS_DEFAULT_BACKEND=file

        # Base URL for the LLM API (overrides the backend default endpoint).
        # The file backend picks its own local port — set this only to target an
        # external OpenAI-compatible server instead of a local llamafile.
        # KDEPS_LLM_BASE_URL=http://localhost:11434

        # Ollama host (used when backend=ollama).
        # OLLAMA_HOST=http://localhost:11434

        # Comma-separated list of models to load or make available.
        # KDEPS_LLM_MODELS=llama3.2:1b

        # JSON blob for the full LLM router config (advanced — usually set by kdeps
        # from config.yaml; override here only if you need fine-grained routing).
        # KDEPS_LLM_ROUTER=

        # ---------------------------------------------------------------------------
        # LLM API keys — set the key for whichever backend you use
        # ---------------------------------------------------------------------------

        # OPENAI_API_KEY=sk-...
        # ANTHROPIC_API_KEY=sk-ant-...
        # GROQ_API_KEY=gsk_...
        # MISTRAL_API_KEY=...
        # COHERE_API_KEY=...
        # DEEPSEEK_API_KEY=...
        # GOOGLE_API_KEY=...
        # TOGETHER_API_KEY=...
        # OPENROUTER_API_KEY=sk-or-...
        # PERPLEXITY_API_KEY=pplx-...

        # ---------------------------------------------------------------------------
        # Chat resource defaults (resource_defaults.chat in config.yaml)
        # ---------------------------------------------------------------------------

        # KDEPS_CHAT_TIMEOUT=60s
        # KDEPS_CHAT_CONTEXT_LENGTH=4096
        # KDEPS_CHAT_STREAMING=false
        # KDEPS_CHAT_TEMPERATURE=0.7
        # KDEPS_CHAT_MAX_TOKENS=4096
        # KDEPS_CHAT_TOP_P=0.9
        # KDEPS_CHAT_FREQUENCY_PENALTY=0.0
        # KDEPS_CHAT_PRESENCE_PENALTY=0.0
        # KDEPS_CHAT_MAX_OUTPUT_BYTES=1048576

        # ---------------------------------------------------------------------------
        # HTTP client resource defaults
        # ---------------------------------------------------------------------------

        # KDEPS_HTTP_TIMEOUT=30s
        # KDEPS_HTTP_FOLLOW_REDIRECTS=true
        # KDEPS_HTTP_MAX_RESPONSE_BYTES=10485760
        # KDEPS_HTTP_PROXY=http://proxy:8080
        # KDEPS_HTTP_RETRY_MAX_ATTEMPTS=3
        # KDEPS_HTTP_RETRY_BACKOFF=1s
        # KDEPS_HTTP_RETRY_MAX_BACKOFF=30s
        # KDEPS_HTTP_RETRY_ON=429,503

        # ---------------------------------------------------------------------------
        # Python executor defaults
        # ---------------------------------------------------------------------------

        # KDEPS_PYTHON_TIMEOUT=60s
        # KDEPS_PYTHON_MAX_OUTPUT_BYTES=1048576
        # KDEPS_PYTHON_VERSION=3.12

        # ---------------------------------------------------------------------------
        # Shell exec resource defaults
        # ---------------------------------------------------------------------------

        # KDEPS_EXEC_TIMEOUT=30s
        # KDEPS_EXEC_MAX_OUTPUT_BYTES=1048576

        # ---------------------------------------------------------------------------
        # SQL resource defaults
        # ---------------------------------------------------------------------------

        # KDEPS_SQL_TIMEOUT=30s
        # KDEPS_SQL_MAX_ROWS=1000

        # ---------------------------------------------------------------------------
        # Error handling defaults
        # ---------------------------------------------------------------------------

        # Action when a resource fails: fail | continue | retry
        # KDEPS_ON_ERROR_ACTION=fail
        # KDEPS_ON_ERROR_MAX_RETRIES=3
        # KDEPS_ON_ERROR_RETRY_DELAY=1s

        # ---------------------------------------------------------------------------
        # Web search executor endpoints
        # ---------------------------------------------------------------------------

        # Override default search provider base URLs if you self-host or proxy them.
        # KDEPS_DDG_URL=https://api.duckduckgo.com
        # KDEPS_BRAVE_URL=https://api.search.brave.com
        # KDEPS_BING_URL=https://api.bing.microsoft.com
        # KDEPS_TAVILY_URL=https://api.tavily.com

        # ---------------------------------------------------------------------------
        # Bot input source (Telegram, Discord, etc.)
        # ---------------------------------------------------------------------------

        # Used when running kdeps with a bot input source instead of HTTP.
        # KDEPS_BOT_PLATFORM=telegram
        # KDEPS_BOT_MESSAGE=
        # KDEPS_BOT_CHAT_ID=
        # KDEPS_BOT_USER_ID=

        # ---------------------------------------------------------------------------
        # Autonomous agent mode
        # ---------------------------------------------------------------------------

        # Model and backend used by the autonomous agent loop (kdeps agent / --interactive).
        # KDEPS_AGENT_MODEL=llama3.2
        # KDEPS_AGENT_BACKEND=file
        # KDEPS_AGENT_BASE_URL=

        # ---------------------------------------------------------------------------
        # Paths
        # ---------------------------------------------------------------------------

        # Path to the kdeps config file (default: ~/.kdeps/config.yaml).
        # KDEPS_CONFIG_PATH=~/.kdeps/config.yaml

        # Directory where installed agents are stored (default: ~/.kdeps/agents/).
        # KDEPS_AGENTS_DIR=~/.kdeps/agents

        # Directory where installed components are stored (default: ~/.kdeps/components/).
        # KDEPS_COMPONENT_DIR=~/.kdeps/components

        # Directory where model files are stored (default: ~/.kdeps/models/).
        # KDEPS_MODELS_DIR=~/.kdeps/models

        # SQLite database path for the memory/embedding store.
        # KDEPS_MEMORY_DB_PATH=~/.kdeps/memory.db

        # Input file path for the file input source (also settable via --file flag).
        # KDEPS_FILE_PATH=

        # ---------------------------------------------------------------------------
        # Runtime behaviour
        # ---------------------------------------------------------------------------

        # Enable offline mode — skip network calls and model downloads.
        # KDEPS_OFFLINE_MODE=false

        # Enable debug logging.
        # KDEPS_DEBUG=false

        # Enable call-chain instrumentation tracing.
        # KDEPS_INSTRUMENT=false

        # Log format: text | json
        # KDEPS_LOG_FORMAT=text

        # Disable ANSI colour output (respected by most CLI tools).
        # NO_COLOR=
    resources/llm.yaml.j2: |
        actionId: llm
        name: LLM Chat

        validations:
          methods: [POST]
          routes: [/api/v1/chat]
          check:
            - get('q') != ''
          error:
            code: 400
            message: "'q' is required"

        chat:
          model: llama3.2:1b  # llamafile alias - auto-downloaded to ~/.kdeps/models (~1.1 GB, first run only)
          # Default backend is "file": the model runs as a local llamafile, no server install needed.
          # Quantization variants: llama3.2:1b-q6, llama3.2:1b-q8. List all: kdeps llamafile list
          # To use ollama instead: set KDEPS_DEFAULT_BACKEND=ollama and installOllama: true in workflow.yaml
          role: user
          prompt: "{% raw %}{{ get('q') }}{% endraw %}"
          timeout: 60s
    resources/response.yaml.j2: |
        actionId: response
        name: API Response
        requires:
          - llm

        validations:
          methods: [POST]
          routes: [/api/v1/chat]

        apiResponse:
          success: true
          response:
            answer: get('llm')
    workflow.yaml.j2: |
        apiVersion: kdeps.io/v1
        kind: Workflow

        metadata:
          name: {{ name }}
          description: {{ description }}
          version: "{{ version }}"
          targetActionId: response

        settings:
          apiServer:
            hostIp: "0.0.0.0"
            portNum: {{ port }}
            routes:
              - path: /api/v1/chat
                methods: [POST]