SDK & Self-Hosting

Python SDK

bash

pip install ginie

Full SDK reference

python

from ginie import GinieClient

client = GinieClient(api_key="your-key")

# Deploy a contract from a prompt
result = client.deploy(
    prompt="Create a bond with issuer Alice, holder Bob, £50,000 principal",
    ledger="ginienet",   # ginienet | localnet | mainnet
    llm="claude"         # claude | gpt4o | gemini | ginie1
)
result.contract_id      # str  — Canton Contract ID
result.cantonscan_url   # str  — CantonScan verification link
result.daml_source      # str  — full .daml source
result.audit_report     # dict — 5-gate findings
result.dar_path         # str  — path to compiled .dar file
result.job_id           # str  — for iteration

python — iterate

# Iterate on an existing contract
v2 = client.iterate(
    job_id=result.job_id,
    prompt="Add an early redemption choice callable by Alice only"
)

# Audit only — no deployment
audit = client.audit(daml_source=result.daml_source)
audit.gates             # list[GateFinding]
audit.critical_count    # int — number of CRITICAL findings
audit.passed            # bool — True if no CRITICALs

Selecting the LLM

The pipeline is model-agnostic. Claude Sonnet is the default — it produces the highest first-pass Daml compile rates in Ginie's production benchmark. You can switch to GPT-4o, Gemini 2.5 Flash, or (from M4) Ginie-1 using the llm parameter.

LLM	Key	Compile rate	Notes
Claude Sonnet	`claude`	Highest (default)	Best first-pass compile rate in production
GPT-4o	`gpt4o`	High	Good alternative, slightly higher cost
Gemini 2.5 Flash	`gemini`	Medium-High	Fastest, best for rapid iteration
Ginie-1	`ginie1`	≥95% target	Air-gapped, M4 release

Environment variables

Variable	Required	Description
`GINIE_API_KEY`	Yes (cloud)	Your Ginie API key — alternative to passing `api_key` in code
`ANTHROPIC_API_KEY`	Self-hosted	Claude API key for self-hosted deployments using Claude
`CANTON_LEDGER_HOST`	Self-hosted	Override the Canton participant node endpoint

SDK & Self-Hosting

Self-Hosting

Ginie is open-source (Apache 2.0) and self-hostable. Run the full pipeline on your own infrastructure using Docker — ideal for regulated environments, private networks, or custom Canton node deployments.

bash

# Clone the repo
git clone https://github.com/BlockX-AI/Canton_Ginie
cd Canton_Ginie

# Configure environment
cp .env.example .env.ginie
# Edit .env.ginie — set ANTHROPIC_API_KEY, CANTON_LEDGER_HOST, POSTGRES_URL

# Start all services
docker-compose up -d
# API   → http://localhost:8000
# Canton LocalNet → localhost:6865

Services

Service	Port	Description
`ginie-api`	8000	FastAPI backend — REST API and job queue (Celery)
`canton-sandbox`	6865	Canton LocalNet — full Daml Ledger API endpoint
`postgres`	5432	Job history, party registry, deployed contract log
`redis`	6379	Celery job queue and session state cache

Required environment variables

Variable	Example	Notes
`ANTHROPIC_API_KEY`	`sk-ant-…`	Required if using Claude as the LLM
`CANTON_LEDGER_HOST`	`localhost:6865`	Canton participant node gRPC endpoint
`POSTGRES_URL`	`postgres://ginie:pass@postgres:5432/ginie`	Job and party storage
`REDIS_URL`	`redis://redis:6379`	Celery broker URL
`SECRET_KEY`	random 32-byte hex	FastAPI session signing key

💡

Canton SDK inside Docker

The ginie-api Docker image ships with Canton SDK 3.4 and dpm pre-installed. No additional SDK setup is needed when running via docker-compose.

SDK & Self-Hosting

Ginie-1 (Air-Gapped)

Ginie-1 is a Canton-native open-weight language model, fine-tuned on Daml with RLCF using real Canton compiler feedback as the reward signal. Available from M4.

🔷

Who Ginie-1 is for

Ginie-1 is for regulated institutions — banks, asset managers, infrastructure providers — who cannot route financial contract specifications through an external API. Ginie-1 runs fully air-gapped: no network call, no data leaving your infrastructure, no third-party LLM dependency.

Attribute	Value
Base model	Mistral 7B or Qwen 2.5-Coder (configurable)
Training	SFT 3-epoch + 5-round RLCF on Canton compiler feedback
Target accuracy	≥95% first-pass compile rate on `ginie-eval` benchmark
Runtime format	GGUF / ONNX — CPU inference, no GPU required
Deployment	Single Docker image — pull and run on your own server
License	Apache 2.0 — weights published on HuggingFace
Cost	Free — no API key, no per-call billing after deployment

bash

# Pull and start Ginie-1
docker pull blockxai/ginie-1:latest
docker run -p 8001:8001 blockxai/ginie-1:latest

# Use Ginie-1 as the LLM in the SDK
client = GinieClient(llm="ginie1", llm_host="http://localhost:8001")

Benchmark: ginie-eval

Ginie-1 is evaluated against ginie-eval — a 50-prompt benchmark covering all 10 standard contract templates at two difficulty levels (standard and complex). Metrics reported:

Compile rate — percentage of first-pass compilations without Fix Agent
Audit pass rate — percentage passing all 5 security gates
Ledger correctness — percentage producing a verifiable live Contract ID

$ ginie-eval --model ginie1 --prompts 50
Running ginie-eval v1.0 against Ginie-1...
────────────────────────────────────────
Compile rate (first-pass): 96.0%
Audit pass rate:           94.0%
Ledger correctness:        92.0%
────────────────────────────────────────
Benchmark complete · 50/50 prompts processed