Getting Started

This tutorial walks you through building a complete provider from an empty directory to a deployed, usable resource type. You will create a provider that manages JSON configuration files.

What You’ll Build

A jsonstore provider with a config resource that:

Creates JSON configuration files
Updates file contents when configuration changes
Deletes files on resource removal
Reports whether its file exists and what it holds
Exposes file path and content hash as outputs

This example uses local files to keep things simple. The same patterns apply when integrating with cloud APIs, databases, or any external service.

Prerequisites

Before starting, ensure you have:

Python 3.13+ installed
uv package manager (install instructions)
Pragmatiks CLI authenticated (pragma auth login)

Verify your setup:

uv --version
pragma auth whoami

Expected output:

uv 0.5.14
Logged in as your-email@example.com

Step 1: Initialize the Project

Create a new provider project using the CLI:

pragma providers init jsonstore
cd jsonstore-provider

The command copies the provider template, asking for the display name, description, and author unless you pass --defaults. It opens and closes with:

Creating provider project: jsonstore-provider
  Template: gh:pragmatiks/pragma-providers

Created provider project: jsonstore-provider

Next steps:
  cd jsonstore-provider
  uv sync

Edit src/jsonstore_provider/resources/ to add your resources.

To update this project when the template changes:
  copier update

When ready to publish a version:
  pragma providers publish

Install dependencies:

uv sync

Your project structure:

jsonstore-provider/
├── pyproject.toml
├── README.md
└── src/jsonstore_provider/
    ├── __init__.py
    └── resources/
        ├── __init__.py
        └── example.py

Step 2: Define the Resource

Replace the example resource with your JSON config resource. Open src/jsonstore_provider/resources/example.py and replace the contents:

"""JSON configuration file resource."""

import asyncio
import hashlib
import json
from pathlib import Path
from typing import Any

from pragma_sdk import Config, Field, ImmutableField, Outputs, Resource


class ConfigFileConfig(Config):
    """Configuration for a JSON config file.

    Attributes:
        filename: Name of the JSON file. Immutable, because the file is located by its path.
        directory: Directory holding the file. Immutable, because the file is located by its path.
        data: JSON-serializable data to write to the file.
    """

    filename: ImmutableField[str]
    directory: ImmutableField[str] = "/tmp/jsonstore"
    data: Field[dict[str, Any]]


class ConfigFileOutputs(Outputs):
    """Outputs from JSON config file creation.

    Attributes:
        file_path: Full path to the file.
        content_hash: SHA-256 hash of the file contents.
        size_bytes: Size of the file in bytes.
    """

    file_path: str
    content_hash: str
    size_bytes: int


class ConfigFile(Resource[ConfigFileConfig, ConfigFileOutputs]):
    """JSON configuration file resource.

    Owns one JSON file, located by ``directory`` and ``filename``.
    Demonstrates the provider pattern without external dependencies.
    """

    def build_path(self) -> Path:
        """Build the full file path from config.

        Returns:
            Path of the file this resource owns.
        """
        return Path(self.config.directory) / self.config.filename

    def build_outputs(self, content: str) -> ConfigFileOutputs:
        """Build outputs for the given file content.

        Args:
            content: JSON text stored in the file.

        Returns:
            Outputs with file path, content hash, and size.
        """
        encoded = content.encode()
        return ConfigFileOutputs(
            file_path=str(self.build_path()),
            content_hash=hashlib.sha256(encoded).hexdigest(),
            size_bytes=len(encoded),
        )

    async def write_file(self) -> ConfigFileOutputs:
        """Write ``config.data`` to the file, creating its directory.

        Returns:
            Outputs for the written content.
        """
        path = self.build_path()
        content = json.dumps(self.config.data, indent=2)
        await asyncio.to_thread(path.parent.mkdir, parents=True, exist_ok=True)
        await asyncio.to_thread(path.write_text, content)
        return self.build_outputs(content)

    async def on_create(self) -> ConfigFileOutputs:
        """Create the JSON config file.

        Returns:
            Outputs with file path, content hash, and size.
        """
        return await self.write_file()

    async def on_observe(self) -> ConfigFileOutputs | None:
        """Read the JSON config file this resource owns.

        Returns:
            Outputs for the file's current content, or ``None`` when the file does not exist.
        """
        try:
            content = await asyncio.to_thread(self.build_path().read_text)
        except FileNotFoundError:
            return None
        return self.build_outputs(content)

    async def on_update(self, previous_config: ConfigFileConfig | None) -> ConfigFileOutputs:
        """Rewrite the JSON config file with the current data.

        The path never changes: ``filename`` and ``directory`` are immutable, so the
        platform refuses a change to either and the file is rewritten in place.

        Args:
            previous_config: Configuration last applied, or ``None`` when the file
                exists but the platform holds no prior configuration. The full
                content is written either way.

        Returns:
            Outputs with the new hash and size.
        """
        return await self.write_file()

    async def on_delete(self) -> None:
        """Delete the JSON config file.

        Succeeds when the file is already gone.
        """
        await asyncio.to_thread(self.build_path().unlink, missing_ok=True)

Step 3: Register the Resource

Update src/jsonstore_provider/resources/__init__.py to export your resource:

"""Resource definitions for jsonstore provider."""

from jsonstore_provider.resources.example import (
    ConfigFile,
    ConfigFileConfig,
    ConfigFileOutputs,
)

__all__ = [
    "ConfigFile",
    "ConfigFileConfig",
    "ConfigFileOutputs",
]

Update src/jsonstore_provider/__init__.py to register the resource with the provider:

"""JSON store provider for Pragmatiks."""

from pragma_sdk import Provider

from jsonstore_provider.resources import (
    ConfigFile,
    ConfigFileConfig,
    ConfigFileOutputs,
)

jsonstore = Provider()

jsonstore.resource("config")(ConfigFile)

__all__ = [
    "jsonstore",
    "ConfigFile",
    "ConfigFileConfig",
    "ConfigFileOutputs",
]

Step 4: Publish and Install the Provider

Publish a version of your provider, then install it in your organization:

pragma providers publish
pragma providers install <org>/jsonstore

publish builds the wheel with uv build, extracts the resource schemas, and uploads both as <org>/jsonstore version 0.1.0, where <org> is your organization’s slug. Published versions are immutable, so bump version in pyproject.toml before publishing again. install queues the provider for your organization, and the platform deploys it. Check the deployment with:

pragma providers status <org>/jsonstore

Step 5: Create a Resource

Now users can create resources using your provider. Create a file my-config.yaml:

provider: jsonstore
resource: config
name: my-app-settings
config:
  filename: settings.json
  directory: /tmp/myapp
  data:
    app_name: "My Application"
    max_connections: 100
    features:
      - logging
      - metrics

Apply it:

pragma resources apply my-config.yaml

Expected output:

Applying resources...

  jsonstore/config/my-app-settings
    Status: created
    Outputs:
      file_path: /tmp/myapp/settings.json
      content_hash: a1b2c3d4e5f6...
      size_bytes: 127

1 resource(s) applied successfully

Check the resource status:

pragma resources get jsonstore/config my-app-settings

Summary

You’ve built a complete provider that:

Defines Config and Outputs schemas with validation
Implements idempotent lifecycle methods (create, observe, update, delete)
Publishes to the platform with pragma providers publish and installs with pragma providers install

The same patterns apply to any integration. Replace the file operations with API calls to cloud services, databases, or internal tools.

Next Steps

Config and Outputs

Design schemas with validation, defaults, and dependencies.

Lifecycle Methods

Deep dive into handlers, subresources, and idempotency.

CLI Reference

Full reference for init, publish, install, and deploy commands.

Concepts

Resource Catalog

Agno (AI Agents)

GCP

Kubernetes

Building Providers

Getting Started

What You’ll Build

Prerequisites

Step 1: Initialize the Project

Step 2: Define the Resource

Step 3: Register the Resource

Step 4: Publish and Install the Provider

Step 5: Create a Resource

Summary

Next Steps

Config and Outputs

Lifecycle Methods

CLI Reference

​What You’ll Build

​Prerequisites

​Step 1: Initialize the Project

​Step 2: Define the Resource

​Step 3: Register the Resource

​Step 4: Publish and Install the Provider

​Step 5: Create a Resource

​Summary

​Next Steps

Config and Outputs

Lifecycle Methods

CLI Reference

What You’ll Build

Prerequisites

Step 1: Initialize the Project

Step 2: Define the Resource

Step 3: Register the Resource

Step 4: Publish and Install the Provider

Step 5: Create a Resource

Summary

Next Steps