Metadata-Version: 2.4
Name: flagqai
Version: 0.1.0a1
Summary: Python client for FlagQAI, the scientific discovery agent companion to FlagQuantum
Author: FlagQuantum Team
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# FlagQAI Python client

Connect Python workflows to **FlagQAI**, the scientific discovery agent companion
to FlagQuantum. This alpha client uses an existing FlagQAI deployment; it does
not install or run the agent backend.

## Install

```bash
python -m pip install flagqai==0.1.0a1
```

Python 3.10+; no third-party runtime dependencies. Python 3.12 is the tested
baseline for this preview. A compatible FlagQAI service and its login password
are required for authenticated operations.

## Connect

```python
from getpass import getpass
from flagqai import Client

with Client("https://your-flagqai-service.example") as client:
    print(client.health())
    client.login(getpass("FlagQAI password: "))
    print(client.me())
    catalog = client.capabilities()
    # manifest = client.task_manifest("your-existing-task-id")
    client.logout()
```

The URL is your deployment's API origin, without an API path. If the service's
allowed web origin differs, pass `origin="https://your-web-origin.example"`.
The server must allow this origin. HTTPS is required except for local loopback
development; production secure session cookies require HTTPS.

## Supported operations

| Method | Service operation |
| --- | --- |
| `health()` | Read `/healthz` |
| `login(password)` | Establish a web session |
| `me()` | Read authenticated identity and configuration status |
| `capabilities()` | Read the service capability catalog |
| `task_manifest(task_id)` | Read an existing task's manifest |
| `logout()` | Request logout and clear local cookies |

Methods return the server JSON object without rewriting evidence or capability
claims. `FlagQAIError.status_code` exposes HTTP failures; transport and JSON
errors have no status code. Error messages omit server bodies and credentials.

Cookies stay in memory. The client does not follow redirects, retry requests,
or submit compute/QPU jobs. Exiting the context clears local cookies, but does
not revoke server-side sessions. Do not share a client instance across threads.
The timeout is a per-socket timeout (default 30 seconds), not a total workflow
deadline. Responses larger than 8 MiB are rejected.

This preview targets the existing `/api/v1/web` session API. That API and this
alpha client may change before a stable release. Validation uses a local HTTP
fixture matching the inspected service routes; it is not live-service certification.

## Development

```bash
python -m pip install -e .
python -m unittest discover -s tests -v
```

Licensed under Apache-2.0.
