ACI SDK Surfaces

Install and import

The packaged Python distribution exposes ACI Inference, ACI Personal Agents, ACI Edge Runtime, and the `aci`, `aci-mcp`, and `aci-inference-mcp` entry points. The legacy `aci.platform`, `aci.personal`, and `aci.runtime` imports remain supported.

pip install aci-engine

from aci.inference import ACIInferenceClient, ACIInferenceClientError
from aci.personal_agents import ACIPersonalAgentsSDK, PersonalAgentsConfig
from aci.edge_runtime import (
    ACIEdgeRuntime,
    EdgeConfig,
    build_native_runtime_artifacts,
    package_edge_embedder_release,
)

# Environment defaults used by ACIInferenceClient.from_env()
export ACI_BASE_URL="http://127.0.0.1:8000"
export ACI_API_KEY="your-key"
export ACI_TIMEOUT_SECS="30"

client = ACIInferenceClient.from_env()

What ships where

The same wheel exposes multiple Python surfaces, but the runtime destination is different for each product family. Use the wheel as the shipping artifact for local software, or as the build wrapper that produces the final native edge artifacts.

Inference client

`ACIInferenceClient` is the thin Python wrapper over the ACI Inference API. It exposes model registration, tenant lifecycle, the primary mutation verbs, health checks, and metrics.

from aci.inference import ACIInferenceClient

admin_client = ACIInferenceClient(
    base_url="http://127.0.0.1:8000",
    api_key="admin-key",
    timeout=30.0,
)
admin_client.create_tenant(
    model_id="support-assistant",
    tenant_id="tenant-a",
    target_dim=4,
    # controller_mode and other parameters configured per deployment
)

tenant_client = ACIInferenceClient(
    base_url="http://127.0.0.1:8000",
    api_key="tenant-key",
    timeout=30.0,
)

tenant_client.bind(
    {
        "model_id": "support-assistant",
        "tenant_id": "tenant-a",
        "namespace": "default",
        "write_memory": False,
        "items": [
            {
                "id": "faq-1",
                "input": "Refunds require proof of purchase.",
                "target": {"label": "policy_refund"},
                "tags": ["policy"],
            }
        ],
    }
)

result = tenant_client.infer(
    {
        "model_id": "support-assistant",
        "tenant_id": "tenant-a",
        "namespace": "default",
        "input": "What is the refund policy?",
        "use_memory": False,
    }
)

audit = tenant_client.audit(model_id="support-assistant", tenant_id="tenant-a")

Personal Agents SDK

`ACIPersonalAgentsSDK` is the local surface for desktop agents, laptops, and personal devices. It stores state locally, exposes explicit privacy operations, and supports snapshot or restore rather than remote tenant provisioning.

from aci.personal_agents import ACIPersonalAgentsSDK, PersonalAgentsConfig

config = PersonalAgentsConfig(
    device_id="phone-1",
    user_id="user-1",
    feature_dim=384,
    target_dim=4,
    db_path="personal.sqlite3",
    memory_enabled=True,
)

sdk = ACIPersonalAgentsSDK(config)
sdk.bind("sample-1", features, targets, tags=["profile"])
result = sdk.infer(features, x_raw="hello")
audit = sdk.audit()

snapshot = sdk.snapshot_bytes()
restored = ACIPersonalAgentsSDK(config)
restored.restore_snapshot_bytes(snapshot)

restored.forget_by_tag("profile")
report = restored.privacy_report()
restored.erase_profile()

Edge Runtime and packaging helpers

`ACIEdgeRuntime` is the compiled local runtime wrapper for `ACI Edge Runtime`. The packaging helpers build native artifacts and produce an embedder-facing release bundle.

from aci.edge_runtime import ACIEdgeRuntime, EdgeConfig

runtime = ACIEdgeRuntime(
    EdgeConfig(
        feature_dim=384,
        target_dim=4,
        max_samples=1000,
        max_memory_items=500,
    )
)

runtime.bind("sample-1", features, targets)
output = runtime.predict(features)
audit = runtime.audit()

from aci.edge_runtime import (
    build_native_runtime_artifacts,
    package_edge_embedder_release,
)

native_manifest = build_native_runtime_artifacts("build/native")
embedder_manifest = package_edge_embedder_release("build/embedder")

The runtime public surface includes bind, adapt, predict, constrain, unbind, audit, consolidate, and operating-envelope access. For control applications, enable safety enforcement with approved bounds.

Public boundary

• The SDK documentation covers public imports, configuration, and explicit operations only.
• It does not document controller internals, optimization details, signer internals, or other implementation-sensitive mechanisms.
• For cloud or on-prem service traffic, use the inference client. For device-local and desktop-agent state, use the Personal Agents SDK. For compiled edge deployment, use the Edge Runtime.