Metadata-Version: 2.4
Name: cosmon-agent-sdk
Version: 0.1.1
Summary: Program the Nexus agent in your installed Cosmon app — drive SolidWorks, Abaqus, COMSOL, Fluent and more.
Project-URL: Homepage, https://cosmon.com
Project-URL: Documentation, https://docs.cosmon.com/sdk/overview
Project-URL: Repository, https://github.com/Cosmon-Inc/cosmon
Author-email: "Cosmon, Inc." <support@cosmon.com>
License: Copyright (c) 2026 Cosmon, Inc. All rights reserved.
        
        NEXUS AGENT SDK — PROPRIETARY SOFTWARE LICENSE
        
        This software and associated documentation files (the "Software") are the
        proprietary and confidential property of Cosmon, Inc. ("Cosmon").
        
        1. License grant. Subject to your agreement to Cosmon's Terms of Service and any
           applicable subscription or commercial agreement, Cosmon grants you a limited,
           non-exclusive, non-transferable, revocable license to install and use the
           Software solely to interface with the Cosmon Nexus application that you have
           licensed and are authorized to use.
        
        2. Restrictions. You may not, except to the extent permitted by applicable law:
           (a) copy, modify, or create derivative works of the Software; (b) reverse
           engineer, decompile, or disassemble the Software; (c) redistribute, sublicense,
           sell, rent, or lease the Software; or (d) remove or alter any proprietary
           notices.
        
        3. Ownership. The Software is licensed, not sold. Cosmon retains all right, title,
           and interest in and to the Software, including all intellectual property rights.
        
        4. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
           EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
           MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
        
        5. Limitation of liability. IN NO EVENT SHALL COSMON BE LIABLE FOR ANY CLAIM,
           DAMAGES, OR OTHER LIABILITY ARISING FROM OR IN CONNECTION WITH THE SOFTWARE OR
           ITS USE.
        
        For licensing inquiries, contact legal@cosmon.com.
License-File: LICENSE
Keywords: agent,cad,cae,cosmon,mcp,nexus,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: anyio>=4
Requires-Dist: httpx>=0.24
Requires-Dist: mcp<2,>=1.28
Requires-Dist: pydantic>=2
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# Cosmon Agent SDK (Python)

> **⚠️ Alpha.** This SDK is an early release: the API surface is still moving
> and **breaking changes will ship in minor versions** while we're on `0.x`.
> Pin an exact version (`cosmon-agent-sdk==0.1.1`) in anything you don't want
> to fix on upgrade day, and read the [CHANGELOG](CHANGELOG.md) before bumping.

Program the **Nexus agent** in your installed, signed-in Cosmon app — drive
SolidWorks, Abaqus, COMSOL, Fluent, Ansys Mechanical and more from your own
Python. Your code brings the *caller*; the installed app brings the *capability*
(your login, your credits, the CAD software on your machine). **Your code never
holds a key.**

Under the hood the SDK is a small [MCP](https://modelcontextprotocol.io) client:
it discovers the running app, connects to the local MCP server it exposes, and
drives the agent through one `run` tool.

## Install

```bash
pip install cosmon-agent-sdk
```

Then: open Cosmon, sign in, and turn on **Settings → Developer access**.

Check it's working:

```bash
cosmon doctor
```

## Quickstart

`client.run()` returns a `Run`; get the agent's final answer with `.text()`:

```python
from cosmon_agent_sdk import Client

with Client() as client:
    answer = client.run("What's the max von Mises in bracket.sldprt?", agent="solidworks").text()
    print(answer)
```

Or **iterate** the run to stream it — it yields typed `ToolCall` / `TextChunk`
events (`.text()` and iterating are the two ways to consume a run; pick one):

```python
import sys
from cosmon_agent_sdk import Client, TextChunk, ToolCall

with Client() as client:
    for event in client.run("Run a static study on bracket.sldprt", agent="solidworks"):
        if isinstance(event, TextChunk):
            print(event.text, end="", flush=True)          # answer, token by token
        elif isinstance(event, ToolCall) and not event.finished:
            print(f"[{event.summary}]", file=sys.stderr)    # tool steps
```

## Attended vs unattended

Interactivity is set when you build the client, by whether you supply handlers:

- **Unattended (default)** — no handlers. The agent is never offered `ask_user`
  (it proceeds on its own) and confirmations are auto-resolved (approve safe,
  **decline dangerous**). `.text()` just runs to completion. This is the headless
  path; put any decisions the agent might otherwise ask about in the prompt.
- **Interactive** — supply `on_question` and/or `on_confirm`. The app forwards the
  agent's `ask_user` / `confirm_action` to your handlers (over MCP elicitation)
  while `.text()` runs to completion. There's no event loop to drive — your
  handlers are called as needed, so `.text()` never stalls waiting for an answer.

```python
from cosmon_agent_sdk import Client, Question, Confirmation

def answer(question: Question) -> str:
    return question.options[0] if question.options else "10mm seed size"

def approve(confirmation: Confirmation) -> bool:
    return True  # your policy here

with Client(on_question=answer, on_confirm=approve) as client:
    print(client.run("Mesh the model and submit the job", agent="abaqus").text())
```

## Long runs

The agent can work for many minutes (mesh, solve, post-process). The client sets
a generous default `timeout` (10 minutes) and you can raise it:

```python
with Client(timeout=1800) as client:   # 30 minutes
    client.run("Run a mesh-convergence study on bracket.sldprt", agent="solidworks").text()
```

## Async

`AsyncClient` is the async twin (for pipelines, FastAPI, etc.) — same surface,
`await`ed:

```python
import asyncio
from cosmon_agent_sdk import AsyncClient

async def main() -> None:
    async with AsyncClient() as client:
        print(await client.run("what can you do?", agent="nexus").text())

asyncio.run(main())
```

`Client`/`AsyncClient` and `Run`/`AsyncRun` are the sync/async pairs.

## Command line

```bash
cosmon doctor                                  # check the connection, step by step
cosmon run "mesh and solve" --agent abaqus                  # stream the work (steps to stderr)
cosmon run "what can you do?" --agent nexus -q              # -q: print just the final answer
```

The CLI is headless (it can't answer `ask_user`); `--auto-approve` additionally
approves confirmation requests, including dangerous ones.

## Notes

- **Discovery**: the app writes a `mcp-gateway.json` descriptor while Developer
  access is on; the SDK reads it automatically. Override with the
  `COSMON_SDK_DESCRIPTOR` environment variable.
- **Errors**: connecting / starting a run can raise `CosmonConnectionError`,
  `CosmonAuthError`, `CosmonTimeoutError`, `CosmonProtocolError`; a run that fails
  while running raises `CosmonRunError` from `.text()`.
- Docs: <https://docs.cosmon.com/>
