cognite-typed-functions 0.5.2

FastAPI-style framework for building type-safe Cognite Functions with automatic OpenAPI schema generation and MCP integration

Cognite Typed Functions

Enterprise-grade framework for building type-safe, composable Cognite Functions with automatic validation, built-in introspection, and AI integration.

Why Cognite Typed Functions?

Standard Cognite Functions require a simple handle(client, data) function, which becomes unwieldy for complex APIs. This framework provides composable architecture, automatic validation, and built-in introspection.

Standard Cognite Function:

def handle(client, data):
    try:
        asset_no = int(data["assetNo"])  # Manual validation
        include_tax = data.get("includeTax", "false").lower() == "true"  # Manual parsing
        # Handle routing manually based on data
        if data.get("action") == "get_item":
            # Implementation here
        elif data.get("action") == "create_item":
            # Different implementation
    except Exception as e:
        return {"error": str(e)}  # Basic error handling

With Typed Functions:

@app.get("/items/{item_id}")
def get_item(client: CogniteClient, item_id: int, include_tax: bool = False) -> ItemResponse:
    """Retrieve an item by ID"""
    # Type validation and coercion handled automatically
    # Clear function signature with proper types
    # Automatic error handling and response formatting

Key Features

• Type-safe routing - Decorator-based syntax with automatic validation
• Async/await support - Write both sync and async handlers
• Error handling - Comprehensive error handling with structured responses
• Logging - Enterprise logging with dependency injection
• Distributed tracing - OpenTelemetry-based tracing
• Dependency injection - Inject custom dependencies
• Introspection - Built-in schema, routes, health endpoints
• Model Context Protocol - Native AI tool exposure
• Local development server - Test locally with interactive API docs
• Function client - Notebook-first client for exploring functions

Installation

Requirements:

• Python 3.10 or higher
• uv (recommended) or pip

# Install the package
pip install cognite-typed-functions

# Optional: Install with CLI support for dev server
pip install cognite-typed-functions[cli]

# Optional: Install with tracing support
pip install cognite-typed-functions[tracing]

Quick Start

from cognite.client import CogniteClient
from pydantic import BaseModel
from cognite_typed_functions import FunctionApp, create_function_service

# Create your app
app = FunctionApp(title="My API", version="1.0.0")

# Define your models
class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None

class ItemResponse(BaseModel):
    id: int
    item: Item
    total_price: float

# Define your endpoints
@app.get("/items/{item_id}")
def get_item(
    client: CogniteClient,
    item_id: int,
    include_tax: bool = False
) -> ItemResponse:
    """Retrieve an item by ID"""
    item = Item(
        name=f"Item {item_id}",
        price=100.0,
        tax=10.0 if include_tax else None
    )
    total = item.price + (item.tax or 0)
    return ItemResponse(id=item_id, item=item, total_price=total)

@app.post("/items/")
def create_item(client: CogniteClient, item: Item) -> ItemResponse:
    """Create a new item"""
    new_id = 12345  # Your creation logic here
    total = item.price + (item.tax or 0)
    return ItemResponse(id=new_id, item=item, total_price=total)

# Export the handler for Cognite Functions
handle = create_function_service(app)

Test Locally

Install with CLI support and run the development server:

pip install cognite-typed-functions[cli]
ctf serve examples/

Visit http://localhost:8000/docs for interactive API documentation.

See the Local Development Server guide for detailed setup instructions.

Documentation

Note: Documentation is currently served locally only. We're working on deploying to GitHub Pages for easier access. Until then, you can browse the documentation files directly in this repository or build them locally with mkdocs serve.

Browse the documentation:

Getting Started

• Quick Start & Installation - Get up and running
• Examples - Complete working examples

Core Features

• Error Handling - Structured error responses
• Logging - Enterprise-grade logging
• Type Safety - Automatic validation and type conversion
• Dependency Injection - Custom dependencies
• Async Support - Concurrent handlers with async/await
• Introspection - Built-in schema and health endpoints
• Model Context Protocol - AI tool integration
• Distributed Tracing - OpenTelemetry observability

Development Tools

• Local Dev Server - Test functions locally with interactive docs
• Function Client - Notebook-first client for exploring functions

Advanced Topics

• App Composition - Build modular services
• Architecture - Framework design and internals

Reference

• API Reference - Complete API documentation
• Changelog - Release notes and version history
• Release Process - How we release new versions
• Contributing - Development and contribution guide

For the best experience, build and serve the docs locally with mkdocs serve to get the full MkDocs experience with navigation, search, and auto-generated API docs.

Examples

The framework includes a complete example in examples/handler.py demonstrating:

• Type-safe routing with decorator syntax
• MCP integration for AI tool exposure
• Built-in introspection endpoints
• Async handler support
• Composable app architecture

Contributing

We welcome contributions! Please see our Contributing Guide for:

• Development setup
• Code style guidelines
• Testing guidelines
• Documentation guidelines
• Pull request process

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Built specifically for Cognite Data Fusion Functions platform
• Decorator routing syntax inspired by FastAPI
• Data validation powered by Pydantic