Metadata-Version: 2.4
Name: cometapi
Version: 0.1.0a1
Summary: Typed OpenAI-compatible Python client for the CometAPI gateway
Project-URL: Homepage, https://www.cometapi.com
Project-URL: Documentation, https://apidoc.cometapi.com/
Project-URL: Repository, https://github.com/cometapi-dev/cometapi-python
Project-URL: Issues, https://github.com/cometapi-dev/cometapi-python/issues
Project-URL: Support, https://github.com/cometapi-dev/cometapi-python/blob/main/SUPPORT.md
Project-URL: Security, https://github.com/cometapi-dev/cometapi-python/security/advisories/new
Author: CometAPI
License-Expression: MIT
License-File: LICENSE
Keywords: ai,cometapi,openai,sdk
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: openai<3.0.0,>=2.45.0
Description-Content-Type: text/markdown

# CometAPI Python SDK

> **Pre-release:** `0.1.0a1` is approved for PyPI publication. Its API may
> change before `0.1.0`.

`cometapi` is a thin Python adapter over the official OpenAI SDK for the
OpenAI-compatible CometAPI endpoint. It changes the default API key and base
URL configuration while preserving official OpenAI request, response, stream,
error, retry, timeout, proxy, and transport behavior.

## Supported 0.1 surface

| Operation | Synchronous | Asynchronous | Streaming |
| --- | --- | --- | --- |
| `chat.completions.create` | Yes | Yes | Yes |
| `responses.create` | Yes | Yes | Yes |
| `models.list` | Yes | Yes | Not applicable |

Only these operations are supported and contract-tested for 0.1. Other
resources inherited from the OpenAI client are not CometAPI support claims.
See [COMPATIBILITY.md](COMPATIBILITY.md) for the precise compatibility policy.

The package requires Python 3.10 or later and declares
`openai>=2.45.0,<3.0.0`.

Project links: [CometAPI](https://www.cometapi.com),
[API documentation](https://apidoc.cometapi.com/),
[source repository](https://github.com/cometapi-dev/cometapi-python), and
[issue tracker](https://github.com/cometapi-dev/cometapi-python/issues).

## Installation

Install the exact alpha from PyPI with:

```bash
python -m pip install --pre 'cometapi==0.1.0a1'
```

Check the repository releases and
[PyPI project page](https://pypi.org/project/cometapi/) for current package
availability.

## Authentication and configuration

Create an API key at <https://www.cometapi.com/console/token> and provide it
through the environment:

```bash
export COMETAPI_KEY="your-api-key"
```

You are responsible for all usage and charges incurred with your key. Never
commit a key, place one in an example, or include one in a bug report.

Configuration precedence is explicit constructor value, then environment
variable, then the default:

| Constructor option | Environment variable | Default |
| --- | --- | --- |
| `api_key` | `COMETAPI_KEY` | Required |
| `base_url` | `COMETAPI_BASE_URL` | `https://api.cometapi.com/v1` |

## Usage

### Chat Completions

```python
from cometapi import CometAPI

with CometAPI() as client:
    response = client.chat.completions.create(
        model="gpt-5.4",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response.choices[0].message.content)
```

Streaming uses the official OpenAI stream type:

```python
from cometapi import CometAPI

with CometAPI() as client:
    stream = client.chat.completions.create(
        model="gpt-5.4",
        messages=[{"role": "user", "content": "Write one sentence."}],
        stream=True,
    )
    for chunk in stream:
        print(chunk.choices[0].delta.content or "", end="")
```

### Responses and Models

```python
from cometapi import CometAPI

with CometAPI() as client:
    response = client.responses.create(
        model="gpt-5.4",
        input="Explain API compatibility in one sentence.",
    )
    models = client.models.list()

print(response.output_text)
print(models.data[0].id if models.data else "No models returned")
```

### Async client

```python
import asyncio

from cometapi import AsyncCometAPI


async def main() -> None:
    async with AsyncCometAPI() as client:
        response = await client.responses.create(
            model="gpt-5.4",
            input="Say hello.",
        )
        print(response.output_text)


asyncio.run(main())
```

The constructor exposes a named, typed option set: `api_key`, `admin_api_key`,
`organization`, `project`, `webhook_secret`, `base_url`,
`websocket_base_url`, `timeout`, `max_retries`, `default_headers`,
`default_query`, and the sync or async `http_client`. Configure proxies through
that documented custom HTTP client path. OpenAI provider routing and workload
identity are deliberately excluded because they replace CometAPI routing or
authentication; private underscore-prefixed OpenAI controls and arbitrary
keywords are rejected.

## Direct OpenAI interoperability

Applications may configure the official client directly when they do not need
the CometAPI-specific defaults:

```python
import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com/v1",
)
```

This is an interoperability option, not the primary `cometapi` experience.

## Explicit non-goals for 0.1

The alpha does not add Anthropic or Gemini adapters, CometAPI account or
platform resources, media APIs, provider-neutral message translation, CLI
behavior, or custom HTTP/SSE/retry implementations. There are no compatibility
aliases named `CometClient` or `AsyncCometClient`.

## Development

All commands run from this repository root:

```bash
uv sync --locked
uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv run pyright
uv run pytest -m "not live"
uv run python scripts/check_version.py --expected 0.1.0a1 --require-changelog
uv run python scripts/check_secrets.py
uv run python scripts/check_workflows.py
rm -rf dist
uv build
uv run twine check dist/*
uv run python scripts/check_artifacts.py dist/*
uv run python scripts/check_clean_install.py dist/*
uv run python scripts/check_repository_independence.py
uv run python scripts/run_actionlint.py
```

`actionlint` is static validation, not evidence that a workflow ran
successfully on GitHub. See [CONTRIBUTING.md](CONTRIBUTING.md) and
[RELEASING.md](RELEASING.md) for the contributor and release gates.

The scheduled/manual trusted smoke checks only the current default branch for
ongoing compatibility. It cannot validate or authorize a release. Publication
requires a separate protected live job that checks out the exact immutable
release commit after default-branch ancestry verification and must succeed
before the protected PyPI job becomes eligible.

## Support and security

Use the [issue tracker](https://github.com/cometapi-dev/cometapi-python/issues)
for reproducible SDK problems and `support@cometapi.com` for private support or
conduct reports. Use the
[private security advisory form](https://github.com/cometapi-dev/cometapi-python/security/advisories/new)
for vulnerabilities. [SUPPORT.md](SUPPORT.md) and [SECURITY.md](SECURITY.md)
define the corresponding scope and handling guidance.

## License

MIT. See [LICENSE](LICENSE).
