Metadata-Version: 2.4
Name: redis-agent-lens
Version: 0.1.0a2
Summary: Administrative and read API clients for Redis Lens
License: MIT
License-File: LICENSE
Author: Redis AI Services Team
Requires-Python: >=3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: httpcore (>=1.0.9)
Requires-Dist: httpx (>=0.28.1)
Requires-Dist: pydantic (>=2.11.2)
Project-URL: Documentation, https://pypi.org/project/redis-agent-lens/
Project-URL: Homepage, https://redis.io/docs/latest/develop/ai/
Project-URL: Repository, https://github.com/redis/iris-sdks.git
Description-Content-Type: text/markdown

# redis-agent-lens

Python management and read clients for Redis Lens. This alpha prerelease
contains the control-plane and data-plane REST APIs. Telemetry collection and
OTel instrumentation are owned by [redis-iris](https://github.com/redis/redis-iris).
This package does not import OpenTelemetry, initialize tracing, or export spans.

## Installation and status

Prepared version: `0.1.0a2`. Not published by this change.

```sh
pip install redis-agent-lens==0.1.0a2
```

Install after publication; pin alpha versions. Breaking changes may occur between
alpha releases. [Redis AI documentation](https://redis.io/docs/latest/develop/ai/)
and [package page](https://pypi.org/project/redis-agent-lens/).

## Two independently configured clients

`LensService` manages the deployment/account's singleton instance. `Lens` reads
one instance. Configure each URL and credential explicitly. Cloud instance responses include
endpoint candidates and accessibility metadata; select an appropriate endpoint
for the deployment. The package does not select an endpoint or mint a read key.

```python
from redis_agent_lens import Lens, LensService

with LensService(server_url=service_url, token=service_token) as service:
    instance = service.get_instance()

with Lens(server_url=read_url, instance_id=instance.instance_id, api_key=read_key) as lens:
    agents = lens.list_agents()
    sessions = lens.list_sessions(agent_id="support-bot", range="24h")
```

`LensService` has get/update instance and cloud-only register instance, list
databases, and get network info for control-plane egress allow-listing. Call
`list_databases()` once and select databases whose `eligible_roles` contain
`records` or `content`; the request takes no role filter. An empty role list
means the database is not ready or cannot fill either role. Records require a
Pro or Essentials RAM database; content can use RAM or Flex. Readiness and
control-plane accessibility are also returned; registration still performs live checks.
On-prem instances are provisioned at startup and have no registration or
discovery routes. Cloud responses include database bindings and endpoint
candidates; on-prem get/update responses omit them. Cloud get/update/register
and database discovery require the operator JWT, matching SM `JSESSIONID` cookie
and CSRF token. Use a session-aware transport/fetcher to supply these on every
request. Network info requires operator read authority.
Dependent-resource failures return a typed 424 error across all five management operations.

For cloud database selection:

```python
with LensService(server_url=service_url, token=service_token) as service:
    databases = service.list_databases().databases
    records_databases = [db for db in databases if "records" in db.eligible_roles]
```

`Lens` has list agents, list sessions, get session, get turn, get content, and
get Context Retriever result. `instanceId` is bound on the client. Session lists
require agent and range, support repeated outcome filters, and expose the opaque
next cursor without promising snapshot isolation. Preserve the filters across
pages. Session detail currently returns retained turn summaries together; the
server rejects sessions over its current 10,000-turn cap.

Turn IDs are OTel trace IDs. Turn detail includes component observations and
content references. Fetch content separately and inspect `availability` before
using its body: expired/not-captured/masked are valid states, not HTTP failures.
The wire envelope contains base64 bytes. The generated body representation is
shown in the operation/model reference; no implicit text or JSON parsing occurs.

## Credentials and transports

- DP accepts a Bearer instance key with `read` or `full`. Cloud UI reads also
  accept an SM JWT with Lens read authority and matching tenant; supply it via
  the same `api_key`/`apiKey` option. SM JWTs do not authorize OTLP ingest.
- CP uses `token`; its fallback is `LENS_SERVICE_TOKEN`.
- DP fallback is `LENS_API_KEY`. Neither client reads the existing
  instrumentation credential `IRIS_LENS_API_KEY` or falls back to the other plane.
- Clients support independent transports, callable credentials, timeouts, and
  explicit retry configuration. Retries are not enabled by default.
- CP models/errors live under `redis_agent_lens.controlplane`;
  DP models/errors retain their own namespace.

Python supports sync/async methods (async suffix `_async`), context managers, and caller-owned HTTP clients.
The SDK takes a service root. For a gateway that already inserts
`/v1/instances/<id>`, adapt its fetcher to avoid duplicating that prefix.

See DP operations and
CP operations.
Internal grant callbacks, Identity key lifecycle, OTLP ingestion, and planned
backend APIs are excluded. Use `redis-iris` for telemetry collection and instrumentation.

