poh-sdk

Python SDK for the Decentralized Artificial Intelligence network.

Install

pip install poh-sdk

# For transaction signing:
pip install poh-sdk cryptography

Quick start

import asyncio
from poh_sdk import DAIClient

async def main():
    async with DAIClient("https://miner.iamai.kg") as dai:
        result = await dai.scan("0xabc...")
        print(result.result)   # True = human, False = bot, None = inconclusive

asyncio.run(main())

Sync usage

Use DAIClient.sync(...) to get a synchronous wrapper exposing the same methods (no _sync suffix) without await:

from poh_sdk import DAIClient

dai = DAIClient.sync("https://iamai.kg")
result = dai.scan("0xabc...")
balance = dai.get_balance("dai...")

Natural language jobs

Skill jobs always require a fee — pass budget (DAI), wallet_address, and private_key_pem in AskOptions so the SDK can sign the payment. The node verifies the signature and debits the fee before it will run the job at all; it rejects the request outright (no job ever runs) without a valid signed payment. Pass currency in AskOptions to pay the fee in a stablecoin (see Stablecoins).

from poh_sdk import AskOptions

async with DAIClient("https://iamai.kg") as dai:
    options = AskOptions(budget=0.5, wallet_address="dai...", private_key_pem=my_private_key)

    # Submit a question
    ref = await dai.submit_job(
        "What does vitalik.eth write about on Paragraph?",
        options,
    )

    # Wait for the answer
    result = await dai.poll_job_result(ref.job_id)
    print(result.output)       # skill-specific structured data
    print(result.nl_response)  # LLM natural-language answer

    # One-liner convenience
    result = await dai.ask_and_wait("What NFTs does gmoney.eth hold?", options)

Compute jobs (your own model + dataset)

Run inference with a model of your choice, optionally grounded in a Hugging Face dataset already installed on the node. Like skill jobs, compute jobs are never free — run_compute always signs a fee payment.

from poh_sdk import ComputeOptions

async with DAIClient("https://iamai.kg") as dai:
    ref = await dai.run_compute("Summarize the top 5 rows", ComputeOptions(
        model="llama3.1:8b",
        dataset="some-org/some-dataset",  # optional
        budget=0.5,                       # DAI (or `currency` display units)
        wallet_address="dai...",
        private_key_pem=my_private_key,
    ))
    result = await dai.poll_job_result(ref.job_id)
    print(result.output)

Before either of these will work, the wallet's signing key must be registered with the node once via register_signing_key() / register_key_pair() — the node has no way to verify a signature for a key it has never seen.

Estimating a job's fee

Before paying for a job, ask the node what it will cost — the eth_estimateGas of DAI. Send the same fields you would submit (prompt, attachments, a skill, MCP tools, a dataset). The node sizes the whole pipeline — attachment text, skill and MCP output, dataset rows, planner and synthesis calls — and returns the AI tokens it will use, the minimum fee it accepts, and a recommended budget. It is read-only: nothing runs and nothing is paid.

from poh_sdk import ChatAttachment, EstimateOptions

async with DAIClient("https://iamai.kg") as dai:
    est = await dai.estimate(
        "Summarize this report and compare it with the latest news",
        EstimateOptions(
            attachments=[ChatAttachment(name="report.md", content=report_text)],  # text is inlined and measured
            # skill_id="web_search", mcp=["shop__search"], dataset="some-org/some-dataset",
            # currency="aiKGS", max_output_tokens=512, route=False,
        ),
    )

    est.fees.minimum.raw        # μDAI the node will accept, at minimum
    est.fees.recommended.raw    # μDAI to escrow — covers the worst case
    est.total_tokens            # TokenRange(min=…, max=…)
    est.breakdown               # what each part contributed, and how sure that is

    # run_compute takes DAI; estimate returns μDAI
    budget = est.fees.recommended.raw / 1e9

What comes back:

Amounts are in raw units of the fee currency (μDAI for DAI; 1 DAI = 1e9 μDAI), so divide by 1e9 for runCompute's budget. For a non-DAI currency the price is quoted off the live P2P book; if nothing quotes that pair the quote says unavailable instead of inventing a number, and a DAI figure is returned alongside.

Needs a node newer than 0.4.36 (it adds POST /api/estimate); older nodes answer 404. estimate is read-only, so — unlike the other POST methods — it works against remote nodes without a local_base_url.

Wallet / blockchain

async with DAIClient("https://iamai.kg") as dai:
    # Balance (μDAI — divide by 1e9 for DAI)
    bal = await dai.get_balance("dai...")
    print(bal.balance / 1e9, "DAI")

    # Nonce
    nonce = await dai.get_nonce("dai...")

    # Transaction history (balance journal)
    history = await dai.get_transaction_history("dai...", limit=50)
    for entry in history.entries:
        print(entry.tx_hash, entry.delta)

    # Raw transaction records involving an address
    txs = await dai.get_transactions("dai...")

    # Miner info
    info = await dai.get_miner_info()
    print(info.model, info.reputation)

Signing & transactions

from poh_sdk import (
    generate_key_pair,
    build_transfer,
    sign_transaction,
    create_signing_proof,
)

# 1. Generate a keypair — address is derived from the signing public key
private_key_pem, public_key_pem, my_address = generate_key_pair()

# 2. Register the public key with your local node (one-time)
async with DAIClient(
    "https://miner.iamai.kg",
    local_base_url="http://127.0.0.1:3456",
) as dai:
    await dai.register_signing_key(
        my_address, public_key_pem, create_signing_proof(my_address, private_key_pem)
    )

    # 3. Build, sign, and submit a transfer
    nonce_resp = await dai.get_nonce(my_address)
    tx     = build_transfer(my_address, recipient, amount_dai=5.0, nonce=nonce_resp.nonce + 1)
    signed = sign_transaction(tx, private_key_pem)
    result = await dai.submit_transaction(signed)
    print(result.tx_hash)

    # One-liner convenience (fetches nonce automatically)
    result = await dai.transfer(my_address, recipient, 5.0, private_key_pem)

register_key_pair(KeyPair(...)) does the same registration from a KeyPair, deriving the proof automatically and also publishing the wallet's X25519 encryption key (see Chat record encryption). To replace an already-registered key, sign a create_rotation_proof(address, new_signing_public_key, existing_private_key_pem) with the current key and pass it as rotation_proof.

Stablecoins (multi-currency)

Five regional stablecoins ride alongside DAI: aiGEL, aiKGS, aiAMD, aiETB, aiBTN (2 decimals — 1 unit = 100 raw; DAI keeps 9).

# Transfer 12.50 aiGEL — build + sign + submit manually
# (transfer() itself is DAI-only; it has no currency parameter)
tx = build_transfer(from_addr, to, 12.5, nonce + 1, currency="aiGEL")
signed = sign_transaction(tx, private_key_pem)
await dai.submit_transaction(signed)

# Pay a compute job in aiKGS — the miner receives exactly aiKGS
ref = await dai.run_compute("Summarize…", ComputeOptions(
    model="qwen3-1.7b", budget=5.0, currency="aiKGS",
    wallet_address=addr, private_key_pem=key,
))

DAI transactions/job payments hash exactly as before (currency enters the signed preimage only when non-DAI) — existing integrations are unaffected.

Chat record encryption

Public-job chat records (promptCipher / replyCipher) are sealed to the requester wallet's X25519 key, derived deterministically from its Ed25519 signing key. register_key_pair() publishes the encryption key automatically.

from poh_sdk import derive_encryption_keypair, is_envelope, unseal

keys = derive_encryption_keypair(private_key_pem)
# keys["publicKeyB64"], keys["privateScalarB64"]

if is_envelope(record["promptCipher"]):
    prompt = unseal(record["promptCipher"], keys["privateScalarB64"])

Bulk scans

async with DAIClient("https://iamai.kg") as dai:
    job = await dai.scan_bulk(["0xaaa", "0xbbb", "0xccc"])

    # Stream progress
    async for snap in dai.watch_job(job.job_id):
        print(f"{snap.percent:.0f}% done")

    # Or wait in one call
    final = await dai.scan_and_wait(["0xaaa", "0xbbb"])

Multi-node

dai = DAIClient(nodes=[
    "https://miner.iamai.kg",
    "https://iamai.kg",
    "https://miner.iamai.kg",
])
# Automatically picks the fastest responding node

API reference

Scanning

Signal methods

Natural language jobs

Wallet / blockchain

Signing utilities

Chat encryption utilities

Node info

Differences from the JS SDK

The Python SDK does not (yet) implement some features present in @poh_network/sdk:

• chat() — no free-form chat endpoint wrapper
• submit_feedback() — no job star-rating
• get_assets() — no asset-registry / gas-price endpoint wrapper
• get_balance() returns only the μDAI balance (no stablecoin assets map)
• transfer() has no currency parameter — stablecoin transfers go through build_transfer(currency=...) + submit_transaction()
• TxSubmitResult has no idempotent flag
• No pick_strategy option (multi-node always picks the fastest node)

License

MIT