quickstart.md

Quickstart (5 Minutes to First Log)

Get your first tamper-evident log anchored in under 5 minutes using the Blocklog Python SDK.

1. Installation

Install the blocklog-python package via pip:

pip install blocklog

2. Configure Credentials

Set your Blocklog API key as an environment variable. The SDK will automatically load this key:

export BLOCKLOG_API_KEY="blk_live_xxxxxxxxx"

If self-hosting or targeting a specific deployment, optionally configure the base URL:

export BLOCKLOG_BASE_URL="https://blocklogsecurity.com/app/api/v1"

3. Ingest and Verify an Event

Create a script named ingest.py to trace an agent execution, log a cryptographically sealed decision, and verify its integrity:

import os
import blocklog

# 1. Initialize the SDK (loads from environment variables)
blocklog.init(api_key=os.environ.get("BLOCKLOG_API_KEY", "blk_demo_key"))

# 2. Instrument a tool dependency
@blocklog.tool(name="fetch-spot-price")
def check_price(ticker: str) -> float:
    return 412.50

# 3. Instrument the agent execution
@blocklog.agent(name="quickstart-trader")
def run_agent():
    # Record the tool call automatically under the agent trace
    price = check_price("TSLA")
    
    # 4. Record a structured decision
    with blocklog.decision(type="BUY", asset="TSLA") as d:
        d.record_input(price=price)
        d.record_output(order_id="ord_123")
        
    print(f"Decision recorded: {d.id}")

    # 5. Programmatically verify the decision against signature/chain integrity
    try:
        verification = blocklog.verify.decision(d.id)
        print(f"Verification status: {verification.get('status', 'verified')}")
    except Exception as e:
        print(f"Verification failed: {e}")

if __name__ == "__main__":
    run_agent()

Run the script:

python ingest.py

4. Output

Upon execution, the SDK will:

• Establish a trace session context for quickstart-trader.
• Record a TOOL_CALL event for fetch-spot-price.
• Create a signed DECISION_COMPLETE log entry containing inputs, outputs, and metadata.
• Request verification of the generated decision block using Blocklog's verification API.