Metadata-Version: 2.4
Name: sgrs-client
Version: 0.0.0
Summary: Python client for the SGRS governance platform — HTTP + optional NATS real-time events
Project-URL: Homepage, https://github.com/dealexmachina/sgrs
Project-URL: Documentation, https://sgrs.readthedocs.io
Project-URL: Repository, https://github.com/dealexmachina/sgrs
Author-email: Deal ex Machina SAS <contact@dealexmachina.fr>
License: MIT
License-File: LICENSE
Keywords: api,client,finality,governance,sgrs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: nats-py>=2.9.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=4.2.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=3.1.0; extra == 'docs'
Requires-Dist: sphinx<9,>=8.2.0; extra == 'docs'
Provides-Extra: nats
Requires-Dist: nats-py>=2.9.0; extra == 'nats'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# sgrs-client

Python HTTP client for the SGRS REST API.

## Installation

```bash
pip install sgrs-client
```

## Quick Start

### Async Usage

```python
import asyncio
from sgrs_client import create_client

async def main():
    client = create_client(base_url='http://localhost:3000')
    
    # Get a scope
    response = await client.get_scope('my-scope')
    if response.ok:
        print(f"Scope: {response.data}")
    else:
        print(f"Error: {response.error}")
    
    await client.close()

asyncio.run(main())
```

### Sync Usage

```python
from sgrs_client import create_client

client = create_client(base_url='http://localhost:3000')

# Get a scope
response = client.get_scope_sync('my-scope')
if response.ok:
    print(f"Scope: {response.data}")
else:
    print(f"Error: {response.error}")

client._sync_client.close()
```

### Context Manager

```python
import asyncio
from sgrs_client import create_client

async def main():
    async with create_client(base_url='http://localhost:3000') as client:
        response = await client.get_scope('my-scope')
        print(response.data if response.ok else response.error)

asyncio.run(main())
```

## Features

- **Type-safe**: All types validated with Pydantic models
- **Async-first**: Full async/await support with fallback to sync
- **Schema validation**: Runtime validation using models derived from Zod schemas
- **Error handling**: Structured error responses with detailed information
- **Timeouts**: Configurable request timeouts
- **SSL verification**: Configurable SSL certificate verification

## Scopes API

```python
# Get a scope
response = await client.get_scope('scope-id')

# Create a scope
response = await client.create_scope(
    name='My Scope',
    tag='tag',
    state='active',
    score=0.5,
    cycles=0
)

# Update a scope
response = await client.update_scope('scope-id', score=0.75)
```

## Models API

```python
from sgrs_client import ConnectModelRequest

# Connect a model provider
request = ConnectModelRequest(
    provider='openai',
    api_key='sk-...',
    model='gpt-4'
)
response = await client.connect_model(request)

# Get a connected model
response = await client.get_model('mh_xxx')
```

## Finality API

```python
# Get finality status
response = await client.get_finality_status('scope-id')

# Get finality certificate
response = await client.get_finality_certificate('scope-id', round=1)
```

## Documentation (Sphinx)

From the **repository root**, `pnpm docs:py` runs `scripts/docs-py.sh`, which maintains `packages/client-py/.venv` so installs work on PEP-668–managed Pythons:

```bash
pnpm docs:py
```

Generated HTML: `packages/client-py/docs/_build/html/` (Sphinx sources in `packages/client-py/docs/`).

## License

MIT - see LICENSE file
