missilya-sdk-sandbox

MISSILYA GROUP Sandbox SDK — the API-identical, deterministic, offline twin of missilya-sdk. It installs under the same import namespace (missilya_sdk), so application code switches between real and mock behavior by which package is installed, not by changing a single import.

• Package: missilya-sdk-sandbox · Import namespace: missilya_sdk
• Runtime: development & CI (mocks, no side effects)
• Python: 3.11 – 3.13
• Production twin: missilya-sdk

Status: private, under review. After approval it is published to the MISSILYA private pip registry alongside the core package.

---

Table of contents

1. What it is & why
2. Guarantees (forbidden behaviors)
3. Install
4. Usage (identical to core)
5. Deterministic behavior reference
6. Configuration
7. How apps swap core ⇄ sandbox by environment
8. Parity contract
9. Local development
10. Project layout

---

1. What it is & why

The sandbox lets developers and CI run application code safely and for free. It keeps the same imports, classes, functions, parameters, and return shapes as missilya-sdk, but instead of calling real providers it returns deterministic mocks. This means:

• Unit tests run with no network, no API cost, and no side effects.
• The same code that runs in production runs in tests — only the installed package differs — so tests written against the sandbox validate production logic.
• CI is fast and reproducible (fixtures are stable across runs).

	Sandbox SDK	Core SDK
Package	missilya-sdk-sandbox	missilya-sdk
Import	missilya_sdk	missilya_sdk (same)
Where	development / CI	staging / production
Behavior	deterministic mocks	real providers via vault
Network	never (default)	yes

---

2. Guarantees (forbidden behaviors)

The sandbox never:

1. uses a production vault environment (it raises if asked to);
2. uses a live credential (sk_live… / rk_live…) — it raises ValidationError;
3. creates a real charge;
4. sends a real email, SMS, or WhatsApp message;
5. requires internet access for default unit tests.

It does raise the same typed exceptions as the core SDK (ConfigurationError, ValidationError, ProviderError, …), so error-handling paths are exercised exactly as in production.

---

3. Install

pip install missilya-sdk-sandbox          # everything you need (offline)
pip install "missilya-sdk-sandbox[dev]"   # + pytest / ruff / mypy / build

The [ai], [payments], [notifications], [monitoring], [all] extras exist for parity with core (so requirements.txt matches), but they pull in nothing extra — the sandbox never needs a provider library.

requirements-dev.txt:

missilya-sdk-sandbox==0.1.0
pytest
pytest-asyncio
ruff
mypy

---

4. Usage (identical to core)

The exact same code you ship to production:

from missilya_sdk.ai.chat import LlmChat, SystemMessage, UserMessage

chat = LlmChat(model="gpt-4o")
chat.add_message(SystemMessage("Be concise."))
chat.add_message(UserMessage("Hello"))
print(chat.chat())          # -> "[sandbox:gpt-4o] Hello"   (deterministic)

from missilya_sdk.payments.stripe import StripeCheckout
from missilya_sdk.payments.checkout import CheckoutSessionRequest

session = StripeCheckout().create_session(CheckoutSessionRequest(
    line_items=[{"price": "price_x", "quantity": 1}],
    success_url="https://app/success",
    cancel_url="https://app/cancel",
))
assert session.url.startswith("https://checkout.sandbox.missilya.com/")  # mock, no charge

from missilya_sdk.notifications.email import send_email
result = send_email("user@example.com", "Hi", text="hello")
assert result.status == "logged"   # logged, never actually sent

from missilya_sdk.auth.jwt import create_token, verify_token
token = create_token({"sub": "u"})          # real HS256, offline, deterministic
assert verify_token(token)["sub"] == "u"

---

5. Deterministic behavior reference

Call	Sandbox result
LlmChat(...).chat()	"[sandbox:<model>] <last user message>" (stable echo)
LlmChat(...).complete()	ChatResponse with computed token counts, raw={"sandbox": True}
generate_image(...)	ImageResult(url="https://sandbox.missilya.com/fixtures/image.png")
text_to_speech(...)	SpeechResult(audio=<fixture bytes>)
speech_to_text(...)	TranscriptResult(text="This is a sandbox transcript fixture.")
translate("hi", "FR")	TranslationResult(text="[FR] hi")
generate_video(...)	VideoJob(status="queued", job_id="sandbox-video-…")
StripeCheckout().create_session(...)	mock cs_sandbox_… session, payment_status="unpaid"
StripeCheckout().handle_webhook(payload, sig)	parses JSON payload, no signature check
send_email/sms/whatsapp(...)	DeliveryResult(status="logged"/"queued"), only logged
auth.jwt.*	real HS256 round-trips (offline, deterministic)

Auth uses real JWT crypto (deterministic and offline); everything else is a fixture.

---

6. Configuration

The sandbox resolves config offline:

1. process environment variable (development/test values only)
2. caller-supplied default
3. deterministic fixture sandbox-<key> (so a missing secret never crashes a test)

Guards:

• MISSILYA_ENV=production → the sandbox refuses to run (ConfigurationError).
• A live credential in the environment (sk_live…) → ValidationError.

# Optional; the sandbox works with no env at all.
MISSILYA_ENV=development
OPENAI_API_KEY=          # test keys only, never sk_live_...
JWT_SECRET=

See .env.example.

---

7. How apps swap core ⇄ sandbox by environment

Pin different packages per environment — the import never changes:

# requirements.txt          (staging / production)
missilya-sdk[ai,payments,notifications,monitoring]==0.1.0

# requirements-dev.txt      (development / CI)
missilya-sdk-sandbox==0.1.0

# app code — identical everywhere
from missilya_sdk.ai.chat import LlmChat, UserMessage

CI installs the sandbox and runs the suite offline; staging/production installs the core package and runs against the real vault and providers.

---

8. Parity contract

The sandbox and core must expose an identical public API for the same version:

• same import namespace (missilya_sdk),
• same public modules, classes, functions,
• same function / __init__ parameter names,
• same return shapes and dataclass fields,
• same typed exceptions,
• same version string (0.1.0).

This is verified statically by repos/sdk-tools/check_sdk_parity.py (AST-based, no install required) and enforced as a test. A feature cannot be added to core without matching sandbox behavior, and vice versa.

---

9. Local development

python -m venv .venv
./.venv/Scripts/python -m pip install -e ".[dev]"   # Windows
# source .venv/bin/activate && pip install -e ".[dev]"   # macOS/Linux

ruff check src tests tools
mypy src/missilya_sdk
pytest -q
python -m build && twine check dist/*

---

10. Project layout

src/missilya_sdk/
├── __init__.py            # public top-level exports (mirrors core)
├── config.py              # offline config; refuses production + live keys
├── context.py             # TenantContext, MissilyaSDK facade
├── exceptions.py          # identical typed error hierarchy
├── ai/                    # chat (deterministic), images, tts, stt, translation, video, _fixtures
├── payments/              # stripe (mock), checkout models
├── notifications/         # email, sms, whatsapp (logged only)
├── auth/                  # jwt (real HS256, offline)
├── vault/                 # offline VaultClient (fixtures, no network)
└── monitoring/            # logging shim, analytics, sentry (no-op)
tests/                     # determinism + no-side-effect + parity tests
tools/check_forbidden_imports.py
.github/workflows/         # test, publish, docker-publish
Dockerfile · repo.classification.yml · .env.example

---

License

Proprietary — © 2026 MISSILYA GROUP. See LICENSE. Private to MISSILYA GROUP; redistribution requires written authorization from Yvon Kamach (CEO).