Metadata-Version: 2.5
Name: contextdb-cloud-client
Version: 0.2.0a1
Summary: Python SDK for persistent, action-aware memory in AI voice, support, and workflow agents
Project-URL: Homepage, https://github.com/atomsai/contextdb-clients
Project-URL: Repository, https://github.com/atomsai/contextdb-clients
Project-URL: Documentation, https://contextdb.ai/docs
Author-email: Atoms AI <gaurav@saaslabs.co>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent-memory,ai-agents,context,contextdb,llm,memory,voice-ai
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: pyyaml>=6; extra == 'dev'
Description-Content-Type: text/markdown

# ContextDB Cloud Python SDK for AI agent memory

Remote client for the ContextDB Cloud data plane. The hosted API and this
package are alpha and do not carry a production availability commitment.

```bash
pip install contextdb-cloud-client==0.2.0a1
```

## Correct, retract, or deduplicate memory

```python
from contextdb_cloud_client import CloudClient

async with CloudClient("https://api.contextdb.ai", api_key="cdb_…") as cdb:
    corrected = await cdb.evolve(
        "caller-1",
        "update",
        idempotency_key="call-456-correction-v1",
        target_memory_id=current_memory_id,
        content="My preferred visit day is Sunday.",
        source="user_stated",
    )
    retracted = await cdb.evolve(
        "caller-1",
        "delete",
        idempotency_key="call-456-retraction-v1",
        target_memory_id=obsolete_memory_id,
    )
    duplicate = await cdb.evolve(
        "caller-1",
        "noop",
        idempotency_key="call-456-duplicate-v1",
        noop_reason="duplicate",
    )
```

`EvolutionResult` exposes requested/applied operation, outcome, optional
memory, previous and deleted memory IDs, NOOP reason, `memory_version`,
`primary_wal_lsn`, and `request_id`. Target IDs are opaque; store and pass them
unchanged.

## Full memory lifecycle

```python
from contextdb_cloud_client import CloudClient

async with CloudClient("https://api.contextdb.ai", api_key="cdb_…") as cdb:
    saved = await cdb.remember(
        "caller-1", "Thursday works", source="user_stated",
        confidence=0.9, idempotency_key="call-456-preference-v1",
    )
    context = await cdb.recall(
        "caller-1",
        "when can they come in?",
        min_memory_version=saved.memory_version,
        min_primary_wal_lsn=saved.primary_wal_lsn,
    )
    decision = await cdb.evaluate_action("caller-1", "book the visit")
    if decision.outcome == "act":
        # Execute in your host, then close the Action Ledger.
        await cdb.report_execution(
            "caller-1", decision.decision_id, "appointment.book", "succeeded",
            idempotency_key=f"receipt-{decision.decision_id}",
            external_ref="appt-8842",
        )
    pending = await cdb.pending_confirmations("caller-1")

    # Hosted Alpha formation: enqueue, then poll.
    submitted = await cdb.submit_formation_job(
        "caller-1",
        [{"speaker": "user", "content": "I prefer Saturday mornings."}],
        mode="propose",
        idempotency_key="call-456-formation-v1",
    )
    formation = await cdb.get_formation_job(submitted.job_id)
```

`LocalClient` wraps the in-process memory calls for offline development.
Cloud-only control-plane features such as durable action decisions and
execution receipts require `CloudClient`.

The API key is a project-wide server credential (`cdb_…`). Keep it in your
server's secret store; never in a browser or client-side code.

Pass a stable `idempotency_key` to every `evolve` call and when retrying
`remember`, `remember_many`, `confirm`, or
`extract_memories(..., mode="commit")`. Reuse the key only for the exact same
logical request.
`submit_formation_job` always requires one. It accepts structured text turns
only; no audio or cancellation contract exists.

Delete one bad memory with `forget(user_id, memory_id=...)`. Whole-partition
erasure is deliberately harder: pass `erase_partition=True`,
`confirmation=user_id`, and an `idempotency_key`; Cloud deletes the partition
and verifies that no memory rows or vector-index IDs remain.

## Use cases

- **AI voice agents:** remember caller preferences and confirmed constraints
  across calls.
- **Customer support agents:** retrieve prior context while requiring trusted
  evidence before consequential actions.
- **Workflow agents:** record act/ask/abstain decisions and report execution
  outcomes.
- **Privacy operations:** delete one memory, a stable slot, or a complete user
  partition with verification.
- **Corrections:** UPDATE a known memory or stable slot while preserving
  previous IDs as lineage.
- **Retractions:** DELETE an opaque target or slot and inspect the returned
  deleted IDs.
- **Duplicates:** return an explicit NOOP reason instead of storing another
  copy.

Formation candidates and job reviews expose operation, target, server-derived
candidate key, operation results/counts, deleted IDs, and consistency tokens.
Legacy candidates with no operation are read as implicit ADD. Missing operation
results are never synthesized from memory IDs.

## Status and limitations

This is a thin Hosted Alpha transport. Formation accepts structured text turns
only; there is no audio upload, cancellation, job listing, retention API,
public availability SLO, or published hosted production proof. The package
contains no hosted planner, worker, tenancy, commit ledger, or recovery code.

## Python starter kits

- [OpenAI Agents SDK](https://github.com/atomsai/contextdb-clients/tree/main/starters/openai-agents-python)
- [LangGraph](https://github.com/atomsai/contextdb-clients/tree/main/starters/langgraph-python)
- [LiveKit Agents with PyAI speech](https://github.com/atomsai/contextdb-clients/tree/main/starters/livekit-agents-python)

Each starter installs this package and is checked against the documented
framework imports in CI.

## Links

- [API documentation](https://contextdb.ai/docs)
- [Memory Evolution in ContextDB SDK 0.4.1](https://github.com/atomsai/contextdb/blob/v0.4.1/docs/memory_evolution.md)
- [ContextDB SDK 0.4.1 package](https://pypi.org/project/pycontextdb/0.4.1/)
- [Source and examples](https://github.com/atomsai/contextdb-clients)
- [Open-source ContextDB engine](https://pypi.org/project/pycontextdb/)
- [Release notes](https://github.com/atomsai/contextdb-clients/releases)

## FAQ

### Which operation should I use?

Use ADD for a new durable fact, UPDATE for a correction, DELETE for an explicit
retraction, and NOOP for a duplicate or no durable change. UPDATE and DELETE
need an opaque target ID or an `entity`/`attribute` slot.

### Is `idempotency_key` optional for evolution?

No. The client validates the 8–128 character key before transport.

### Is this package production-ready?

No. `contextdb-cloud-client` and the hosted service are alpha. The package does
not claim a public availability SLA or hosted production proof.
