Metadata-Version: 2.4
Name: isa-common
Version: 0.6.14
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: pydantic>=2.0.0
Requires-Dist: rfc8785>=0.1.4
Requires-Dist: tenacity>=8.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: cryptography>=46.0.7
Provides-Extra: contracts
Provides-Extra: nats
Requires-Dist: nats-py>=2.6.0; extra == "nats"
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == "redis"
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29.0; extra == "postgres"
Provides-Extra: neo4j
Requires-Dist: neo4j>=5.0.0; extra == "neo4j"
Provides-Extra: s3
Requires-Dist: aioboto3>=13.0.0; extra == "s3"
Requires-Dist: aiofiles>=23.0.0; extra == "s3"
Provides-Extra: qdrant
Requires-Dist: qdrant-client>=1.10.0; extra == "qdrant"
Provides-Extra: falkordb
Requires-Dist: falkordb>=1.0.0; extra == "falkordb"
Provides-Extra: mqtt
Requires-Dist: aiomqtt>=2.0.0; extra == "mqtt"
Provides-Extra: local
Requires-Dist: aiosqlite>=0.19.0; extra == "local"
Requires-Dist: aiofiles>=23.0.0; extra == "local"
Requires-Dist: duckdb>=1.1.0; extra == "local"
Provides-Extra: http
Requires-Dist: aiohttp>=3.9.0; extra == "http"
Provides-Extra: consul
Requires-Dist: python-consul2>=0.1.5; extra == "consul"
Provides-Extra: grpc
Requires-Dist: grpcio>=1.50.0; extra == "grpc"
Requires-Dist: grpcio-tools>=1.50.0; extra == "grpc"
Provides-Extra: full
Requires-Dist: isa-common[consul,falkordb,grpc,http,local,mqtt,nats,neo4j,postgres,qdrant,redis,s3]; extra == "full"
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: isa-common[full]; extra == "dev"
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: wheel>=0.45.1; 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; python_version >= "3.10" and extra == "dev"
Requires-Dist: black==23.12.1; python_version < "3.10" and extra == "dev"
Requires-Dist: isort==8.0.1; python_version >= "3.10" and extra == "dev"
Requires-Dist: isort==5.13.2; python_version < "3.10" and extra == "dev"
Requires-Dist: ruff==0.15.13; extra == "dev"

# 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[full]"
```

The base package installs contracts and common utilities. Select drivers explicitly:

```bash
pip install "isa-common[contracts,nats]"  # IntegrationEvent contracts and NATS only
pip install "isa-common[redis]"          # Redis client
pip install "isa-common[local]"          # SQLite, files, and DuckDB
```

Existing consumers that use several infrastructure clients should switch their dependency to
`isa-common[full]`. Public client imports remain lazy and unchanged. A driver must be installed
before its client can be imported; installing the base package alone no longer installs every
database client. `full` preserves the previous driver dependency set; observability extras
remain separate.

Frappe v15 consumers should select `[contracts,nats]` so Redis and Boto versions remain governed
by Frappe. Do not select `[redis]`, `[s3]`, `[falkordb]` or `[full]` inside that Bench environment
unless their combined dependency constraints have been verified.

Run `bash scripts/test_lean_frappe_install.sh` from this package directory to verify a fresh
Python 3.12 install against pinned Frappe v15.109.0, including imports and dependency checks.

## 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 the default deterministic gate from the repository root. External service
tests require one explicit opt-in; endpoint variables configure the target but
do not enable a run by themselves:

```bash
# From the repository root
make test
ISA_COMMON_RUN_INTEGRATION=1 make test-service s=redis

# Optional Redis endpoint override
ISA_COMMON_RUN_INTEGRATION=1 REDIS_HOST=redis-service REDIS_PORT=6379 \
    make test-service s=redis
```

## 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
