idun-sdk

PyPI Python License: MIT

A thin, dependency-free Python client + CLI for Azure AI Foundry agents (Idun / NatureLM) and any OpenAI-compatible endpoint. Tenant-agnostic by default: bring your own Foundry resource, no hardcoded tenant coordinates.

Install

pip install idun-sdk
# with optional PDF ingest:
pip install "idun-sdk[pdf]"   # pulls PyPDF2

Quick start (SDK)

from idun import IdunClient

client = IdunClient()                 # reads ~/.idun/config.toml
out = client.complete("Summarize the quarterly risk report.")
print(out["text"])

Two CLIs — two separate setup wizards (intentionally, not one)

This package ships two command-line tools with distinct purposes. They are intentionally kept separate — idun is the Azure AI Foundry client, idun-multi is the multi-provider LLM console. There is no unified idun-wizard; each tool has its own first-run setup wizard:

  • idun — the Azure AI Foundry client. Agent completions, trajectory export, document matrix (idun matrix), prompt packs (idun run / idun packs), and Hugging Face Hub operations (idun hf). Azure-specific.
    • idun wizard configures the Azure Foundry client (endpoint / project / agent) in ~/.idun/config.toml.
  • idun-multi — the multi-provider LLM console. Talks to any of the 17 registered providers (OpenAI, Anthropic, Groq, OpenRouter, HF, …) plus race, cost, models, doctor, support. Provider-agnostic.
    • idun-multi wizard configures the default LLM provider (picks one of the 17 registered providers, and prints the provider table so you can choose) in ~/.idun/config.toml.

The two wizards were previously unified, but that version was broken (the provider table was never printed) and was corrected back into two separate wizards. Both wizards write only to ~/.idun/config.toml (never ~/.idunrc, which is no longer used). Credentials live in per-provider ~/.idun/<id>.token files (0600).

idun-multi providers        # list providers + credential status
idun-multi -p openrouter ask "hello"   # -p goes BEFORE the subcommand
idun-multi race "explain quantum"      # compare providers on one prompt
idun-multi doctor            # environment + credential audit (also checks scripts)
idun-multi wizard            # pick the default LLM provider
idun wizard                  # configure the Azure Foundry client

Async

import asyncio
from idun import AsyncIdunClient

async def main():
    c = AsyncIdunClient()
    out = await c.acomplete("What changed vs last quarter?")
    print(out["text"])

asyncio.run(main())

CLI

idun — Azure AI Foundry client:

idun chat "your prompt"        # one-shot completion
idun trace "your prompt"       # full agent trajectory (steps)
idun export "your prompt" -o trace.md   # run + save trajectory (json/md)
idun token                     # inspect / rotate stored Entra token
idun login                     # device-code login to your Foundry (azure/hf/openai)
idun status                    # show resolved backend + credential state
idun run <pack> <key>          # run a bundled prompt pack
idun packs                     # list bundled prompt packs
idun matrix  --docs DIR --questions FILE   # Doc x Question pivot (IDEA α)
idun diff-docs --doc-a A --doc-b B --topics T  # clause-drift compare (IDEA γ)
idun diff "A" "B"              # compare two prompt trajectories side-by-side
idun hf whoami|status|push     # Hugging Face Hub operations
idun openapi                   # print the bundled OpenAPI 3 spec for the completion API
idun logo                      # show bundled Foundry logo paths
idun welcome                   # ASCII banner
idun wizard                    # configure the Azure Foundry client

idun-multi — multi-provider LLM console (-p <provider> goes BEFORE the subcommand):

idun-multi providers          # list providers + credential status
idun-multi -p openrouter ask "hello"   # chat with a provider
idun-multi race "explain quantum"      # compare providers on one prompt
idun-multi models              # list models (or --discover)
idun-multi cost                # token / cost estimate
idun-multi doctor              # environment + credential audit
idun-multi wizard              # pick the default LLM provider

Supported providers

The idun CLI / IdunClient speak to any OpenAI-compatible endpoint plus the native Azure AI Foundry transport. Registered providers (4 groups):

  • OpenAI-compatible: openai, groq, together, perplexity, fireworks, novita, xai, deepseek, mistral, openrouter, gemini, hf, nous
  • Anthropic: anthropic (Claude)
  • Azure: azure (Azure AI Foundry / Idun agent)
  • Local: ollama, local (bring your own endpoint)

Tested vs untested (as of 2026-08-21). After a full audit only a subset of these providers has actually been exercised against a live endpoint. The rest are registered and code-complete but NOT verified — they may work, but nobody has confirmed it.

Status Providers
✅ tested against a live endpoint openrouter (live OK), openai (token valid, account has no credit → HTTP 429), hf (migrated to router.huggingface.co; see note), ollama / local (correctly unreachable in CI)
⚠️ untested anthropic, groq, together, deepseek, mistral, gemini, xai, nous, perplexity, fireworks, novita
ℹ️ needs tenant azure

See AUDIT-BEFEHLE.md for the full command audit and BEFUNDE.md / ROADMAP-FIX.md for the bug log. A live test harness for idun race is planned to exercise all providers before the next release.

Hugging Face (hf): migrated to the OpenAI-compatible router https://router.huggingface.co/v1 (the old api-inference.huggingface.co host was retired and no longer resolves). Requires an HF token (HF_TOKEN).

Any OpenAI-compatible base URL works with zero code changes — set it in the config and the provider switches automatically. See SUPPORT_MATRIX.md for per-provider capability details.

Configuration (tenant-agnostic)

~/.idun/config.toml (neutral defaults — supply your own resource). Secrets go to per-provider ~/.idun/<id>.token files (mode 0600), not in this file:

# Written by `idun-multi wizard` (LLM provider default):
[defaults]
provider = "openrouter"

[openrouter]
model = "deepseek/deepseek-chat"

# Written by `idun wizard` (Azure AI Foundry client):
[azure]
base   = "https://YOUR-RESOURCE.services.ai.azure.com"
agent  = "your-agent-name"
project = "your-project"

No tenant coordinates are baked into the shipped code. The CLI reads the config via idun.config; environment variables (IDUN_PROVIDER, OPENAI_API_KEY, …) always win over the file.

Additional features

These build on the core SDK and live in idun.matrix / the playground repo.

Idun Matrix — Doc × Question pivot (IDEA α)

Build an N × M answer matrix over documents × questions. Each cell carries the answer, the source citation, and a status (GREEN = answered+cited, RED = contradiction, GRAY = no info).

idun matrix --docs ./contracts --questions ./questions.txt

Clause Drift compare (IDEA γ)

Compare two documents across topics and flag deviations:

idun diff-docs --doc-a contract_a.txt --doc-b contract_b.txt --topics topics.txt

PocketPal-style Bridge (IDEA β)

A tenant-agnostic mobile web UI that runs idun matrix against your Foundry resource: https://qapdex-maker.github.io/idun-playground/matrix_app.html

Links

Development

pip install -e ".[dev]"
pytest        # offline; no network/API keys required
ruff check .  # lint (pinned ruff==0.15.10 in CI)

License

MIT.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.0.29)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for AlexanderKleine from gravatar.com AlexanderKleine

Credits

Author: Idun

License

MIT

Requires

Python >=3.8

Provides Extra

pdf

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

idun_sdk-1.0.26.tar.gz (129.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

idun_sdk-1.0.26-py3-none-any.whl (92.1 kB view details)

Uploaded Python 3

File details

Details for the file idun_sdk-1.0.26.tar.gz.

File metadata

  • Download URL: idun_sdk-1.0.26.tar.gz
  • Upload date:
  • Size: 129.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.14.6

File hashes

Hashes for idun_sdk-1.0.26.tar.gz
Algorithm Hash digest
SHA256 0ee793388affcda452851239faa0fed68707f6022bc4cb7fb370e9adf8af0f8e
MD5 38675773e64cf975879909c09caed156
BLAKE2b-256 84c3cd966d35db21b3fb14d4e87974363c713c9c97f52fd23651a1f963ea298e

See more details on using hashes here.

File details

Details for the file idun_sdk-1.0.26-py3-none-any.whl.

File metadata

  • Download URL: idun_sdk-1.0.26-py3-none-any.whl
  • Upload date:
  • Size: 92.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.14.6

File hashes

Hashes for idun_sdk-1.0.26-py3-none-any.whl
Algorithm Hash digest
SHA256 4c77182b321b57bc9454cfcc48a816c27f709e72d2e2e13707bdd45a6090554e
MD5 73f44768570ce50acbb7aec66354367a
BLAKE2b-256 efb31363d700ac390470440493101504d0ce50927ab369d80e984d6c2026bd8d

See more details on using hashes here.

Release history Release notifications | RSS feed

1.0.29

2 files

1.0.28

2 files

1.0.27

2 files

This release

1.0.26 This release

2 files

1.0.25

2 files

1.0.24

2 files

1.0.23

2 files

1.0.16

1 file

1.0.15

1 file

1.0.14

1 file

1.0.13

1 file

1.0.12

1 file

1.0.11

1 file

1.0.10

1 file

1.0.9

1 file

1.0.8

1 file

1.0.7

1 file

1.0.6

1 file

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.1.38

2 files

0.1.37

2 files

0.1.36

2 files

0.1.35

2 files

0.1.34

2 files

0.1.33

2 files

0.1.32

2 files

0.1.31

2 files

0.1.30

2 files

0.1.29

2 files

0.1.28

2 files

0.1.27

2 files

0.1.26

2 files

0.1.25

2 files

0.1.24

2 files

0.1.23

2 files

0.1.22

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.17

2 files

0.1.16

2 files

0.1.15

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page