Metadata-Version: 2.4
Name: isa-common
Version: 0.6.0
Summary: Shared Python infrastructure library for isA platform
Home-page: https://github.com/isa-platform/isA_Cloud
Author: 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: 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.9.0
Requires-Dist: falkordb>=1.0.0
Requires-Dist: aiomqtt>=2.0.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: duckdb>=0.10.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: metrics
Requires-Dist: prometheus-client>=0.20.0; extra == "metrics"
Requires-Dist: starlette>=0.27.0; extra == "metrics"
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"
Provides-Extra: observability
Requires-Dist: isa-common[metrics,tracing]; extra == "observability"
Provides-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"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# 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
