Metadata-Version: 2.5
Name: sentientx
Version: 0.1.0rc1
Summary: Unified CLI and MCP surface for the sentientx lifecycle
Project-URL: Homepage, https://sentientx.io
Project-URL: Documentation, https://docs.sentientx.io
License: LicenseRef-Proprietary
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: connectrpc==0.10.1
Requires-Dist: fastapi>=0.115
Requires-Dist: grpcio<2,>=1.76
Requires-Dist: httpx>=0.27
Requires-Dist: jaxtyping>=0.2
Requires-Dist: keyring>=25
Requires-Dist: mcp<2,>=1.26
Requires-Dist: numpy>=2.1
Requires-Dist: opentelemetry-api<2,>=1.43
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.43
Requires-Dist: opentelemetry-instrumentation-aiohttp-client<1,>=0.64b0
Requires-Dist: opentelemetry-instrumentation-botocore<1,>=0.64b0
Requires-Dist: opentelemetry-instrumentation-httpx<1,>=0.64b0
Requires-Dist: opentelemetry-instrumentation-psycopg<1,>=0.64b0
Requires-Dist: opentelemetry-instrumentation-redis<1,>=0.64b0
Requires-Dist: opentelemetry-instrumentation-requests<1,>=0.64b0
Requires-Dist: opentelemetry-instrumentation-system-metrics<1,>=0.64b0
Requires-Dist: opentelemetry-sdk<2,>=1.43
Requires-Dist: posthog>=7.21
Requires-Dist: protobuf<7,>=6.33.5
Requires-Dist: protovalidate==1.1.2
Requires-Dist: psycopg-pool>=3.2
Requires-Dist: psycopg[binary]>=3.2
Requires-Dist: pydantic>=2.10,>=2.9
Requires-Dist: pyqwest>=0.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.15
Provides-Extra: episodes
Requires-Dist: harbor==0.18.0; extra == 'episodes'
Requires-Dist: pyarrow>=14; extra == 'episodes'
Requires-Dist: rerun-sdk<0.37,>=0.36; extra == 'episodes'
Description-Content-Type: text/markdown

# sentientx

The hosted, project-scoped entrypoint to the sentientx robotics platform — one CLI,
one MCP server, and one Python SDK over the same governed resources.

`sx` names governed resources, submits one durable operation, and prints a reference you
can watch from any later shell. It needs no request JSON, no service URLs, no worker
queues, and no locally running infrastructure.

```bash
curl -fsSL https://docs.sentientx.io/install.sh | sh
```

Installs `sx` and `sx-mcp` on Linux or macOS with a managed Python runtime. No pip,
system Python, or administrator access is required. Open a new terminal if prompted.
Run the same command again to update. Access to a sentientx project is required; see
[the installation guide](https://docs.sentientx.io/docs/agents) for release availability
and setup. For `import sx` in your own application, install `sentientx` into that
application's Python 3.12 or newer environment separately.

Hosted operations work without local Rerun. For local RRD validation and episode outboxes,
install `sentientx[episodes]` on a platform supported by the current Rerun SDK.

## Three depths, one project

Start at the highest level that expresses the outcome. Going deeper reveals control; it
does not create another project or bypass the platform's gates.

1. **Hosted builder.** Describe what the robot should do, where it should work, its
   limits, and what counts as success. The platform agent plans the next step and keeps
   its skills, tool calls, evidence, and durable receipts inspectable.
2. **Your coding agent.** Connect a local workspace to the same project. The `sx` MCP
   server supplies governed reads and mutations across Experience, Worlds, Autonomy, and
   Fleet, and an installed project skill keeps the agent working in outcome language.
3. **Your program.** Import `sx` when the workflow belongs in code. The SDK exposes the
   same project identity, domain values, operation receipts, and fail-closed gates.

There is no advanced mode and no state conversion between these depths. A task,
application, evaluation, deployment, or operation created through one surface is the same
governed resource the other two read.

## Authenticate and connect

Authenticate once in the hosted browser, then bind the current workspace to one explicit
project. The CLI stores its revocable credential in your operating system's credential
store; it never prints the key or writes it into the workspace.

```bash
sx auth login
sx project list
sx project connect --project <project-uuid>
```

`sx project connect` preserves any other MCP servers already configured, adds the
project-scoped `sx-mcp` server to Claude Code's `.mcp.json` and Codex's
`.codex/config.toml`, and installs the project skill for both coding agents. It writes
the non-secret project id, workspace path, and profile, never your credential. Restart
or reload the agent session after connecting so it discovers the local tools and skill.

## Author a local world preview

Keep authored inputs and one explicit preview export in the connected world folder. A preview
can be a self-contained static GLB, or a standard 3D Tiles 1.1 `tileset.json` whose relative
content paths select bounded self-contained GLB leaves and child JSON pages. Each JSON page root
selects a coarse GLB and uses `REPLACE` refinement. Declare the root, authored source paths, and
required license in `world.sx.yaml`:

```yaml
schema: sx.world-authoring/v1
name: Packing bench
preview: build/preview.glb
sources:
  - author_scene.py
license_id: LicenseRef-Proprietary
```

Then create, sync, and open the retained project draft:

```bash
sx worlds draft init world.sx.yaml
sx worlds draft sync world.sx.yaml
sx worlds draft open world.sx.yaml
```

`sync` uploads missing preview members from leaves to root, then atomically accepts the complete
root. A retry reuses admitted content, and changing one tile uploads that tile and its changed
ancestor pages. Source files, agent conversations, and model credentials stay local. A stale
sync tells you to inspect the hosted head and run
`sx worlds draft adopt <reviewed-revision>` before a deliberate next sync. The command refuses
if that head moved again. Adoption uploads nothing and changes no source files. This preview is
visual only; it is not a published environment or proof of simulation readiness.

Use `sx auth status` to inspect the current identity, and `sx auth logout` to revoke this
CLI's key before removing it locally. `SX_API_KEY` is the explicit non-interactive
override for CI and enrolled machines, not the human setup path.

## Operations are durable

Every long-running verb returns a `pillar/kind/id` reference. The work continues when the
CLI disconnects.

```bash
OPERATION=$(sx worlds evaluate generalist-picker --task "Pick and place")
sx watch "$OPERATION"
```

Reattach later with `sx watch`, inspect once with `sx status`, fetch the terminal value
with `sx result`, or stop work explicitly with `sx cancel "$OPERATION" --reason "..."`.

Capture runs from the same hosted surface once a station has been enrolled and
commissioned:

```bash
CAPTURE=$(sx experience capture --task "Pick and place" --with yubi --episodes 100)
sx watch "$CAPTURE"
```

Station enrollment, calibration, hardware readiness, and fail-closed robot control stay
edge-local. Submitting work to an already-enrolled station requires none of them.

## Working with a coding agent

Give the agent the outcome and the accountable decisions, not an implementation recipe:

```text
Build a canary-ready application that sorts inspected connectors into three bins.
Keep human approval for task publication and promotion. Show the evidence and durable
receipt behind each completed gate.
```

The skill keeps the conversation at builder altitude, chooses the owning pillar, and uses
MCP for inspection and action. Ask to see tool inputs or receipts when debugging; ask for
SDK code when the workflow needs to become a program.

## Python SDK

The Python API keeps the same resource and operation model while returning canonical
domain types:

```python
from sx import Sx, WorldEvaluation


async def evaluate() -> WorldEvaluation:
    sx = Sx()
    task = await sx.experience.tasks.spec("Pick and place")
    application = await sx.autonomy.applications.get("generalist-picker")
    operation = await sx.evaluate(application, task=task)
    print(operation.ref)  # save this to reattach later
    projection = await operation  # generated Worlds verdict + scorecard
    print(projection.verdict)
    return await sx.worlds.canonical_evaluation(operation)
```

`sx.operation(ref)` reattaches without I/O. Status, ordered updates, terminal result
retrieval, and cancellation route to the pillar that owns the operation. Closing the local
SDK object never cancels server work.

Awaiting the operation returns the generated protocol `WorldEvaluation` projection. For an
application evaluation, `sx.worlds.canonical_evaluation(operation)` follows its exact
`canonical_run` content reference and returns the canonical `sx_worlds.WorldEvaluation` domain
value after verifying the projection against Catalog evidence.

Deploying takes one complete application manifest — a bare checkpoint is not a deployable
unit:

```python
from pathlib import Path

import yaml

from sx import Sx, application_manifest_from_dict


async def deploy(manifest_path: Path):
    document = yaml.safe_load(manifest_path.read_text(encoding="utf-8"))
    manifest = application_manifest_from_dict(document)

    sx = Sx()
    operation = await sx.deploy(manifest)
    print(operation.ref)  # persist this to reattach from another process
    return await operation
```

`sx.deploy(manifest)` executes or reuses the typed build graph, assembles one exact
`RobotApplication`, obtains Worlds and Fleet qualification, requires one approval per
declared task, and asks Fleet for an atomic rollout. Any failed gate is the operation
result; the SDK never substitutes a partial deployment.

## Robot description assets

The package ships the SDK, not the robot geometry. URDF, MJCF, and mesh files are read from
a local tree or an asset store and cached locally on first use, each verified against the
digest the registry's manifest declares for it; every file a registered robot's description
names is in that manifest.

Naming an embodiment needs nothing on disk:

```python
from sx_embodiments import embodiments

arm = embodiments["franka"]     # identity, joints, cameras, limits — no files needed
```

Reading its description bytes does. A hosted asset store and its read credentials are
not issued yet; until they are, bytes come from a local tree named by
`SX_EMBODIMENTS_ASSETS`. The SDK already reads a store configured like this:

```bash
export SX_EMBODIMENTS_ASSET_STORE=https://<your-asset-store>
export SX_EMBODIMENTS_ASSET_STORE_TOKEN=<your read token>
```

Objects are fetched by digest, verified against the embodiment's declared sha256 and size,
and cached under `~/.cache/sx-embodiments/sha256/`; `materialize(embodiment)` returns a
directory holding exactly that robot's description and the meshes it names. Without a
tree or a store, anything that needs bytes raises `AssetsUnavailableError` naming both
variables, and a refused or missing object raises the same error. It never silently substitutes or degrades.

## Analytics

MCP analytics is optional and off by default. Set both `POSTHOG_PROJECT_TOKEN` and
`POSTHOG_HOST` in the `sx-mcp` process environment to capture MCP initialization, tool
listings, tool calls, agent intent, and failures. Leaving both absent disables analytics; a
partial configuration fails at startup rather than silently dropping events.

## Links

- Documentation — [docs.sentientx.io](https://docs.sentientx.io)
- Website — [sentientx.io](https://sentientx.io)

## License

Copyright © sentientx. All rights reserved. This is proprietary software; use is governed
by your agreement with sentientx.
