Metadata-Version: 2.1
Name: isa-common
Version: 0.6.10
Summary: Shared Python infrastructure library for isA platform
Author-email: isA Platform <dev@isa-platform.com>
Project-URL: Homepage, https://github.com/isa-platform/isA_Cloud
Project-URL: Repository, https://github.com/isa-platform/isA_Cloud
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: grpcio >=1.50.0
Requires-Dist: grpcio-tools >=1.50.0
Requires-Dist: pydantic >=2.0.0
Requires-Dist: rfc8785 >=0.1.4
Requires-Dist: tenacity >=8.0.0
Requires-Dist: python-consul2 >=0.1.5
Requires-Dist: asyncpg >=0.29.0
Requires-Dist: neo4j >=5.0.0
Requires-Dist: aioboto3 >=13.0.0
Requires-Dist: aiofiles >=23.0.0
Requires-Dist: redis >=5.0.0
Requires-Dist: nats-py >=2.6.0
Requires-Dist: qdrant-client >=1.10.0
Requires-Dist: falkordb >=1.0.0
Requires-Dist: aiomqtt >=2.0.0
Requires-Dist: aiosqlite >=0.19.0
Requires-Dist: duckdb >=1.1.0
Requires-Dist: aiohttp >=3.9.0
Requires-Dist: pyyaml >=6.0
Requires-Dist: cryptography >=46.0.7
Provides-Extra: dev
Requires-Dist: build >=1.2.2 ; extra == 'dev'
Requires-Dist: jsonschema >=4.23.0 ; extra == 'dev'
Requires-Dist: pytest >=7.0.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio >=0.21.0 ; extra == 'dev'
Requires-Dist: mypy >=1.0.0 ; extra == 'dev'
Requires-Dist: black ==26.5.1 ; extra == 'dev'
Requires-Dist: isort ==8.0.1 ; extra == 'dev'
Requires-Dist: ruff ==0.15.13 ; extra == 'dev'
Provides-Extra: metrics
Requires-Dist: prometheus-client >=0.20.0 ; extra == 'metrics'
Requires-Dist: starlette >=0.27.0 ; extra == 'metrics'
Provides-Extra: observability
Requires-Dist: isa-common[metrics,tracing] ; extra == 'observability'
Provides-Extra: tracing
Requires-Dist: opentelemetry-sdk >=1.20.0 ; extra == 'tracing'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc >=1.20.0 ; extra == 'tracing'
Requires-Dist: opentelemetry-instrumentation-fastapi >=0.41b0 ; extra == 'tracing'
Provides-Extra: tracing-extras
Requires-Dist: opentelemetry-instrumentation-aiohttp-client >=0.41b0 ; extra == 'tracing-extras'
Requires-Dist: opentelemetry-instrumentation-asyncpg >=0.41b0 ; extra == 'tracing-extras'
Requires-Dist: opentelemetry-instrumentation-redis >=0.41b0 ; extra == 'tracing-extras'
Requires-Dist: opentelemetry-instrumentation-httpx >=0.41b0 ; extra == 'tracing-extras'

# isA Common

Shared async Python client library for the isA platform.

## Overview

`isa-common` provides async Python clients for interacting with isA Cloud infrastructure services. All clients use `async with` context managers and share a common base class (`AsyncBaseClient`).

### Infrastructure Clients (require running services)

| Client | Service | Default Port | Protocol |
|--------|---------|-------------|----------|
| `AsyncRedisClient` | Redis | 6379 | gRPC proxy |
| `AsyncPostgresClient` | PostgreSQL | 5432 | gRPC proxy |
| `AsyncNeo4jClient` | Neo4j | 7687 | gRPC proxy |
| `AsyncNATSClient` | NATS | 4222 | gRPC proxy |
| `AsyncMQTTClient` | MQTT | 1883 | gRPC proxy |
| `AsyncMinioClient` | MinIO | 9000 | gRPC proxy |
| `AsyncQdrantClient` | Qdrant | 6333 | gRPC proxy |
| `AsyncDuckDBClient` | DuckDB | embedded | native |

### Local-Mode Clients (no external services needed)

Drop-in alternatives for desktop/offline use. Same API surface, backed by local storage:

| Local Client | Replaces | Backed By |
|-------------|----------|-----------|
| `AsyncSQLiteClient` | `AsyncPostgresClient` | SQLite file |
| `AsyncLocalStorageClient` | `AsyncMinioClient` | Local filesystem |
| `AsyncChromaClient` | `AsyncQdrantClient` | ChromaDB (embedded) |
| `AsyncMemoryClient` | `AsyncRedisClient` | In-memory dict |

**When to use local clients:** Use local-mode clients when running on desktop/ICP without cloud infrastructure, for development/testing without Docker, or when you need offline-capable storage.

## Installation

```bash
pip install isa-common
```

## Quick Start

```python
from isa_common import AsyncRedisClient

async with AsyncRedisClient(host="localhost", port=6379, user_id="my-user") as client:
    health = await client.health_check()
    await client.set("key", "value")
    value = await client.get("key")
```

### Using Local-Mode Clients

```python
from isa_common import AsyncSQLiteClient, AsyncLocalStorageClient

# SQLite instead of PostgreSQL
async with AsyncSQLiteClient(database="app.db", user_id="my-user") as db:
    await db.query("SELECT * FROM users")

# Local filesystem instead of MinIO
async with AsyncLocalStorageClient(base_path="./storage", user_id="my-user") as storage:
    await storage.put_object("my-bucket", "file.txt", b"contents")
```

## Development

Run tests (requires services or use local clients):

```bash
# Run individual service tests
python tests/redis/test_async_redis.py
python tests/duck/test_async_duckdb.py

# Run all tests via Makefile
make test
```

## Contract Coverage

See [tests/contract_coverage.md](tests/contract_coverage.md) for the mapping between CDD contract IDs (BR/EC/ER) and test functions.

## License

Copyright © 2024 isA Platform
