ligaxai 0.1.0__tar.gz

ligaxai-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[codz]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+
+# Environments
+.venv/
+venv/
+.python-version.local
+
+# Secrets — examples read their key from the environment; never commit one
+.env
+.env.*
+!.env.example
+examples/**/.env
+examples/**/.env.*
+!examples/**/.env.example
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Synced spec (committed on purpose once SPEC_VERSION is set; nothing to ignore here)
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store

ligaxai-0.1.0/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-11-09
+
+First stable release.
+
+### Changed
+
+- **Docs: the README is rewritten as the user guide and PyPI page.** What you need and the
+  words it uses come first, then install, configure (both required variables), a complete
+  quickstart, common tasks, web apps, webhooks, reference tables and a section for AI coding
+  assistants. Every link is absolute (relative links break on PyPI), the CI badge points at
+  this repository, and contributor material moved to `CONTRIBUTING.md`.
+  `tests/unit/test_readme.py` checks that the examples parse and import only real names.
+  PyPI now lists Documentation and Issues links.
+- **Breaking: no built-in base URL.** `DEFAULT_BASE_URL` is removed. The API root comes from
+  `base_url=` or `LIGAX_BASE_URL` for every environment, production included; without one the
+  constructor raises the new `MissingBaseURLError` (`APIError` + `ValueError`) before any
+  request. The vendored spec's `servers` entry is the relative `/api/public/v1`, and
+  `scripts/sync_spec.py` rewrites it that way on each sync, so no deployment host ships in
+  the package or its docs.
+
+- CI runs on pushes to `main` and `dev` and ends in one `ci-gate` job for branch protection.
+  Pull requests from logins outside `.github/CONTRIBUTORS` are closed; issues stay open.
+- Spec pinned to `public-api-spec-v0.7.0`: a profile reports `tool_access` (`read_only`,
+  `read_write` or `custom`) and `approvals` (`server` or `end_users`).
+- **Security defaults.** `run_stream_route` needs `resolve_end_user` (or `allow_anonymous=True`)
+  and answers 401 without a signed-in user; it and `client_token_route` refuse cross-site requests
+  and no longer pass refusals about your own key to the browser (a generic 502 with the request id;
+  spend refusals keep their code). `webhook_dependency` reads at most 1 MB. A key with whitespace
+  is refused at construction; ids of `.`/`..` are refused; logs redact any LigaX key, client token
+  or webhook secret; a 409 is retried only when the API marks it retryable; oversized stream lines
+  and absurd text offsets are refused. Dependencies are bounded by their next major. The example
+  app takes its user from one replaceable `current_user()` and no longer exposes `keys.self()`.
+- Spec pinned to `public-api-spec-v0.6.0`. A run's `Idempotency-Key` replay that arrives while the
+  first request is still starting answers `409 idempotency_in_progress` with `x-should-retry: true`,
+  which the client retries. Run events are a safe subset: tool events carry name, status and
+  duration only, and `reasoning.delta` / `usage.delta` are no longer sent. Anonymous website visitors
+  can chat only; answering an approval with their token is `403 approval_not_allowed`.
+
+### Added
+
+- **Agent API v0.1** (`SPEC_VERSION` = `public-api-spec-v0.1.0`), identical on `LigaX` and
+  `AsyncLigaX`: `runs.create` / `wait` / `stream` / `get` / `events` / `follow_events` /
+  `cancel` / `resolve_interrupt`, `conversations.get`, `profiles.list` / `get`,
+  `keys.self`, `usage.get`. Response models are generated from the pinned spec and
+  re-exported in `ligaxai.types`.
+- `RunStream` / `AsyncRunStream` over the engine's LAE frames: `RunEvent(type, seq,
+  payload, run_id)`, `run_id` / `conversation_id` from `X-Run-Id` / `X-Conversation-Id`,
+  `last_seq` for resuming with `follow_events(after=)`, `text_stream()`, `final_text()`,
+  context-manager use; a JSON answer (idempotent replay) falls back to `stream.run`.
+- `TextAssembler`: offset-addressed text assembly in UTF-16 code units — replay-safe,
+  emits only new contiguous text, never splits a surrogate pair, answer in `part.start`
+  order.
+- `ligaxai.fastapi.run_stream_route()`: a server-side endpoint that streams a run to the
+  browser without exposing the key; `encode_run_event()`.
+- `gen_types.py --check` (in `make check` and CI): the generated models cannot drift from
+  `openapi/openapi.json`.
+- Conformance cases for `runs.create`, `runs.get` and a non-retried `402`; the harness
+  can assert a request count (`expect.requests`).
+- **Webhook endpoints** (scope `webhooks:manage`) on both clients:
+  `webhooks.create(url=, event_types=, description=, profile_ids=)` (returns the signing
+  `secret` once), `list`, `get`, `update` (only the fields given are sent), `delete`,
+  `test` (→ `WebhookDelivery`).
+- Typed webhook events, generated from the spec's top-level `webhooks` section:
+  `RunWebhookEvent` (`run.completed` / `failed` / `canceled` / `requires_action`),
+  `ApiKeyLimitWebhookEvent`, `WebhookTestEvent`; `UnknownWebhookEvent` for a type added
+  later. `webhooks.verify_signature()` and `webhooks.parse_event()`.
+- `ligaxai.fastapi.webhook_dependency(secret)`: verifies a request's raw body and yields the
+  typed event, or answers `400`.
+- **Browser access** (platform Phase 5): `client_tokens.create(profile_id=, end_user=,
+  conversation_id=, expires_in=)` on both clients mints a short-lived `lgx_ct_…` token for
+  one profile and one end user (scope `client_tokens:write`) → `ClientToken`. A client
+  constructed with a client token presents it as the bearer, for tests and tools acting as
+  the browser. `POST /widget/sessions` is browser-only and not mounted.
+- `ligaxai.fastapi.client_token_route(client, profile_id, resolve_end_user, expires_in=)`:
+  mints a token for the signed-in user (`None` → `401`) and returns `{token, expires_at}`
+  with `Cache-Control: no-store`.
+- `openapi/openapi.json` re-pinned with `/client_tokens` and `/widget/sessions`;
+  `ClientToken`, `ClientTokenCreateRequest`, `WidgetSession`, `WidgetSessionCreateRequest`
+  generated.
+- **End users' own accounts** (platform Phase 6; `SPEC_VERSION` = `public-api-spec-v0.3.0`)
+  on both clients: `connect_sessions.create(connector_key=, profile_id=, end_user=)`
+  (scope `connections:write`) → `ConnectSession` with the `connect_url` a browser opens in a
+  popup; `connect_sessions.get(session_id, end_user_id=)`; `connect_sessions.wait(...)`,
+  which polls every `poll_interval` (2 s) until the session leaves `pending` and raises
+  `TimeoutError` after `timeout` (600 s; `None` waits for the session's own expiry);
+  `end_users.connections.list(end_user_id)` → `EndUserConnectionList` and
+  `end_users.connections.delete(end_user_id, connection_id)` → `EndUserConnectionDeleted`.
+- `connection.created` / `connection.deleted` webhooks: subscribable through
+  `webhooks.create(event_types=)`, and `webhooks.verify()` returns the hand-written
+  `ConnectionCreatedWebhookEvent` / `ConnectionDeletedWebhookEvent` (the spec's `webhooks`
+  section does not describe their bodies yet).
+- **Files** (platform Phase 8; `SPEC_VERSION` = `public-api-spec-v0.5.0`) on both clients:
+  `files.create(file=, end_user_id=None)` uploads one file as multipart field `file` from a
+  path, bytes, a `(filename, bytes[, content_type])` tuple or a binary file object →
+  `FileObject`; a file over 25 MB raises `ValueError` before any request. `files.get` →
+  `FileObject`, `files.delete` → `FileDeleted`. `runs.create` / `wait` / `stream` take
+  `attachments=[file ids]` (up to 10).
+- `webhooks.create(idempotency_key=)`. Create was already sent with a minted
+  `Idempotency-Key`; the platform now honours it — a replay answers `200` +
+  `Idempotent-Replayed: true` with the same endpoint and secret, and a concurrent duplicate's
+  `409` + `x-should-retry: true` is retried by the existing policy.
+- README: a Files section and "Use from MCP / A2A clients" (Claude Code `claude mcp add`,
+  OpenAI Agents SDK `MCPServerStreamableHttp`, the A2A agent-card URL). The protocol
+  endpoints are generated into the models (`McpJsonRpcRequest`, `A2aJsonRpcRequest`) but not
+  mounted on a client — MCP and A2A client libraries speak them.
+- README: an end-user connections section with a FastAPI recipe (a route that starts a
+  connect session for the signed-in user and returns `connect_url`, plus a status route)
+  and the browser popup-and-poll flow.
+
+### Changed
+
+- `gen_types.py` generates into a temporary directory in both modes, so `--check` no longer
+  reports drift for a line between 88 and 100 columns that `make gen-types` wrote unsplit.
+- `webhooks.verify()` returns a typed event (dispatched on `type`) instead of the parsed
+  JSON, and reports a malformed signature header as `WebhookVerificationError`.
+- 422 is never retried (with 402 and 403), matching the TypeScript SDK.
+- `examples/fastapi-app` is a working sample: `/me`, `/ask` (`runs.wait`), `/chat`
+  (`run_stream_route`) and a one-file streaming chat page.
+
+### Removed
+
+- The template's example `health` resource (the Agent API has no `/health`).
+
+### Template baseline
+
+- Template skeleton: `LigaX` / `AsyncLigaX` clients with env-based
+  configuration, `with_options()`, context managers and `http_client` injection.
+- Request pipeline: bearer auth, `User-Agent`, `X-Request-Id` capture, auto
+  `Idempotency-Key` on POST, retries with `retry-after-ms` / `retry-after` / exponential
+  backoff and the `x-should-retry` override.
+- Typed exception hierarchy mapped from HTTP status and the JSON error envelope.
+- Vendored SSE parser with `Stream` / `AsyncStream`, event registry and `last_event_id`.
+- Cursor pagination (`SyncPage` / `AsyncPage`).
+- `webhooks.verify()` (Standard Webhooks) and optional `fastapi` helpers.
+- Conformance harness over `conformance/cases/*.json`, unit suite, CI matrix and PyPI
+  trusted-publishing release workflow.

ligaxai-0.1.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 LigaX AI authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.