Metadata-Version: 2.4
Name: mathdatiao-agent
Version: 0.1.1
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: tests/release/licenses/Apache-2.0.txt
License-File: tests/release/licenses/MIT.txt
Summary: Native Tokitai runtime bindings for the mathdatiao competition agent
Keywords: intern-s1,math-agent,tokitai,reasoning,pyo3
Author: mathdatiao contributors
License: MIT OR Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/silverenternal/mathdatiao
Project-URL: Repository, https://github.com/silverenternal/mathdatiao

# mathdatiao-agent native Python bindings

`mathdatiao-agent` is a competition project distribution from the mathdatiao
contributors. It is not an official InternLM or Shanghai AI Laboratory
distribution. Intern-S1 and the official Challenge Cup runner remain external
upstream components with their own provenance and licenses.

The distribution is named `mathdatiao-agent`; its import namespace remains
`internlm` so the competition `user_agent.py` compatibility layer does not
need to own or duplicate the Rust runtime. The wheel contains the project's
PyO3 extension and its small Python shim only. SymPy, Z3, Lean and other
mathematics tools are deliberately not bundled into this wheel.

It is built with [PyO3] 0.21 and [maturin] 1.14.1 as one abi3 wheel per platform
for Python 3.10 and newer.

[PyO3]: https://pyo3.rs
[maturin]: https://www.maturin.rs

## Install

```bash
pip install ./mathdatiao_agent-0.1.1-cp310-abi3-<platform>.whl
```

The wheel is `abi3` (compiled against the Python 3.10 stable ABI), so one
platform wheel covers all supported CPython 3.10+ interpreters. A wheel tag
still has to match the operating system and architecture; abi3 does not make a
Linux wheel portable to macOS or Windows.

To build from source (e.g. for development):

```bash
# inside backend/ecosystem/internlm-py/
maturin develop --release
pytest tests/ -v
```

Building requires Rust and maturin. Installing a pre-built wheel does not:
the installed runtime must not invoke Cargo, download a tool, or start a
sidecar process. Publication is intentionally a separate, explicitly
authorized release step; local verification never uploads to PyPI.

The reproducible Linux release build uses a caller-owned target, path
remapping, auditwheel checking, and the checked-in top-level SPDX declaration:

```bash
REPO_ROOT="$(git rev-parse --show-toplevel)"
cd "$REPO_ROOT"
export CARGO_TARGET_DIR="$HOME/.cache/mathdatiao-target-wheel"
export RUSTFLAGS="--remap-path-prefix=$PWD=. \
  --remap-path-prefix=$HOME/.cargo/registry/src=cargo-registry \
  --remap-path-prefix=$HOME/.cargo/git/checkouts=cargo-git"
uvx --from 'maturin==1.14.1' maturin build \
  --release --locked \
  --auditwheel check \
  --manifest-path backend/ecosystem/internlm-py/Cargo.toml \
  --sbom-include \
backend/ecosystem/internlm-py/tests/release/mathdatiao-agent.spdx.json
```

Do not relabel the result to an older manylinux baseline. The current locked
graph includes a native-tls path through context AI support; a Zig
manylinux2014 build therefore requires a separately reviewed OpenSSL
static-vendoring or dependency-feature change. Until that is resolved, use the
lowest tag reported by maturin and confirmed by `auditwheel show`.

Before handing a wheel to the release integrator, run the backend's offline
artifact gate. It verifies metadata, abi3/native tags, every `RECORD` digest,
license files, SBOM members, and forbidden source/build files. If the declared
platform floor is not proven, the report is `explicit_unavailable`; never
rename the wheel to claim portability:

```bash
python3 backend/scripts/audit_wheel.py \
  /absolute/path/mathdatiao_agent-*.whl \
  --platform-floor manylinux_2_17 \
  --output backend/reports/distribution-audit-<run-id>.json
```

## Quickstart

```python
import internlm

client = internlm.Client("replace-with-token")
req = (
    internlm.ChatRequest("intern-latest")
    .message(internlm.Message.user("hello"))
    .temperature(0.3)
    .build()
)
print(client.create(req))                       # blocking
# or, from an async def:
#   text = await client.create_async(req)
```

## Streaming

```python
def on_delta(text: str) -> None:
    print(text, end="", flush=True)

client.stream_sync(req, on_delta)
```

## Context engineering

`ContextManager` is a thin in-memory wrapper over
`internlm::context_engineering::ContextManager`.  It exposes
`append`, `select`, and turn-count inspection.  The on-disk
`FileKV`-backed path is intentionally not exposed in this
revision; long-lived host processes that need it can drive the
Rust API directly.

```python
ctx = internlm.ContextManager("thread-1", max_tokens=8000)
ctx.append(internlm.Message.user("hi"))
ctx.append(internlm.Message.assistant("hello!"))
for turn in ctx.select():
    print(turn["role"], turn["content"])
```

## Token estimation

```python
est = internlm.TokenEstimator.heuristic()
est.estimate("hello, world!")                    # -> 3
gpt = internlm.TokenEstimator.tiktoken("gpt-4o")
gpt.estimate("hello, world!")                   # -> 4
gpt.name()                                      # -> "tiktoken"
```

## API overview

| Class             | Wraps                                           |
| ----------------- | ----------------------------------------------- |
| `Client`          | `internlm::Client` (async)                      |
| `Message`         | `internlm::types::chat::Message`                |
| `ChatRequest`     | `internlm::types::chat::ChatRequestBuilder`     |
| `ChatRequestRef`  | `internlm::types::chat::ChatRequest`            |
| `ContextManager`  | `internlm::context_engineering::ContextManager` |
| `TokenEstimator`  | `internlm::token_estimator::Heuristic/Tiktoken` |

Both blocking (`create`) and async (`create_async`) variants are
exposed on `Client`; the async path is a coroutine that runs on
the same tokio reactor the Rust SDK uses internally.

## Distribution boundary

The wheel is the native Tokitai ABI, not a complete competition submission.
The official `client.chat` object and in-process tool callback are supplied by
the thin `user_agent.py` bridge. External mathematics packages are installed
from their own official Python distributions and remain independently
licensed. They must not be copied into this wheel.

## License

MIT OR Apache-2.0, same as the underlying Rust crate.

