### Install Chalk Go Client

Source: https://github.com/chalk-ai/docs/blob/main/client-go.mdx

Install the Chalk Go client library using the go get command. This is the first step to integrating Chalk features into your Go application.

```bash
go get github.com/chalk-ai/chalk-go
```

--------------------------------

### Envoy Gateway Configuration Example

Source: https://github.com/chalk-ai/docs/blob/main/envoy-gateway-installation.mdx

This JSON object demonstrates a typical configuration for an Envoy Gateway in Chalk, specifying the gateway name, class, namespace, and listener settings. Ensure the 'gateway_class_name' matches your Envoy quickstart setup.

```json
{
  "gateway_name": "chalk-gateway",
  "gateway_class_name": "chalk-gateway-class",
  "namespace": "chalk-networking",
  "listeners": [
    {
      "name": "runway",
      "port": 80,
      "protocol": "HTTP",
      "allowed_routes": {
        "namespaces": {
          "from": "All"
        }
      }
    }
  ]
}
```

--------------------------------

### Install chalkpy

Source: https://github.com/chalk-ai/docs/blob/main/client-python.mdx

Install the chalkpy library using pip. This is the first step to using the Chalk Python client.

```bash
pip install chalkpy
```

--------------------------------

### Install Chalk TypeScript Client

Source: https://github.com/chalk-ai/docs/blob/main/client-typescript.mdx

Install the Chalk TypeScript client using npm or yarn.

```bash
npm install @chalk-ai/client
```

```bash
yarn add @chalk-ai/client
```

--------------------------------

### Setup RBAC for Snowflake

Source: https://github.com/chalk-ai/docs/blob/main/snowflake.mdx

Example SQL script for setting up a role with appropriate permissions for Chalk to use Snowflake as a data source. Ensure to replace placeholder values with your actual configuration.

```sql
-- Set variables
SET ROLE_NAME='CHALK_ROLE';
SET WAREHOUSE_NAME='<warehouse_name>';
SET DB_NAME='<database_name>';
SET SCHEMA_NAME='<schema_name>';
SET STAGE_NAME='<stage_name>';
SET INTEGRATION_NAME='<integration_name>';
SET USER_NAME='<chalk_user>';

-- Derived variables
SET QUALIFIED_SCHEMA_NAME=concat($DB_NAME, '.', $SCHEMA_NAME);

-- Create a role for Chalk
CREATE ROLE IF NOT EXISTS IDENTIFIER($ROLE_NAME);

-- Grant warehouse permissions
GRANT USAGE ON WAREHOUSE IDENTIFIER($WAREHOUSE_NAME) TO ROLE IDENTIFIER($ROLE_NAME);

-- Grant database/schema permissions
GRANT USAGE ON DATABASE IDENTIFIER($DB_NAME) TO ROLE IDENTIFIER($ROLE_NAME);
GRANT USAGE ON SCHEMA IDENTIFIER($QUALIFIED_SCHEMA_NAME) TO ROLE IDENTIFIER($ROLE_NAME);
GRANT SELECT ON ALL TABLES IN SCHEMA IDENTIFIER($QUALIFIED_SCHEMA_NAME) TO ROLE IDENTIFIER($ROLE_NAME);

-- Grant temporary table permissions
GRANT CREATE TEMPORARY TABLE ON SCHEMA IDENTIFIER($QUALIFIED_SCHEMA_NAME) TO ROLE IDENTIFIER($ROLE_NAME);

-- Grant storage integration and stage permissions (if using data unloading)
GRANT USAGE ON INTEGRATION IDENTIFIER($INTEGRATION_NAME) TO ROLE IDENTIFIER($ROLE_NAME);
GRANT USAGE ON STAGE IDENTIFIER($STAGE_NAME) TO ROLE IDENTIFIER($ROLE_NAME);
GRANT READ, WRITE ON STAGE IDENTIFIER($STAGE_NAME) TO ROLE IDENTIFIER($ROLE_NAME);

-- Assign role to user
GRANT ROLE IDENTIFIER($ROLE_NAME) TO USER IDENTIFIER($USER_NAME);
```

--------------------------------

### Install Project Requirements

Source: https://github.com/chalk-ai/docs/blob/main/getting-started.mdx

Install Python libraries specified in `requirements.txt` using pip. Ensure the virtual environment is activated.

```bash
$ pip3 install -r requirements.txt
```

--------------------------------

### Install Homebrew and Python 3.11

Source: https://github.com/chalk-ai/docs/blob/main/setup-guide.mdx

Use Homebrew to install Python 3.11 on your system. This is a prerequisite for setting up the Chalk environment.

```bash
# Install Homebrew
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Use Homebrew to install python3.11
$ brew install python@3.11
```

--------------------------------

### Install Chalk CLI

Source: https://github.com/chalk-ai/docs/blob/main/getting-started.mdx

Install the Chalk CLI using a curl script. This command downloads and executes the installation script.

```bash
$ curl -s -L https://api.chalk.ai/install.sh | sh
```

--------------------------------

### Install Chalk CLI in GitHub Actions

Source: https://github.com/chalk-ai/docs/blob/main/github-actions.mdx

Use this action to install the Chalk CLI. It supports specifying the version, environment, and API host for self-hosted deployments.

```yaml
- uses: chalk-ai/cli-action@v2
  with:
    client-id: ${{secrets.CHALK_CLIENT_ID}}
    client-secret: ${{secrets.CHALK_CLIENT_SECRET}}
    # Optional: Version of the Chalk CLI to install. Defaults to `latest`
    version: latest
    # Optional: Environment to use. Optional for environment-scoped tokens.
    environment: <environment id>
    # Optional: Used for Hybrid Cloud deployments
    api-host: https://custom.deployment.com/

```

--------------------------------

### Install chalk_ruby gem

Source: https://github.com/chalk-ai/docs/blob/main/client-ruby.mdx

Install the chalk_ruby gem using either bundle install after updating the Gemfile or directly using the gem install command.

```bash
bundle install
```

```bash
gem install chalk_ruby
```

--------------------------------

### Install Homebrew and Python

Source: https://github.com/chalk-ai/docs/blob/main/getting-started.mdx

Use Homebrew to install Python on macOS. Ensure Homebrew is installed first.

```bash
# Install Homebrew
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Use Homebrew to install python3
$ brew install python
```

--------------------------------

### Verify Chalk Metadata Plane Installation

Source: https://github.com/chalk-ai/docs/blob/main/helm-installation.mdx

Check the status of pods in the specified namespace to verify a successful installation. Use `kubectl describe pod <podname>` for troubleshooting.

```bash
kubectl get pods -n YOUR_METADATA_PLANE_KUBE_NAMESPACE
```

--------------------------------

### Install and Configure Chalk CLI in GitLab CI/CD

Source: https://github.com/chalk-ai/docs/blob/main/gitlab-cicd.mdx

This job installs the Chalk CLI and configures it with provided credentials. Ensure CHALK_CLIENT_ID and CHALK_CLIENT_SECRET are set as GitLab CI/CD variables. Optional variables like CHALK_VERSION, CHALK_ENVIRONMENT, and CHALK_API_HOST can also be configured.

```yaml
install-chalk:
  stage: setup
  image: ubuntu:latest
  before_script:
    - apt-get update && apt-get install -y curl
  script:
    - |
      # Download and install Chalk CLI
      CHALK_VERSION=${CHALK_VERSION:-latest}
      curl -L "https://github.com/chalk-ai/chalk/releases/${CHALK_VERSION}/download/chalk-linux" -o chalk
      chmod +x chalk
      mv chalk /usr/local/bin/chalk
    - |
      # Configure Chalk with credentials
      chalk auth --client-id "$CHALK_CLIENT_ID" --client-secret "$CHALK_CLIENT_SECRET"
      if [ -n "$CHALK_ENVIRONMENT" ]; then
        chalk config set environment "$CHALK_ENVIRONMENT"
      fi
      if [ -n "$CHALK_API_HOST" ]; then
        chalk config set api-host "$CHALK_API_HOST"
      fi
  variables:
    CHALK_CLIENT_ID: $CHALK_CLIENT_ID
    CHALK_CLIENT_SECRET: $CHALK_CLIENT_SECRET
    # Optional: Version of the Chalk CLI to install. Defaults to `latest`
    CHALK_VERSION: latest
    # Optional: Environment to use. Optional for environment-scoped tokens.
    CHALK_ENVIRONMENT: <environment id>
    # Optional: Used for Hybrid Cloud deployments
    CHALK_API_HOST: https://custom.deployment.com/
  artifacts:
    paths:
      - /usr/local/bin/chalk
    expire_in: 1 hour

```

--------------------------------

### Full Webhook Example with Validation and Processing

Source: https://github.com/chalk-ai/docs/blob/main/webhook-sources.mdx

A comprehensive example demonstrating the creation of a webhook source with Pydantic models for body and headers, and a webhook resolver function that validates headers and processes the message body to fetch data.

```python
from pydantic import BaseModel, Field
from chalk.webhooks import webhook, WebhookSource

class WebhookBody(BaseModel):
    webhook_type: str
    item_id: str


class Headers(BaseModel):
    plaid_verification: str = Field(alias="plaid-verification")

source = WebhookSource(
    id="plaid_transactions",
    body=WebhookBody,
    headers=Headers
)

@online
def get_transactions(account: Account.item_id) -> DataFrame[PlaidTransaction]:
    ...

@webhook
def fn(message: source.Message):
    verify_webhook(message.headers.plaid_verification)

    if message.body.webhook_type == "TRANSACTIONS":
        return get_transactions(message.body.item_id)
```

--------------------------------

### Verify Chalk Setup

Source: https://github.com/chalk-ai/docs/blob/main/notebook-development.mdx

Call the `whoami()` method on the ChalkClient to confirm successful authentication and retrieve user, team, and environment IDs.

```python
client.whoami()
```

--------------------------------

### Full Kafka Stream Resolver Example

Source: https://github.com/chalk-ai/docs/blob/main/streams.mdx

An example demonstrating a full stream resolver pipeline for Kafka messages. It includes Pydantic models for message parsing, a parse function to convert naive timestamps to timezone-aware datetimes, and a stream resolver to generate Chalk features.

```python
from datetime import datetime, timezone
from dateutil import parser
from pydantic import BaseModel
from chalk.features import features, Features
from chalk.streams import stream, KafkaSource

source = KafkaSource(name="...")

class KafkaMessage(BaseModel):
    id: str
    value: str
    naive_timestamp_str: str

class ParsedMessage(BaseModel):
    id: str
    value: str
    event_timestamp: datetime


@features(max_staleness="1d", etl_offline_to_online=True)
class StreamFeature:
    id: str
    value: str
    event_timestamp: datetime

def parse_message(kafka_message: KafkaMessage) -> ParsedMessage:
    parsed_timestamp: datetime = parser.parse(kafka_message.naive_timestamp_str)
    timezoned_timestamp = parsed_timestamp.replace(tzinfo=timezone.utc)
    return ParsedMessage(
        id=kafka_message.id,
        value=kafka_message.value,
        event_timestamp=timezoned_timestamp
    )

@stream(source=source, parse=parse_message)
def kafka_stream_resolver(message: ParsedMessage) -> Features[StreamFeature.id, StreamFeature.value]:
    return StreamFeature(id=message.id, value=message.value, event_timestamp=message.event_timestamp)
```

--------------------------------

### Generated Go Chalk Client

Source: https://github.com/chalk-ai/docs/blob/main/fraud-5.mdx

This is an example of a Go client library generated by Chalk. It includes feature definitions and initialization logic. Do not manually edit this file.

```go
package client

/**************************************
 Code generated by Chalk. DO NOT EDIT.
 > chalk codegen go --out ./clients/go/client.go --package client
**************************************/ 

import (
	"github.com/chalk-ai/chalk-go"
	"time"
)

var InitFeaturesErr error

type Account struct {
	Id *int64
	Title *string
	UserId *int64
	Balance *float64
	User *User
	UpdatedAt *time.Time
}

type User struct {
	Id *int64
	Name *string
	Email *string
	Account *Account
	AccountNameMatch *float64
	FicoScore *int64
	CreditScoreTags *[]any
}

var Features struct {
	Account *Account
	User *User
}

func init() {
	InitFeaturesErr = chalk.InitFeatures(&Features)
}
```

--------------------------------

### Querying Information Schema in Chalk

Source: https://github.com/chalk-ai/docs/blob/main/chalksql/what-is-chalk-sql.mdx

An example query to retrieve all available schemas within the 'chalk' catalog using the INFORMATION_SCHEMA.

```sql
-- Example query to find all schemas available in the "chalk" catalog
SELECT * FROM chalk.information_schema.schemas WHERE catalog_name = 'chalk';
```

--------------------------------

### Query User Username with Chalk CLI

Source: https://github.com/chalk-ai/docs/blob/main/fraud-tutorial.mdx

Example of using the Chalk CLI to query for a user's username, demonstrating how Chalk resolves dependencies between features.

```bash
$ chalk query --in user.id=1 --out user.username
```

--------------------------------

### Deploy Chalk Metadata Plane with Helm

Source: https://github.com/chalk-ai/docs/blob/main/helm-installation.mdx

Install the Chalk Metadata Plane using Helm, specifying the namespace and custom values files for configuration and seeding.

```bash
helm install chalk-metadata-plane oci://317932201237.dkr.ecr.us-east-1.amazonaws.com/charts/chalk-metadata-plane \
  --namespace YOUR_METADATA_PLANE_KUBE_NAMESPACE \
  --values values.yaml \
  --values seed.yaml
```

--------------------------------

### Initialize Chalk Project

Source: https://github.com/chalk-ai/docs/blob/main/getting-started.mdx

Create a new Chalk project directory and initialize project files including `chalk.yaml` and `.chalkignore` using the `chalk init` command.

```bash
$ mkdir chalk-tutorial
$ cd chalk-tutorial
$ chalk init
```

--------------------------------

### Sample chalk.yaml Configuration

Source: https://github.com/chalk-ai/docs/blob/main/configuration.mdx

This sample `chalk.yaml` demonstrates environment-specific configurations for runtime, requirements, Dockerfile, and ignore files.

```yaml
project: my-project-id

environments:
  default:
    runtime: python312
    requirements: requirements.txt
  dev:
    chalkignore: .chalkignore.dev
  prod:
    dockerfile: ./DockerfileProd
    chalkignore: .chalkignore.prod

validation:
  feature:
    metadata:
      - name: owner
        missing: error
      - name: description
        missing: warning
      - name: tags
        missing: info
  resolver:
    metadata:
      - name: owner
        missing: error
```

--------------------------------

### Initialize and Query with Chalk Python Client

Source: https://github.com/chalk-ai/docs/blob/main/client-python.mdx

Initialize the Chalk client with your credentials and environment ID, then query for specific user features. Ensure you replace placeholders with your actual credentials.

```python
from chalk import ChalkClient

# Initialize the client
client = ChalkClient(
    client_id='your-client-id',
    client_secret='your-client-secret',
    environment='your-environment-id'
)

# Query features
result = client.query(
    input={
        'user.id': 'user123'
    },
    output=[
        'user.credit_score',
        'user.account_age_days'
    ]
)

print(result)
```

--------------------------------

### Initialize Chalk Client Locally

Source: https://github.com/chalk-ai/docs/blob/main/notebook-setup.mdx

For local notebooks, Chalk automatically picks up credentials from `chalk login`. Initialize the client with default settings.

```python
from chalk.client import ChalkClient

client = ChalkClient()
```

--------------------------------

### SQL for Additional Snowflake Environment Setup

Source: https://github.com/chalk-ai/docs/blob/main/snowflake-gcp-deployment.mdx

Set up a new, unique schema, role, and user for each additional Chalk environment. This script demonstrates how to configure shared or separate databases and warehouses, and grants necessary permissions including access to the shared storage integration.

```sql
-- ═══════════════════════════════════════════════════════════════
-- ADDITIONAL ENVIRONMENT SETUP
-- Replace _STAGE with your environment suffix
-- Use suffixes that fit your use case: _DEV, _PROD, _UAT, _SANDBOX, etc.
-- ═══════════════════════════════════════════════════════════════

-- Database and Warehouse: share existing OR create new per environment
-- Option A: Share (simpler)
SET DB_NAME='CHALK';                      -- Same database (shared)
SET WAREHOUSE_NAME='CHALK_WAREHOUSE';     -- Same warehouse (shared)
-- Option B: Separate (for independent scaling/billing)
-- SET DB_NAME='CHALK_STAGE';             -- Separate database per env
-- SET WAREHOUSE_NAME='CHALK_WH_STAGE';   -- Separate warehouse per env

-- New environment-specific resources
SET SCHEMA_NAME='OFFLINE_STORE_STAGE';    -- ⚠️ MUST be unique
SET ROLE_NAME='CHALK_ROLE_STAGE';
SET USER_NAME='CHALK_USER_STAGE';

-- Create the new schema
USE DATABASE IDENTIFIER($DB_NAME);
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($SCHEMA_NAME);

-- Create a new role for this environment
CREATE ROLE IF NOT EXISTS IDENTIFIER($ROLE_NAME);
GRANT USAGE ON WAREHOUSE IDENTIFIER($WAREHOUSE_NAME) TO ROLE IDENTIFIER($ROLE_NAME);

-- Create a new user for this environment
CREATE USER IF NOT EXISTS IDENTIFIER($USER_NAME)
    RSA_PUBLIC_KEY=`<your-new-public-key-here>`
    DEFAULT_ROLE=IDENTIFIER($ROLE_NAME)
    DEFAULT_WAREHOUSE=IDENTIFIER($WAREHOUSE_NAME)
    DEFAULT_NAMESPACE=IDENTIFIER(concat($DB_NAME, '.', $SCHEMA_NAME));

-- Grant permissions
SET QUALIFIED_SCHEMA_NAME=concat($DB_NAME, '.', $SCHEMA_NAME);
GRANT OWNERSHIP ON SCHEMA IDENTIFIER($QUALIFIED_SCHEMA_NAME) TO ROLE IDENTIFIER($ROLE_NAME) REVOKE CURRENT GRANTS;
GRANT CREATE STAGE ON SCHEMA IDENTIFIER($QUALIFIED_SCHEMA_NAME) TO ROLE IDENTIFIER($ROLE_NAME);
GRANT ROLE IDENTIFIER($ROLE_NAME) TO USER IDENTIFIER($USER_NAME);

-- Grant access to the SHARED storage integration
GRANT USAGE ON INTEGRATION "gcs-integration-chalk-{organization}-offline-store-bulk-insert" TO ROLE IDENTIFIER($ROLE_NAME);
```

--------------------------------

### Schedule Resolver with Filtered Examples

Source: https://github.com/chalk-ai/docs/blob/main/resolver-cron.mdx

Schedule a resolver to run with specific arguments by providing a filter function. The filter function determines which of the default examples to run based on a condition. This example filters for balances greater than 100.

```python
def filter_examples(bank_id: User.bank_account.balance) -> bool:
    return balance > 100

@online(cron=Cron(schedule="1d", filter=filter_examples))
def fn(balance: User.bank_account.balance) -> ...
```

--------------------------------

### Initialize Blue Deployment and Set Traffic

Source: https://github.com/chalk-ai/docs/blob/main/blue-green-deployment.mdx

Tag the current deployment as 'blue' and direct 100% of traffic to it, preparing for a new 'green' deployment.

```bash
$ chalk apply --deployment-tag blue
$ chalk traffic set --tags blue=100
```

--------------------------------

### Install chalkdf

Source: https://github.com/chalk-ai/docs/blob/main/chalkdf/getting-started.mdx

Install chalkdf with the chalkpy extra using pip. Ensure you have Python 3.10-3.13 and Linux/macOS 15+.

```bash
uv pip install "chalkdf[chalkpy]"
```

--------------------------------

### Initialize Chalk Project

Source: https://github.com/chalk-ai/docs/blob/main/setup-guide.mdx

Initialize your Chalk project files, including chalk.yaml, README.md, and requirements.txt. This sets up the basic project structure.

```yaml
project: {YOUR_PROJECT_NAME}
environments:
  default:
    requirements: requirements.txt
    runtime: python312
```

--------------------------------

### Query Chalk Using Generated Go Client

Source: https://github.com/chalk-ai/docs/blob/main/fraud-5.mdx

Demonstrates how to use the generated Go feature library to query Chalk. Ensure you have imported the necessary packages and initialized the Chalk client.

```go
import (
    "github.com/chalk-ai/chalk-go"
)

// Create a new Chalk client.
client := chalk.NewClient()

// Create an empty struct to hold the results.
user := User{}

// Query Chalk, and add the results to the struct.
_, err = client.OnlineQuery(
    chalk.OnlineQueryParams{}. 
        WithInput(Features.User.Id, 1234).
        WithOutputs(
			Features.User.Id,
			Features.User.LastName,
			Features.User.FicoScore,
			Features.User.Account.Balance,
        ),
    &user,
)

// Now, you can access the properties of the
// user for which there was a matching `output`.
fmt.Println(user.Account.Balance)
```

--------------------------------

### Basic Go Client Usage

Source: https://github.com/chalk-ai/docs/blob/main/client-go.mdx

Initialize the Chalk Go client with your credentials and environment ID, then use it to query features by providing input identifiers and desired output feature names. Ensure proper error handling for client initialization and query operations.

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/chalk-ai/chalk-go"
)

func main() {
    // Initialize the client
    client, err := chalk.NewClient(
        chalk.WithClientID("your-client-id"),
        chalk.WithClientSecret("your-client-secret"),
        chalk.WithEnvironment("your-environment-id"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Query features
    result, err := client.Query(context.Background(), chalk.QueryParams{
        Inputs: map[string]interface{}{
            "user.id": "user123",
        },
        Outputs: []string{
            "user.credit_score",
            "user.account_age_days",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result)
}
```

--------------------------------

### Verify Library Installation

Source: https://github.com/chalk-ai/docs/blob/main/getting-started.mdx

Check if the `requests` library is installed by importing it in a Python interactive session. Exit the session with `exit()`.

```bash
$ python3
>>> import requests
>>> exit()
```

--------------------------------

### Deploy to Production

Source: https://context7.com/chalk-ai/docs/llms.txt

Applies the current project to the production environment using the Chalk CLI.

```bash
# Deploy to production
chalk apply
```

--------------------------------

### Snowflake Storage Integration Name Example (GCP)

Source: https://github.com/chalk-ai/docs/blob/main/snowflake-internal-setup.mdx

Example of a Snowflake Storage Integration Name for GCP when configuring Background Persistence.

```plaintext
gcs-integration-chalk-{organization}-offline-store-bulk-insert
```

--------------------------------

### Snowflake Storage Integration Name Example (AWS)

Source: https://github.com/chalk-ai/docs/blob/main/snowflake-internal-setup.mdx

Example of a Snowflake Storage Integration Name for AWS when configuring Background Persistence.

```plaintext
s3-integration-chalk-{organization}-data-bucket
```

--------------------------------

### Install chalkdf with ChalkPy

Source: https://github.com/chalk-ai/docs/blob/main/chalkdf/installation.mdx

Use this command to install chalkdf along with the chalkpy integration. Ensure you have Python 3.10-3.13 and a compatible OS (Linux/macOS 15+).

```bash
pip install "chalkdf[chalkpy]"
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/chalk-ai/docs/blob/main/getting-started.mdx

Create a Python virtual environment named `chalk-tutorial-venv` and activate it using the `source` command. Deactivate using `deactivate`.

```bash
$ python3 -m venv chalk-tutorial-venv
$ source chalk-tutorial-venv/bin/activate
```

--------------------------------

### Initiating a Training Run with Chalk Client

Source: https://github.com/chalk-ai/docs/blob/main/model_training.mdx

Starts a model training job using the Chalk client. Specify the experiment name, training function, configuration parameters, and resource requests.

```python
from chalk import ResourceRequests

# Create a training run
training_run = client.train_model(
    experiment_name="spam_model",
    train_fn=train,
    config=dict(
        lr=0.01,
        num_epochs=50,
        batch_size=32,
        dataset_name="sms_spam_dataset"
    ),
    resources=ResourceRequests(
        cpu=15,
        memory="15Gi",
        resource_group="gpu"
    )
)
```

--------------------------------

### Full Webhook Example with Pydantic Validation

Source: https://github.com/chalk-ai/docs/blob/main/webhook-sources.mdx

A comprehensive example showing the creation of a WebhookSource with Pydantic models for body and headers, and a corresponding webhook resolver.

```APIDOC
## Full Webhook Implementation Example

### Description
This example demonstrates a complete setup for a webhook integration, including Pydantic models for request validation and a resolver function to handle specific webhook types.

### Components
1.  **Pydantic Models**: Define the expected structure for request bodies and headers.
2.  **WebhookSource Initialization**: Create a `WebhookSource` instance, specifying the Pydantic models for validation.
3.  **Webhook Resolver**: Implement a function decorated with `@webhook` to process incoming messages, validate headers, and conditionally trigger downstream actions.

### Code
```python
from pydantic import BaseModel, Field
from chalk.webhooks import webhook, WebhookSource
from chalk import Account, DataFrame
from chalk.features.plaid import PlaidTransaction

# Define Pydantic models for request validation
class WebhookBody(BaseModel):
    webhook_type: str
    item_id: str

class Headers(BaseModel):
    plaid_verification: str = Field(alias="plaid-verification")

# Initialize the WebhookSource with validation models
source = WebhookSource(
    id="plaid_transactions",
    body=WebhookBody,
    headers=Headers
)

# Placeholder for a downstream function (e.g., fetching transactions)
@online
def get_transactions(account: Account.item_id) -> DataFrame[PlaidTransaction]:
    # Implementation to fetch transactions
    pass

# Define the webhook resolver function
@webhook
def fn(message: source.Message):
    # Validate webhook signature using header
    verify_webhook(message.headers.plaid_verification)

    # Process based on webhook type
    if message.body.webhook_type == "TRANSACTIONS":
        return get_transactions(message.body.item_id)

# Helper function for webhook verification (implementation not shown)
def verify_webhook(signature: str):
    # Logic to verify the webhook signature
    pass
```

### Notes
- The `Field(alias="plaid-verification")` in the `Headers` model demonstrates how to map incoming header names (which are case-insensitive and hyphenated) to Pydantic model attributes.
- The `@online` decorator is assumed to be defined elsewhere and is used here to denote a function that runs in an online environment.
- The `source.Message` type hint ensures that the `message` object passed to the resolver has the structure defined by the `WebhookSource`.
```

--------------------------------

### Create Streaming Sources

Source: https://github.com/chalk-ai/docs/blob/main/streams.mdx

Instantiate Kafka, Kinesis, or PubSub sources for streaming data ingestion. Parameters and credentials can be set in the dashboard or code.

```python
from chalk.streams import KafkaSource, KinesisSource, PubSubSource

kafka_topic = KafkaSource(name="transactions")
kinesis_topic = KinesisSource(name="transactions")
pubsub_topic = PubSubSource(name="transactions")
```

--------------------------------

### Example Metrics Database Configuration

Source: https://github.com/chalk-ai/docs/blob/main/metrics-installation.mdx

Use this JSON configuration to set up a Chalk metrics database. Ensure you replace placeholder values like backup bucket and IAM role ARN with your specific details.

```json
{
  "timescale_image": "ghcr.io/imusmanmalik/timescaledb-postgis:16-3.4-54",
  "database_name": "chalk-metrics-db",
  "database_replicas": 1,
  "storage": "200Gi",
  "namespace": "chalk-metrics",
  "request": {
    "cpu": "1",
    "memory": "500Mi"
  },
  "limit": {
    "cpu": "1",
    "memory": "500Mi"
  },
  "postgres_parameters": {
    "max_connections": "200"
  },
  "connection_pool_mode": "transaction",
  "connection_pool_replicas": 3,
  "connection_pool_max_connections": "300",
  "connection_pool_size": "40",
  "service_type": "cluster-ip",
  "backup_bucket": "s3://<your backup bucket>",
  "backup_iam_role_arn": "arn:aws:iam::<your aws account ID>:role/<your backup role name>",
  "secret_name": "chalk-metrics-uri"
}
```

--------------------------------

### Schedule Resolver with Filtered Examples by Status

Source: https://github.com/chalk-ai/docs/blob/main/resolver-cron.mdx

Another example of filtering scheduled runs. This filter function checks the bank account status, ensuring only 'opened' accounts are processed.

```python
def filter_examples(status: User.bank_account.status) -> bool:
    return status == "opened"

@online(cron=Cron(schedule="1d", filter=filter_examples))
def fn(balance: User.bank_account.balance) -> ...
```

--------------------------------

### Complex Calculation Example

Source: https://github.com/chalk-ai/docs/blob/main/static-resolver-optimization.mdx

This example shows a less optimal resolver due to complex nested logic and a loop. Loops and external function calls may not be optimized by the symbolic interpreter.

```python
import \"chalk\"

# Less optimal: Complex nested logic
@chalk.online
def complex_calculation(a: chalk.Feature.a, b: chalk.Feature.b, c: chalk.Feature.c) -> chalk.Feature.result:
    result = a
    for i in range(10):  # Loops may not optimize
        if b > i:
            result = custom_function(result, c)  # External functions may not optimize
    return result
```

--------------------------------

### Federated Query Example in Chalk SQL

Source: https://github.com/chalk-ai/docs/blob/main/chalksql/what-is-chalk-sql.mdx

This example demonstrates querying across different data sources like PostgreSQL and BigQuery using Chalk SQL, including joining and aggregation.

```sql
WITH total_spending AS (
    SELECT
        u.user_id AS user_id,
        SUM(t.amount) AS user_spending,
    FROM "my_postgres.public.user" u  -- Query against a data source named "my_postgres"
    LEFT JOIN "my_bigquery.my_dataset.transactions" t -- Query against a data source named "my_bigquery"
    ON u.user_id = t.user_id
    GROUP BY u.user_id
)
SELECT
    u.user_id AS user_id,
    u.embedding AS user_embedding,
    array_normalize(u.embedding, 2) AS l2_normalized_embedding,
    json_extract(ts.random_transaction_data, '$.timestamp') AS txn_timestamp,
    json_extract(ts.random_transaction_data, '$.metadata.country') AS country,
    ts.user_spending AS user_spending,
FROM "my_postgres.public.users" u
LEFT JOIN total_spending ts
ON u.user_id = ts.user_id

```

--------------------------------

### Install Chalk CLI in GitLab CI

Source: https://github.com/chalk-ai/docs/blob/main/gitlab-cicd.mdx

This snippet installs the Chalk CLI from a GitHub release. It ensures the CLI is executable and available in the system's PATH. Artifacts are stored for subsequent stages.

```yaml
install-chalk:
  stage: setup
  image: ubuntu:latest
  before_script:
    - apt-get update && apt-get install -y curl
  script:
    - |
      CHALK_VERSION=${CHALK_VERSION:-latest}
      curl -L "https://github.com/chalk-ai/chalk/releases/${CHALK_VERSION}/download/chalk-linux" -o chalk
      chmod +x chalk
      mv chalk /usr/local/bin/chalk
  artifacts:
    paths:
      - /usr/local/bin/chalk
    expire_in: 1 hour
```

--------------------------------

### Execute and Query Data

Source: https://github.com/chalk-ai/docs/blob/main/debugging-queries.mdx

Run a query to fetch user data and print the result. This example demonstrates how to execute a query and retrieve a specific value, useful for initial testing.

```python
data = ChalkClient().query(input={User.id: 1}, output=[User.sum_transaction_amount])

print(data.get_value(User.sum_transaction_amount))
```

--------------------------------

### Initialize Chalk Client and Load Features

Source: https://github.com/chalk-ai/docs/blob/main/what-is-chalk.mdx

Initialize the Chalk client and load production features. This is the first step for interacting with Chalk's feature store in a Python environment.

```python
from chalk.client import ChalkClient

client = ChalkClient(branch=True)
client.load_features() # load prod features with one line
```

--------------------------------

### Create a Branch Deployment using CLI

Source: https://github.com/chalk-ai/docs/blob/main/integration-tests.mdx

Use the `--branch` flag with `chalk apply` to create a branch deployment. The `--await` flag ensures the deployment is live when the command returns.

```bash
# --branch creates a branch deployment
> chalk apply --force --await --branch <branch_name>
```

--------------------------------

### Example Stream Message

Source: https://github.com/chalk-ai/docs/blob/main/native-streaming.mdx

An incoming JSON message from a stream, parsed into a Python object.

```json
{
  "id": 123,
  "name": "John Smith",
  "updated_at": 1700000000000000,
  "contact_info": {
    "phone_number": "555-555-5555",
    "email_address": "john.smith@gmail.com"
  }
}
```

--------------------------------

### Create a Basic Webhook Source

Source: https://github.com/chalk-ai/docs/blob/main/webhook-sources.mdx

Instantiate a WebhookSource with a unique ID. This is the first step in setting up a webhook to receive data.

```python
from chalk.webhooks import WebhookSource

source = WebhookSource(id="my_webhook_id")
```

--------------------------------

### Create and Run a Simple Task via CLI

Source: https://github.com/chalk-ai/docs/blob/main/tasks.mdx

Use the Chalk CLI to create a basic Python script and then execute it as a task. The CLI provides a link to view the task's progress and output in the dashboard.

```bash
echo 'print("Hello from Chalk tasks!")' > script.py
```

```bash
chalk task run script.py
```

```bash
✓ View task at: https://chalk.ai/projects/my-project/environments/prod/tasks/550e8400...
```

--------------------------------

### Query for Has-Many Relationships

Source: https://github.com/chalk-ai/docs/blob/main/marketplace-tutorial.mdx

Query for all entities in a has-many relationship. This example fetches all Reviews belonging to a specific User.

```bash
chalk query --in user.id=50 --out reviews
```

--------------------------------

### Create New Deployment and Mirror Traffic

Source: https://github.com/chalk-ai/docs/blob/main/blue-green-deployment.mdx

This sequence of commands demonstrates a lightweight approach to using mirroring. First, a new deployment is created with a tag. Then, traffic is mirrored to this new deployment, allowing for monitoring before a full promotion.

```bash
# Make the new deployment -- it won't receive any traffic yet
$ chalk apply --deployment-tag green
```

```bash
# Mirror 5% of traffic to the green deployment
$ chalk traffic set --tags blue=100,green=0 --mirror green=5
```

```bash
# Monitor the new deployment for any issues. Once you're satisfied, you can promote it to production with:
$ chalk traffic promote
```

--------------------------------

### Define Job Feature Class

Source: https://github.com/chalk-ai/docs/blob/main/feature-caching.mdx

Defines features for a Job, specifying storage behavior for start and end times.

```python
# with no max_staleness set, features in the Job feature class will by default by stored offline, but not online
@features
class Job:
    id: int

    # with no overrides, this feature will be stored offline, but not online
    driver_id: Driver.id

    # with an override for store_offline, computed feature values for start_time will not be persisted
    start_time: datetime = feature(store_offline=False)

    # with overrides for store_online and store_offline, computed feature values for end_time will be persisted
    # in the online store, but not the offline store
    end_time: datetime = feature(store_online=True, store_offline=False)
```

--------------------------------

### Project Dependencies

Source: https://github.com/chalk-ai/docs/blob/main/setup-guide.mdx

List of project dependencies for Chalk, including the chalkpy runtime. Ensure these are installed within your virtual environment.

```text
requests
chalkpy[runtime]
```

--------------------------------

### Load Chalk Features into Notebook

Source: https://github.com/chalk-ai/docs/blob/main/notebook-development.mdx

Initialize ChalkClient and use `load_features()` to display available features and load them into the notebook environment.

```python
from chalk.client import ChalkClient

client = ChalkClient()

client.load_features()
```

--------------------------------

### SQL Query Rewritten with Lookback Period

Source: https://github.com/chalk-ai/docs/blob/main/sql.mdx

Example of how Chalk rewrites a SQL query when `lookback_period` is specified in the `.incremental` method.

```sql
SELECT * FROM payments
WHERE updated_at >= (<previous_max_updated_at> - <lookback_period>)
```

--------------------------------

### Example Background Persistence Writer Configuration

Source: https://github.com/chalk-ai/docs/blob/main/background-persistence-installation.mdx

This JSON configuration defines parameters for background persistence writers, covering common specifications, API server details, Kafka and Redis settings, and specific writer configurations for metrics and results.

```json
{
  "common_persistence_specs": {
    "bus_backend": "KAFKA",
    "bus_writer_image_go": "<go bus writer image>",
    "bus_writer_image_python": "<python bus writer image>",
    "bus_writer_image_bswl": "<bswl bus writer image>",
    "namespace": "background-persistence",
    "service_account_name": "background-persistence-sa",
    "secret_client": "AWS",
    "bigquery_parquet_upload_subscription_id": "offline-store-bulk-insert-bus-1",
    "bigquery_streaming_write_subscription_id": "offline-store-streaming-insert-bus-1",
    "bigquery_streaming_write_topic": "offline-store-streaming-insert-bus-1",
    "bigquery_upload_bucket": "s3://<your data bucket>",
    "bigquery_upload_topic": "offline-store-bulk-insert-bus-1",
    "metrics_bus_subscription_id": "metrics-bus-1",
    "metrics_bus_topic_id": "metrics-bus-1",
    "result_bus_metrics_subscription_id": "result-bus-1",
    "result_bus_offline_store_subscription_id": "result-bus-1",
    "result_bus_online_store_subscription_id": "result-bus-1",
    "kafka_dlq_topic": "dlq-1",
    "operation_subscription_id": "operation-bus-1"
  },
  "api_server_host": "<your api server here>",
  "kafka_sasl_secret": "<your aws kafka auth secret here>",
  "kafka_bootstrap_servers": "<bootstrap server1>:<port>, <bootstrap server2>:<port>, ...",
  "kafka_security_protocol": "SASL_SSL",
  "kafka_sasl_mechanism": "SCRAM-SHA-512",
  "redis_is_clustered": "1",
  "snowflake_storage_integration_name": "<snowflak integration name>",
  "metadata_provider": "GRPC_SERVER",
  "writers": [
    {
      "name": "go-metrics-bus-writer",
      "bus_subscriber_type": "GO_METRICS_BUS_WRITER",
      "request": {
        "cpu": "200m",
        "memory": "512Mi"
      },
      "limit": {
        "cpu": "1",
        "memory": "512Mi"
      },
      "version": "1.0",
      "default_replica_count": 1
    },
    {
      "name": "go-result-bus-metrics-writer",
      "bus_subscriber_type": "GO_RESULT_BUS_METRICS_WRITER",
      "request": {
        "cpu": "400m",
        "memory": "1024Mi"
      },
      "limit": {
        "cpu": "1",
        "memory": "1024Mi"
      },
      "version": "1.0",
      "default_replica_count": 1
    }
  ]
}
```

--------------------------------

### Preview Database with psql

Source: https://github.com/chalk-ai/docs/blob/main/getting-started.mdx

Use the psql command-line tool to connect to a PostgreSQL database and preview its contents. Requires psql to be installed.

```bash
psql -U postgres -p 5432 -h 35.188.7.252 -d postgres
postgres=> select * from users limit 10;
```

--------------------------------

### Query PostgreSQL Data

Source: https://github.com/chalk-ai/docs/blob/main/integrations.mdx

Example of resolving user data from a PostgreSQL source. Ensure the 'postgres' source is configured in your Chalk deployment.

```sql
-- resolves: User
-- source: postgres
select
    id,
    name,
from users
```

--------------------------------

### Example Bulk Query Inputs

Source: https://github.com/chalk-ai/docs/blob/main/query-basics.mdx

Demonstrates the structure for providing input features and their corresponding values for a bulk query. Supports simple, has-one (struct), and has-many features.

```json
{
  "user.id": [1, 2],
  "user.name": ["Alice", "Bob"],
  "user.profile": [
    {"age": 30, "city": "NYC"},
    {"age": 25, "city": "SF"}
  ],
  "user.cards": [
    [{"id": "card1"}, {"id": "card2"}],
    [{"id": "card3"}]
  ]
}
```

--------------------------------

### Federated Query Example

Source: https://github.com/chalk-ai/docs/blob/main/chalksql/chalk-catalog-components.mdx

Demonstrates a federated SQL query joining data from a BigQuery source ('bq_source') and a PostgreSQL source ('pg_source').

```sql
SELECT
  bq_users.user_id AS user_id,
  bq_users.full_name AS full_name,
  pg_transactions.transaction_id AS transaction_id,
  pg_transactions.amount AS transaction_amount
FROM bq_source.my_dataset.users AS bq_users
OUTER JOIN pg.public.transactions AS pg_transactions
ON user_id = pg_transactions.user_id
```

--------------------------------

### Define Postgres and BigQuery Sources

Source: https://github.com/chalk-ai/docs/blob/main/chalksql/chalk-catalog-components.mdx

Example of defining Postgres and BigQuery data sources in Python, which will be automatically registered as catalogs in Chalk.

```python
from chalk.sql import PostgresSource
from chalk.sql import BigquerySource
pg = PostgresSource(name='pg_source')
bq = BigquerySource(name='bq_source')
```

--------------------------------

### Prepare Dataset for Prompt Evaluation

Source: https://github.com/chalk-ai/docs/blob/main/prompts.mdx

Create a labeled dataset for prompt evaluation using pandas and the Chalk client. This dataset serves as the ground truth for assessing prompt performance.

```python
import pandas as pd

sentiment_df = pd.read_csv("sentiment.csv")
sentiment_ds = chalk_client.create_dataset(
    input=sentiment_df,
    dataset_name="sentiment_gt",
)
sentiment_ds.to_pandas()
```

--------------------------------

### Initialize and Query with Chalk Ruby Client

Source: https://github.com/chalk-ai/docs/blob/main/client-ruby.mdx

Initialize the Chalk Ruby client with your credentials and environment ID, then use it to query specific features based on input identifiers. Ensure you have your client ID, client secret, and environment ID available.

```ruby
require 'chalk_ruby'

# Initialize the client
client = ChalkRuby::Client.new(
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  environment_id: 'your-environment-id'
)

# Query features
result = client.query(
  inputs: {
    'user.id' => 'user123'
  },
  outputs: [
    'user.credit_score',
    'user.account_age_days'
  ]
)

puts result
```

--------------------------------

### Call API with Python Requests

Source: https://github.com/chalk-ai/docs/blob/main/getting-started.mdx

Use the Python requests library to call an API from a Jupyter Notebook. Ensure the requests library is installed.

```python
import requests
requests.get(
    "https://credit-report.chalk.dev/rutter_score/12"
).json()["score"]
```

--------------------------------

### Real-time Query for Average Temperature

Source: https://github.com/chalk-ai/docs/blob/main/query-cron.mdx

Example of querying the cached average temperature for a specific city ID in real-time using the Chalk client.

```python
client.query(input={City.id: 713}, output=[City.average_temperature])
```

--------------------------------

### Schedule Resolver with Custom Samples and Subset of Arguments

Source: https://github.com/chalk-ai/docs/blob/main/resolver-cron.mdx

When providing custom samples, you can choose to supply only a subset of the resolver's arguments. Chalk will automatically sample the remaining arguments. This example provides `uid` and lets Chalk sample `balance`.

```python
def pull_examples() -> DataFrame[User.id]:
    return DataFrame.read_csv(...)

@online(cron=Cron(schedule="1d", samples=pull_examples))
def fn(uid: User.id, balance: User.account.balance) -> ...
```

--------------------------------

### Unit Test Feature Resolver

Source: https://github.com/chalk-ai/docs/blob/main/lifecycle.mdx

Write unit tests for your feature resolvers using pytest. This example tests the name_email_match_scorer with expected outputs.

```python
from pytest import approx

# Assume name_email_match_scorer is imported
def test_name_email_match_scorer():
    assert approx(0.60) == name_email_match_scorer(
        "katherine.johnson@nasa.gov",
        "Katherine Johnson",
    )
    assert approx(0.39) == name_email_match_scorer(
        "katherine.johnson@nasa.gov",
        "Eleanor Roosevelt",
    )
```

--------------------------------

### Query Data with ChalkClient

Source: https://github.com/chalk-ai/docs/blob/main/cookbook-snowflake-serving.mdx

Instantiate a ChalkClient and query data from the online store. This demonstrates how to retrieve specific features for a given input.

```python
from chalk.client import ChalkClient

client = ChalkClient()

client.query(inputs={BusinessFacts.id: 1234}, outputs=[BusinessFacts.name, BusinessFacts.review_count])
```

--------------------------------

### GET /v1/runs/:id

Source: https://github.com/chalk-ai/docs/blob/main/runs.mdx

Query the status of a previously triggered run using its unique ID. This is useful for polling the execution status until it completes.

```APIDOC
## GET /v1/runs/:id

### Description
Query the status of a previously triggered run using its unique ID. This is useful for polling the execution status until it completes.

### Method
GET

### Endpoint
https://api.chalk.ai/v1/runs/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - ID of the relevant run.

### Response
#### Success Response (200)
- **id** (string) - ID of the relevant run.
- **status** (enum) - One of 'received', 'succeeded', or 'failed'

#### Response Example
```json
{
  "id": "<run-id>",
  "status": "succeeded"
}
```
```