GSM Agent Kit

A toolkit for SIM-capable cellular devices and capability-based workflows, under development.

Public source, all rights reserved. See LICENSE and third-party notices.

Issue tracker · Project board · Contribution workflow

Workspace

libs/                 Independently packaged Python libraries
  core/               Domain and capability contracts
  gsm-agent/          Application workflows and CQRS
  integrations/       Cellular device, AI and storage integrations
  standard-tests/     Shared integration contract tests
  kit/                Optional installation bundles
apps/                 Server, CLI and browser UI
deploy/               Images, Compose profiles and host setup
examples/             SMS assistant and gateway examples
tests/e2e/            Assembled-system tests
.v0/                  Archived reference implementation

The Python workspace has 13 packages. Device inspection is implemented through core contracts, Mediary query handlers, Dishka composition, a simulated adapter and the model-specific ZTE MF833T HTTP adapter. Incoming SMS ingestion is implemented with source baselines, a SQLite ledger and durable events. Outgoing SMS submission has durable intent, per-part attempts and bounded plain-text preparation. OpenRouter replies use a durable queue and bounded persistent conversations. A capability-aware browser console operates these APIs. The ZTE assistant also has an adapter-specific container profile and an isolated hardware-free deployment smoke test. Remaining integrations are being built as implementation tickets. Each package owns its dependencies, README, source namespace, typing marker and tests.

New cellular-device adapters can inherit the shared contract test suite and supply a synthetic device fixture. Simulated and ZTE adapters run these common checks alongside their protocol tests; fixture success does not imply hardware verification.

The server reserves enabled SQLite ledgers with native OS locks before device access or restart recovery, preventing competing backends from sharing active local state. See ownership and deployment limits.

Run the first slice

uv run --package gsm-agent-server --extra simulated gsm-agent-server

Open http://127.0.0.1:8000/docs to list adapters, inspect demo-device and read its status. This profile performs no hardware access or outgoing SMS submissions. See server configuration and API examples.

For the attached ZTE MF833T, select its optional integration explicitly:

GSM_DEVICE__ADAPTER=zte-mf833t GSM_DEVICE__ID=zte-device \
  uv run --package gsm-agent-server --extra zte-mf833t gsm-agent-server

Inspect /api/devices/zte-device and /api/devices/zte-device/status. This profile reads model, firmware, hardware revision and network status. The host needs network access to the management interface, which defaults to http://192.168.0.1.

To enable durable incoming SMS polling:

GSM_DEVICE__ADAPTER=zte-mf833t GSM_DEVICE__ID=zte-device GSM_INBOX__ENABLED=true \
  uv run --package gsm-agent-server --extra zte-mf833t --extra inbox gsm-agent-server

Read /api/devices/zte-device/messages. The first scan records the existing inbox as backlog; later complete messages become eligible for processing. Auto-reply is disabled by default. See the server README for storage and subscription generation settings before replacing a SIM or device.

For manual SMS submission, add --extra sms and set GSM_SUBMISSIONS__ENABLED=true. POST /api/devices/zte-device/submissions accepts a client-generated UUID, international destination and text; a matching GET returns durable progress. See the server README for the request format and retry semantics. Sending has protocol-fixture coverage; live SMS verification is pending.

For OpenRouter replies, add --extra ai, enable GSM_ASSISTANT__ENABLED=true and configure GSM_ASSISTANT__API_KEY in your local environment. The assistant starts in dry-run mode. See the assistant setup for live sending, conversation retention, budgets and operator status.

Operator console

The browser console selects a logical device and displays capabilities, observed status, inbox, assistant mode and submission progress. With the backend running, use pnpm install --frozen-lockfile and pnpm web:dev from the repository root, then open http://127.0.0.1:5173. It uses the existing API and offers SMS/balance actions only when the adapter implements them. The SPA uses shadcn/ui and routed overview, inbox, workflow and device screens. pnpm web:dev also starts its tRPC WebSocket gateway for live inbox and reply updates. Proxy settings come from root .env; see the web README for defaults. pnpm is pinned in root package.json; no provider credentials go in the UI.

Containers

See container setup and host prerequisites for the ZTE MF833T assistant, runtime .env settings and persistent storage. The production console overlay starts the built browser UI and realtime gateway alongside it, using port 8080 for the browser and no published gateway port. Run the hardware-free deployment test without provider keys or a device:

python scripts/smoke_containers.py

Operator CLI

The query-only CLI inspects adapters, logical devices, status, background workers, stored inbox messages, assistant jobs and durable submission outcomes through the running backend API. It shares the root .env API token and adds GSM_CLI__API_URL (default http://127.0.0.1:8000) and GSM_CLI__TIMEOUT_SECONDS (default 35). Balance is an explicit query and reports unsupported capabilities without following carrier menus.

uv sync --locked --all-packages --all-extras
uv run --no-sync gsm-agent devices
uv run --no-sync gsm-agent runtime
uv run --no-sync gsm-agent status zte-device
uv run --no-sync gsm-agent inbox zte-device --limit 25

Success output is JSON; errors use stderr and documented exit codes. The CLI does not start services, send SMS, retry submissions or take device ownership.

Develop

uv sync --all-packages --all-extras
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run python scripts/run_tests.py
pnpm install --frozen-lockfile
pnpm web:generate-api
pnpm web:check
pnpm web:build
pnpm web:test

uv.lock coordinates local development. .v0 is excluded from workspace membership, linting and test discovery. Select a package when working on it, for example uv run --package gsm-agent-core python.

The gsm-agent-kit package declares installation extras: server, cli, zte-mf833t, inbox, sms, ai, zte-http, serial-at, modemmanager, langchain, and sqlite. zte-mf833t installs the server and model-specific adapter. The server also offers separate simulated, inbox, sms and ai extras. inbox and sms install the SQLite integration; ai adds SQLite and LangChain/OpenRouter. Combine them with a device profile. Other device integrations still select scaffold packages. No packages or images have been published.

See the proposed monorepo layout for the planned libraries, integrations, applications, and deployment structure.

The domain glossary defines the shared terminology. The cellular device interface proposal applies that language to capability contracts and records scenarios the new implementation must handle.

The original working draft is preserved in .v0/ as a reference for the new implementation. Its source, tests, scripts, dependency metadata, device investigations, and local configuration/data were archived together. The archived virtual environment may contain paths from its previous location; recreate it before attempting to run the draft from .v0.

Keep .v0 until the replacement covers the required behavior. It can then be removed explicitly. Local secrets, databases, and environments remain ignored.