Metadata-Version: 2.4
Name: neosigma-sdk
Version: 0.1.0
Summary: NeoSigma tracing SDK — wrap your agents, emit OpenTelemetry spans to NeoSigma
Author: NeoSigma Team
License: MIT
Project-URL: Homepage, https://neosigma.ai
Project-URL: Documentation, https://docs.neosigma.ai
Keywords: opentelemetry,observability,tracing,llm,agents,anthropic,gen-ai
Classifier: Development Status :: 3 - Alpha
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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opentelemetry-api>=1.27.0
Requires-Dist: opentelemetry-sdk>=1.27.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Dynamic: license-file

# neosigma-sdk

Trace your AI agents and ship the results to [NeoSigma](https://neosigma.ai). Add a
few lines, run your agents as usual, and every run's model calls, tool calls, and
token usage lands in NeoSigma as a structured OpenTelemetry trace.

- **Dark by default**: with no API key (and `NEOSIGMA_CONSOLE_EXPORT=false`) the SDK is
  a complete no-op and never touches your application's own OpenTelemetry setup, so it's
  safe to leave in place.
- **Provider-agnostic**: a small core with thin adapters that wrap the agent
  framework you already use, with no hard dependency on any provider SDK.

## Install

```bash
pip install neosigma-sdk
# or:  uv add neosigma-sdk
```

## Quickstart

```python
import neosigma_sdk as neosigma

neosigma.init()        # reads NEOSIGMA_API_KEY from the environment
# ... wrap your agent client with the adapter for your framework and run as usual ...
neosigma.shutdown()    # flush before exit (long-running servers flush in the background)
```

Anthropic Managed Agents is supported today, with more frameworks on the way. See the
[documentation](https://docs.neosigma.ai) for per-adapter setup and the full API.

### Example: Anthropic Managed Agents

```python
import anthropic
import neosigma_sdk as neosigma

neosigma.init()
client = neosigma.wrap_managed_agents(anthropic.Anthropic())

# Build and run a Managed Agents session as you normally would. Streaming the
# session produces one NeoSigma trace: model calls, tool calls, and token usage.
session = client.beta.sessions.create(agent=agent, environment_id=environment.id)
with client.beta.sessions.events.stream(session_id=session.id) as stream:
    for event in stream:
        ...

neosigma.shutdown()
```

`AsyncAnthropic` works the same way (`async with` / `async for`).

## Configuration

Common settings read from a `NEOSIGMA_*` environment variable, or can be passed to
`init(...)`:

| Variable | Default | Purpose |
|---|---|---|
| `NEOSIGMA_API_KEY` | (none) | Your `ns_live_...` key. **Required to export**, without it the SDK stays dark. |
| `NEOSIGMA_PROJECT` | `default` | Logical project name, attached to every trace. |
| `NEOSIGMA_OTEL_ENDPOINT` | NeoSigma cloud | OTLP/HTTP endpoint. Override to target another environment. |
| `NEOSIGMA_CONSOLE_EXPORT` | `false` | Also print spans to stdout, for local debugging. |

See the [NeoSigma documentation](https://docs.neosigma.ai) for the complete configuration
reference and API docs.

## License

Released under the MIT License.
