Metadata-Version: 2.4
Name: idun-sdk
Version: 0.1.1
Summary: Thin client + CLI for Azure AI Foundry agent NatureLM-Idun-5-MoE
Home-page: https://github.com/qapdex-maker/idun-sdk
Author: QMFI-Research
Author-email: alexanderkleine@qmfiresearch.onmicrosoft.com
Project-URL: Source, https://github.com/qapdex-maker/idun-sdk
Project-URL: Playground, https://github.com/qapdex-maker/idun-playground
Project-URL: Docs (GitMCP), https://gitmcp.io/qapdex-maker/idun-sdk/sse
Project-URL: Bug Tracker, https://github.com/qapdex-maker/idun-sdk/issues
Keywords: azure,ai-foundry,azure-ai-foundry,agent,tool-agent,mcp,model-context-protocol,naturelm,idun,llm,cli,stdlib,termux,web_search,trace
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

# Idun SDK

Thin, **stdlib-only** client + CLI for the **NatureLM-Idun-5-MoE** agent on
**Azure AI Foundry** (codename *Idun*). No `httpx`, no `azure-identity` — it
runs headless on Termux/Android with nothing but the Python standard library.

Idun is a **tool agent**: it reasons and calls tools (`web_search`,
`memory_search`). This SDK surfaces the **full agent trajectory** — every
reasoning step and tool call — instead of a black-box chatbot wheel, so you
can see *how* it arrived at an answer.

## Install

```bash
pip install idun-sdk
```

The `idun` CLI and the `idun` Python package (plus the stdlib MCP server
`idun_mcp.py`) are installed.

## Authenticate (device-code, Entra)

```bash
idun login
# opens https://microsoft.com/devicelogin — enter the printed code,
# sign in with your QMFI-Research admin account.
# Token is saved to ~/foundry_token.txt (FOUNDRY_TOKEN).
```

Alternatively export `FOUNDRY_TOKEN` directly.

## Use

```bash
# final answer only
idun chat "Fasse in einem Satz zusammen, was Contoso im Bereich Nachhaltigkeit kommuniziert."

# full agent trajectory (reasoning + web_search tool steps)
idun trace "Use web_search to find the current CEO of Contoso and report the name."
```

### Python

```python
from idun import IdunClient

res = IdunClient().complete("Your prompt here")
print(res.text)            # final answer
for s in res.steps:        # agent trajectory
    if s.kind == "tool":
        print("TOOL", s.tool, s.status, s.query)
    else:
        print("REASON", s.text[:80])
```

`IdunResult` has:

- `text` — the final answer
- `steps` — list of `Step` (`kind="reasoning"|"tool"`, plus `tool`/`query`/`status` for tool steps)
- `model` — the backing model (e.g. `gpt-5.4-2026-03-05`)
- `raw` — the verbatim Foundry responses payload

## Request shape (verified working)

```
POST {base}/api/projects/{project}/agents/{agent}/endpoint/protocols/openai/responses?api-version=2025-05-15-preview
Authorization: Bearer ***
Content-Type: application/json

{"model": "model-router", "input": "<prompt string>", "max_output_tokens": 4096}
```

Notes:

- `model` MUST be `"model-router"` (the agent id is already in the URL).
- Do **not** send a `tools` key — the agent owns its capabilities; doing so
  returns `400 invalid_payload`.
- The answer is in `output[].content[].text`; tool calls appear as
  `web_search_call` items with `action.queries` and `status`.

## MCP — agent + docs

Idun is available as an MCP server **and** has a GitMCP docs mirror, so other
agents can both call Idun and read its documentation without hallucinating.

### 1. Idun MCP server (stdlib-only, local)

`idun_mcp.py` is a zero-dependency stdio MCP server — no FastMCP / httpx
needed (runs on bare Python, ideal for Termux/Android).

```bash
python3 idun_mcp.py        # stdio MCP server
```

Tools exposed:

- `idun_chat(prompt)` — final answer text
- `idun_trace(prompt)` — full agent trajectory (steps + text)

Add to any MCP client (e.g. Cursor `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "idun": { "command": "python3", "args": ["/abs/path/idun-sdk/idun_mcp.py"] }
  }
}
```

### 2. GitMCP docs mirror (remote, zero-setup)

```
https://gitmcp.io/qapdex-maker/idun-sdk/sse
```

For stdio-only clients (Claude Desktop, Cline, Msty):

```json
{ "mcpServers": { "idun-docs": { "command": "npx", "args": ["mcp-remote", "https://gitmcp.io/qapdex-maker/idun-sdk/sse"] } } }
```

**Recommended combo for a foreign agent:** both `idun` (calls the agent) and
`idun-docs` (reads the SDK docs) — it can invoke Idun *and* look up the exact
`IdunClient` signature on its own.

## Why stdlib-only?

Many AI agents run on constrained hosts (Termux on Android, minimal
containers). Pulling `httpx`/`pydantic`/`azure-identity` breaks those setups.
This SDK uses `urllib.request` + `json` only, so `pip install idun-sdk` just
works everywhere Python 3.8+ runs.

## Links

- PyPI: https://pypi.org/project/idun-sdk/
- SDK repo: https://github.com/qapdex-maker/idun-sdk
- Playground repo: https://github.com/qapdex-maker/idun-playground
- GitMCP docs: https://gitmcp.io/qapdex-maker/idun-sdk/sse
