Fulcrum SDK Overview

Enterprise AI governance for Python and TypeScript applications.

Introduction

Fulcrum provides official SDKs for integrating AI governance into your applications. Both SDKs offer feature parity, enabling consistent governance across polyglot environments.

SDK	Package	Version	Status
Python	`fulcrum-governance`	0.1.0	Beta
TypeScript	`@fulcrum-governance/sdk`	0.1.1	Beta

SDK Comparison

Feature Matrix

Feature	Python	TypeScript	Notes
Policy Enforcement	Yes	Yes	Real-time governance checks
Execution Envelopes	Yes	Yes	Context-managed execution tracking
Guard API	Yes	Yes	Synchronous policy evaluation
Cost Tracking	Yes	Yes	LLM spend monitoring
Audit Logging	Yes	Yes	Async event publishing
Fail-Safe Modes	Yes	Yes	FAIL_OPEN / FAIL_CLOSED
TLS Support	Yes	Partial	Auto-detection on port 443
Async Client	Yes	Yes	AsyncFulcrumClient (Python)
Middleware Support	Yes	No	Event filtering/transformation
REST Client	No	Yes	Browser-compatible client
MCP Integration	Yes	Yes	Model Context Protocol

Runtime Requirements

Requirement	Python SDK	TypeScript SDK
Runtime Version	Python 3.9+	Node.js 18+
Protocol	gRPC	gRPC
TLS	Optional	Optional
Dependencies	grpcio, protobuf	@grpc/grpc-js, @grpc/proto-loader

Installation

Python

pip install fulcrum-governance

With development dependencies:

pip install fulcrum-governance[dev]

Dependencies installed: - grpcio >= 1.60.0 - protobuf >= 4.25.0 - googleapis-common-protos >= 1.60.0

TypeScript

npm install @fulcrum-governance/sdk

Or with yarn:

yarn add @fulcrum-governance/sdk

Dependencies installed: - @grpc/grpc-js ^1.9.0 - @grpc/proto-loader ^0.7.0 - uuid ^9.0.0

Quick Start

Python

from fulcrum import FulcrumClient

# Initialize client
client = FulcrumClient(
    host="your-fulcrum-server:50051",
    api_key="your-api-key"
)

# Wrap agent executions in governance envelopes
with client.envelope(workflow_id="customer-support-bot") as env:
    # Check if action is allowed before executing
    if env.guard("send_email", input_text=user_message):
        # Action approved - proceed
        result = send_email(user_message)
        env.log("email_sent", {"recipient": email, "status": "success"})
    else:
        # Action blocked by policy
        env.log("action_blocked", {"reason": "policy_violation"})

TypeScript

import { FulcrumClient } from '@fulcrum-governance/sdk';

// Initialize client
const client = new FulcrumClient({
  host: 'your-fulcrum-server:50051',
  apiKey: 'your-api-key',
  onFailure: 'FAIL_OPEN'
});

// Create governance envelope
const envelope = await client.envelope({
  workflowId: 'customer-support-bot',
  tenantId: 'your-tenant-id'
});

// Check if action is allowed before executing
const allowed = await envelope.guard('send_email', userMessage);

if (allowed) {
  const result = await sendEmail(userMessage);
  envelope.log('email_sent', { recipient: email, status: 'success' });
} else {
  envelope.log('action_blocked', { reason: 'policy_violation' });
}

Configuration

Both SDKs support identical configuration options with language-appropriate naming conventions.

Client Options

Option	Python	TypeScript	Default	Description
Host	`host`	`host`	localhost:50051	Fulcrum server address
API Key	`api_key`	`apiKey`	None	Authentication key
Tenant ID	`tenant_id`	`tenantId`	default-tenant	Default tenant
Failure Mode	`on_failure`	`onFailure`	FAIL_OPEN	Error behavior
Timeout	`timeout_ms`	`timeoutMs`	500	Request timeout (ms)
TLS	`enable_tls`	`enableTls`	Auto	Enable encryption
CA Certificate	`ca_cert_path`	`caCertPath`	None	Custom CA path

Environment Variables

Both SDKs support configuration via environment variables:

export FULCRUM_HOST="localhost:50051"
export FULCRUM_API_KEY="your-api-key"
export FULCRUM_TENANT_ID="your-tenant-id"
export FULCRUM_TIMEOUT_MS="500"

Python:

client = FulcrumClient.from_env()

TypeScript:

const client = FulcrumClient.fromEnv();

Core Concepts

Execution Envelope

The envelope is the fundamental unit of governance. It wraps agent executions to provide:

Policy evaluation before actions execute
Cost tracking throughout execution
Audit logging for compliance
State management for long-running operations

Guard API

The guard() method provides synchronous policy evaluation:

# Python
allowed = env.guard("action_name", input_text="user input", metadata={"key": "value"})

// TypeScript
const allowed = await envelope.guard('action_name', 'user input', { key: 'value' });

Returns true if the action is allowed, false if denied.

Fail-Safe Modes

Both SDKs support configurable behavior when Fulcrum is unreachable:

Mode	Behavior	Use Case
`FAIL_OPEN`	Allow actions when governance unavailable	Development, non-critical workloads
`FAIL_CLOSED`	Block actions when governance unavailable	Production, high-security environments

API Reference Summary

FulcrumClient Methods

Method	Description	Returns
`envelope()`	Create governance envelope	Envelope instance
`evaluate()`	Direct policy evaluation	PolicyDecision
`health_check()`	Server connectivity check	boolean
`shutdown()`	Clean client shutdown	void

Envelope Methods

Method	Description	Returns
`guard()`	Evaluate policy for action	boolean
`log()`	Publish audit event	void
`checkpoint()`	Create execution checkpoint	Checkpoint
`get_cost()`	Get current cost snapshot	CostSnapshot
`complete()`	Mark envelope complete	void

Error Handling

Python Exceptions

from fulcrum.exceptions import (
    FulcrumError,           # Base exception
    PolicyViolationError,   # Action blocked by policy
    BudgetExceededError,    # Budget limit reached
    ConnectionError,        # Server unreachable
    AuthenticationError,    # Invalid API key
    TimeoutError,           # Request timed out
)

TypeScript Errors

import {
  FulcrumError,           // Base error class
  PolicyViolationError,   // Action blocked by policy
  BudgetExceededError,    // Budget limit reached
  ConnectionError,        // Server unreachable
  AuthenticationError,    // Invalid API key
  TimeoutError,           // Request timed out
} from '@fulcrum-governance/sdk/errors';

Framework Integrations

Python Integrations

Framework	Support Level	Documentation
LangChain	Full	Example
LlamaIndex	Full	Example
OpenAI	Full	Example
Anthropic	Full	Via standard client
FastAPI	Full	Middleware available
Django	Full	Via standard client

TypeScript Integrations

Framework	Support Level	Documentation
Vercel AI SDK	Full	Example
LangChain.js	Full	Example
Express	Full	Middleware
Next.js	Full	Via standard client
Fastify	Full	Via standard client

Advanced Features

Async Support (Python)

import asyncio
from fulcrum import AsyncFulcrumClient

async def main():
    client = AsyncFulcrumClient(
        host="localhost:50051",
        api_key="your-api-key"
    )

    async with client.envelope(workflow_id="async-agent") as env:
        allowed = await env.guard("action", input_text="hello")
        if allowed:
            result = await do_async_work()
            await env.log("completed", {"result": result})

asyncio.run(main())

Middleware Support (Python)

def pii_filter(event_type, payload):
    """Filter sensitive data from audit logs."""
    if "email" in payload:
        payload["email"] = "[REDACTED]"
    return event_type, payload

client.add_middleware(pii_filter)

Browser Support (TypeScript)

For browser environments, use the REST client:

import { FulcrumRestClient } from '@fulcrum-governance/sdk/rest';

const client = new FulcrumRestClient({
  baseUrl: 'https://api.fulcrum.dev',
  apiKey: 'your-api-key'
});

// Same API as gRPC client
const envelope = client.envelope({ workflowId: 'browser-agent' });

MCP Integration

Both SDKs support the Model Context Protocol (MCP) for AI agent governance:

# MCP Server Name
io.github.Fulcrum-Governance/fulcrum

The check_governance MCP tool enables agents to evaluate actions against enterprise policies before execution.

See the MCP Registry for configuration details.

Version Compatibility

Python SDK

Python Version	SDK Support	Status
3.9	Full	Supported
3.10	Full	Supported
3.11	Full	Supported
3.12	Full	Supported
3.13	Untested	May work

TypeScript SDK

Node.js Version	SDK Support	Status
18.x	Full	Supported
20.x	Full	Recommended
22.x	Full	Supported

Package Information

Python (PyPI)

Field	Value
Package Name	fulcrum-governance
Current Version	0.1.0
License	Apache-2.0
Repository	github.com/fulcrum-io/fulcrum
Documentation	docs.fulcrum.dev

TypeScript (npm)

Field	Value
Package Name	@fulcrum-governance/sdk
Current Version	0.1.1
License	Apache-2.0
Repository	github.com/Fulcrum-Governance/fulcrum-io
Documentation	docs.fulcrum.dev

SDK Quickstart - 5-minute integration guide
Python SDK Reference - Complete Python API documentation
TypeScript SDK Reference - Complete TypeScript API documentation
Policy Authoring Guide - Creating governance policies
Dashboard Guide - Using the Fulcrum dashboard

Support

Documentation: docs.fulcrum.dev
Email: support@fulcrum.dev
GitHub Issues: For bug reports and feature requests

Document Version: 1.0 Last Updated: January 6, 2026

Fulcrum SDK Overview

Introduction

SDK Comparison

Feature Matrix

Runtime Requirements

Installation

Python

TypeScript

Quick Start

Python

TypeScript

Configuration

Client Options

Environment Variables

Core Concepts

Execution Envelope

Guard API

Fail-Safe Modes

API Reference Summary

FulcrumClient Methods

Envelope Methods

Error Handling

Python Exceptions

TypeScript Errors

Framework Integrations

Python Integrations

TypeScript Integrations

Advanced Features

Async Support (Python)

Middleware Support (Python)

Browser Support (TypeScript)

MCP Integration

Version Compatibility

Python SDK

TypeScript SDK

Package Information

Python (PyPI)

TypeScript (npm)

Related Documentation

Support