pyursa 1.0.0rc5__tar.gz

pyursa-1.0.0rc5/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install ruff -e ".[all]"
+      - run: ruff check src tests scripts benchmarks
+      - name: API reference is up to date
+        run: python scripts/gen_api_docs.py --check
+
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          allow-prereleases: true
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest -q
+      - name: End-to-end script
+        run: python scripts/e2e.py --rows 50000
+
+  minimum-versions:
+    name: test (oldest supported dependencies)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - run: pip install -c ci/constraints-min.txt -e . pytest numpy pandas polars duckdb mcp
+      - run: python -m pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check --strict dist/*
+      - name: Install the wheel in a clean environment and import it
+        run: |
+          python -m venv /tmp/clean
+          /tmp/clean/bin/pip install dist/*.whl polars
+          cd /tmp && /tmp/clean/bin/python -c "import pyursa as pu; print(pu.__version__, pu.from_dict({'a': [1]}).count())"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

pyursa-1.0.0rc5/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release
+
+# Publishes to PyPI when a GitHub release is published, using PyPI trusted publishing
+# (no API token stored in the repository). Configure the "pypi" environment and the
+# trusted publisher on PyPI first: https://docs.pypi.org/trusted-publishers/
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pyursa-1.0.0rc5/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+site/
+.env
+.DS_Store
+*.parquet
+!tests/data/*.parquet
+llm_cache*.sqlite

pyursa-1.0.0rc5/CHANGELOG.md

@@ -0,0 +1,153 @@
+# Changelog
+
+All notable changes are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and versions follow [SemVer](https://semver.org/).
+
+## [1.0.0rc5] - 2026-10-20
+
+### Fixed
+- Rate limits (HTTP 429): pyursa now waits as long as the provider asks (Google's `retryDelay` / "retry in Ns",
+  as well as `Retry-After`); a used-up daily quota fails at once instead of retrying for over a minute, with a
+  hint that the provider's quota, not pyursa, is the cause. `scripts/e2e.py` reports a provider quota as SKIP.
+- Provider error messages wrapped in a list (Gemini's OpenAI layer) or in `detail`/`errors` fields were
+  shown as a bare "Bad Request"; the provider's real message is now extracted.
+- Bad-key errors reported as HTTP 400 (xAI, Gemini) now get the "check your API key" hint.
+- `scripts/check_providers.py`: probes with real public model ids, says "needs settings" when an
+  account ID or workspace is missing, recognizes bad-key replies of any status, treats "model not found"
+  or "model retired" (HTTP 410) as a reachable endpoint, and checks that a local port really serves an OpenAI-compatible API.
+
+## [1.0.0rc4] - 2026-10-20
+
+### Added
+- Bedrock accepts AWS access keys without any SDK: `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`
+  (and `AWS_SESSION_TOKEN`), or `aws_access_key_id=` / `aws_secret_access_key=` / `aws_session_token=`.
+  Requests are signed with AWS Signature V4 using the standard library; signatures are tested
+  byte-for-byte against botocore. Works for `bedrock:` (Nova, Claude on AWS) and `bedrock-openai:`.
+- `profile=` for named AWS profiles (through boto3).
+
+## [1.0.0rc3] - 2026-10-20
+
+### Added
+- **53 OpenAI-compatible providers**, each checked against official docs: model vendors (OpenAI, Gemini,
+  Mistral, Cohere, Meta, xAI, DeepSeek, Qwen/DashScope, Kimi, GLM, MiniMax, Perplexity, AI21, Reka, Upstage),
+  hosts (Groq, Together, Fireworks, Cerebras, SambaNova, DeepInfra, Nebius, Novita, Baseten, OpenRouter,
+  Hugging Face, NVIDIA, Scaleway, OVHcloud), clouds (Azure, Vertex AI, Bedrock OpenAI, Databricks, Snowflake,
+  Cloudflare, Oracle OCI), gateways (LiteLLM, Portkey, Vercel, Helicone, Cloudflare AI Gateway) and local servers
+  (Ollama, LM Studio, vLLM, llama.cpp, LocalAI, Jan, TGI, SGLang, KoboldCpp, GPT4All).
+- `openai-compatible:` catch-all using `OPENAI_BASE_URL` / `OPENAI_API_KEY`.
+- Auth styles (Bearer, custom headers, Google OAuth with refresh), URL settings from environment variables
+  or keyword arguments, alternative key variables, `pu.print_providers()`, `scripts/check_providers.py`,
+  generated `docs/providers.md`.
+- Automatic `max_tokens` / `max_completion_tokens` negotiation.
+- Clear messages for retired services (GitHub Models, Hyperbolic, Lambda, Meta Llama API).
+
+### Fixed
+- Together AI's base URL moved to api.together.ai; DeepSeek's documented base URL is api.deepseek.com.
+- Default output limit lowered from 8192 to 4096 tokens, within every provider's cap.
+
+## [1.0.0rc2] - 2026-10-20
+
+### Added
+- `claude:` provider: Claude through Anthropic's OpenAI-compatible endpoint (no SDK). `anthropic:` falls
+  back to it automatically when the `anthropic` package isn't installed.
+- `bedrock:` works with just a Bedrock API key (`AWS_BEARER_TOKEN_BEDROCK`) over HTTPS, no boto3 needed;
+  covers Amazon Nova and Claude on AWS. Region from `AWS_REGION` or `region=`. Clear hints for
+  inference-profile ids and model access.
+- `bedrock-openai:` (Bedrock's OpenAI-compatible endpoint, for gpt-oss, Qwen, DeepSeek) with a guard that
+  redirects Nova/Claude/Llama to `bedrock:`; `litellm:` gateway preset; `headers=` on
+  `OpenAICompatibleClient`; `pu.list_providers()`.
+
+### Changed
+- Bedrock default `max_tokens` is 4096 (fits every Nova model).
+
+## [1.0.0rc1] - 2026-10-18
+
+Release candidate for 1.0. The public API described in `docs/stability.md` is frozen
+unless release-candidate feedback finds a problem.
+
+### Added
+- **Types:** exact `Decimal(p, s)` with defined arithmetic scales; time-zone-aware
+  `Datetime(tz)` with local-time `.dt` parts; `List`/`Struct` pass-through; dictionary
+  columns decode to `String`; type strings such as `"Decimal(12,2)"`.
+- **Expressions:** `when/then/otherwise`, `fill_null`, `coalesce`, `is_between`, `abs`,
+  `round` (half away from zero), string functions (`contains_regex`, `ends_with`, `strip`,
+  `len`, `replace`, `slice`), date functions (`year`…`second`, `weekday`, `date`, `truncate`).
+- **Aggregations:** `median`, `quantile`, `std`, `var`, `any`, `all`.
+- **Window functions:** aggregations `.over(partition)`, `row_number`, `rank`, dense rank,
+  `cum_sum`, `shift`, with deterministic tie order.
+- **Operations:** full, semi and anti joins; `distinct`; `concat`.
+- **I/O:** `write_parquet`, `write_csv`, `write_json`; `read_json`; multi-file, glob and
+  directory Parquet scans; `read_csv(schema=..., delimiter=...)`.
+- **LLM:** providers for OpenAI-compatible APIs (GPT, Gemini, Groq, Together, Mistral,
+  DeepSeek, xAI, OpenRouter, Ollama, LM Studio, vLLM) and Bedrock (Amazon Nova);
+  token usage and cost reports; token budgets; PII redaction; per-session LLM settings.
+- **MCP:** per-client session isolation (stdio and HTTP), `--host/--port`,
+  `--redact-pii`, `--llm-price`, `--llm-max-input-tokens`, `drop_frame` tool.
+- **Tools:** `distinct` and `concat` steps; glob/directory/JSON loading inside the sandbox;
+  `preview` returns exact numbers and JSON rows.
+- Agent benchmark harness (`benchmarks/agent_bench.py`), API reference generator,
+  docs site, CI matrix, security policy, Apache-2.0 license.
+
+### Changed
+- Renamed from the working name `agentframe` to **pyursa** (`import pyursa as pu`, `pyursa-mcp`,
+  `PyursaError`, reserved prefix `__pu_`).
+- Casts follow a strict contract: invalid text, non-whole floats to Int64, and casts without a
+  single meaning now raise errors (see docs/types.md).
+- `DType` is now a class (constants such as `pu.Int64` are unchanged).
+- DuckDB backend binds every user value as a query parameter.
+- DuckDB backend skips ordering work when a later step makes order irrelevant
+  (about 2.3× faster on the end-to-end pipeline).
+- CSV empty fields are read as null by default (`empty_as_null=False` restores `""`).
+
+### Fixed (independent pre-release review)
+- DuckDB resolved columns differing only by case (`A`, `a`) to the same column; such names are now rejected.
+- Paths containing `[`, `*` or `?` were globbed again after the sandbox check, which could read other files.
+- Engine panics (Rust `PanicException`) could escape `ToolSession` instead of returning an error.
+- Polars wrapped around on Int64 overflow; overflow now raises `INTEGER_OVERFLOW` on every engine.
+- Decimal literals written with an exponent (`1E+3`) lost the exponent on DuckDB.
+- Casts behaved differently per engine (float→int truncation vs rounding, text parsing); one strict
+  cast contract now applies everywhere, with `CAST_FAILED` errors.
+- NaN handling differed between engines and between DuckDB's in-memory and Parquet paths; NaN is
+  now the largest value and equal to itself everywhere.
+- Hour truncation of zoned datetimes on DuckDB was wrong across a DST fall-back.
+- Columns named with the internal `__pu_` prefix broke results; the prefix is now reserved.
+- Malformed LLM answers could crash a step; they now become null failures. Large integer answers are exact.
+- `is_in` failed on Polars for mixed numeric types; `is_in([])` of null now returns null everywhere.
+- Null-typed columns failed on DuckDB.
+- Several error `fix` snippets didn't work when pasted; literal values now print in parseable form.
+- Bad tool arguments returned `INTERNAL_ERROR`; they now return `BAD_ARGUMENTS`. More inputs are
+  validated when the plan is built (`head` bounds, `rename` values, `checkout` ids, token budgets).
+- Fixed-offset time zones (`+05:00`) failed on DuckDB; whole-hour offsets map to `Etc/GMT` zones.
+- Zoned literals at nonexistent local times (DST gaps) failed on Polars.
+- (Second review round) Engines expanded glob characters in already-resolved file paths, so a
+  sandboxed `data[1]/a.parquet` could read `data1/a.parquet`; files are now read literally.
+- (Second review round) DuckDB's optimizer could drop the overflow check when an Int64 result fed a
+  comparison; overflow is now checked explicitly.
+- (Second review round) std/var failed on DuckDB when a NaN was present; text casts disagreed on
+  `24:00`, leap seconds, year 0000 and rounding that adds a digit; non-portable regex (lookaround,
+  backreferences) is now rejected when the plan is built; error codes no longer depend on column names;
+  different `FunctionClient` functions no longer share cached answers; a literal file name such as
+  `x[1].parquet` is no longer treated as a pattern.
+
+### Fixed
+- Polars truncated decimal products (`1.15 × 1.15 → 1.32`); results are now exact everywhere.
+- Previews rounded floats to 4 significant digits.
+- Instruction-like text was only flagged when it appeared in displayed values; the whole
+  column is now scanned.
+- String values containing NUL bytes broke DuckDB queries.
+- Dates loaded from a persistent LLM cache came back as strings.
+- `frame.agg()` and `select()` didn't accept keyword names.
+- Some parser failures surfaced as raw Python exceptions instead of structured errors.
+
+## [0.4.0] - 2026-10-18
+- Multi-provider LLM clients; `pu.llm_client("provider:model")`.
+
+## [0.3.0] - 2026-10-18
+- `llm_filter`, `llm_map`, `llm_extract` with dedup, batching, caching and budgets.
+
+## [0.2.0] - 2026-10-18
+- MCP server and handle-based tool layer; safe expression parser.
+
+## [0.1.0] - 2026-10-18
+- Initial IR, Polars and DuckDB backends, structured errors, history, lineage,
+  explain, `describe_for_llm`.

pyursa-1.0.0rc5/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+## Setup
+
+```bash
+pip install -e ".[dev]"
+pytest                       # unit, conformance, provider and security tests
+python scripts/e2e.py        # end-to-end checks
+ruff check src tests scripts benchmarks
+```
+
+## Ground rules
+
+1. **Every behavior is the same on every backend.** If you add an operation, add a
+   case with explicit expected output to `tests/test_conformance*.py`. It must pass on
+   all backends unchanged. If engines disagree, pick a rule, document it in
+   `SEMANTICS` (`backends/base.py`) and make each backend follow it.
+2. **No silent coercion.** New types or casts must refuse lossy conversions.
+3. **Errors are for agents.** Raise an `PyursaError` subclass with a stable `code`,
+   machine-readable `details`, and at least one `suggestion` (with a `fix` snippet
+   when one exists). Catch mistakes when the plan is built, not at execution.
+4. **Untrusted input.** Anything reachable from `parse.py` or `tools.py` must be safe
+   for hostile input. Add a case to `tests/test_security.py`.
+5. **Public API changes** follow the stability policy in `docs/stability.md` and get a
+   `CHANGELOG.md` entry.
+
+## Adding a backend
+
+Subclass `pyursa.backends.Backend`, implement `compile(node)` and
+`_run(node) -> pyarrow.Table`, register it with `pu.register_backend`, and add its
+name to `BACKENDS` in `tests/conftest.py`. It is done when the conformance suites pass.

pyursa-1.0.0rc5/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

pyursa-1.0.0rc5/NOTICE

@@ -0,0 +1,4 @@
+pyursa
+Copyright 2026 The pyursa authors
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).

pyursa-1.0.0rc5/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: pyursa
+Version: 1.0.0rc5
+Summary: Engine-agnostic dataframes for agentic AI: strict types, identical results on Polars and DuckDB, structured errors, undo, lineage, LLM operators and an MCP server.
+Project-URL: Homepage, https://github.com/karawash-projects/pyursa
+Project-URL: Documentation, https://github.com/karawash-projects/pyursa/tree/main/docs
+Project-URL: Changelog, https://github.com/karawash-projects/pyursa/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/karawash-projects/pyursa/issues
+Author: The pyursa authors
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agents,arrow,data-engineering,dataframe,duckdb,llm,mcp,polars
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pyarrow>=15
+Provides-Extra: all
+Requires-Dist: duckdb>=1.2; extra == 'all'
+Requires-Dist: polars>=1.30; extra == 'all'
+Provides-Extra: bedrock
+Requires-Dist: boto3>=1.34; extra == 'bedrock'
+Provides-Extra: dev
+Requires-Dist: botocore; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: duckdb>=1.2; extra == 'dev'
+Requires-Dist: mcp>=1.21.1; extra == 'dev'
+Requires-Dist: numpy; extra == 'dev'
+Requires-Dist: pandas; extra == 'dev'
+Requires-Dist: polars>=1.30; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=1.2; extra == 'duckdb'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == 'llm'
+Provides-Extra: mcp
+Requires-Dist: duckdb>=1.2; extra == 'mcp'
+Requires-Dist: mcp>=1.21.1; extra == 'mcp'
+Requires-Dist: polars>=1.30; extra == 'mcp'
+Provides-Extra: polars
+Requires-Dist: polars>=1.30; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# pyursa
+
+**Engine-agnostic dataframes for the agentic AI era.** Named for *Ursa*, the bear, in the
+tradition of pandas and Polars. One strict, lazy API runs on
+Polars or DuckDB with identical results. The plan layer adds what AI agents need:
+structured errors with fixes, undo, lineage, dry runs, token-budgeted summaries,
+LLM-powered operators, and an MCP server.
+
+```python
+import pyursa as pu
+from pyursa import col
+
+orders = pu.read_parquet("orders/*.parquet")        # lazy
+print(orders.describe_for_llm(tokens=500))           # fits an LLM context window
+
+report = (orders
+    .filter(col("qty") > 0, col("status") != "cancelled", intent="valid orders only")
+    .with_columns(revenue=col("qty") * col("price"))
+    .group_by("region")
+    .agg(revenue=col("revenue").sum(), orders=pu.len(), p90=col("price").quantile(0.9))
+    .sort("revenue", descending=True))
+
+report.explain()            # dry run: schema, size bounds, compiled query
+report.collect("duckdb")    # pyarrow.Table, identical on "polars"
+report.undo(2); report.lineage("revenue"); report.write_parquet("report.parquet")
+```
+
+```python
+orders.filter(col("quantity") > "5")
+# [COLUMN_NOT_FOUND] Column 'quantity' not found in the input of this step.
+#   suggestion: Did you mean 'qty'?  ->  col("qty")
+```
+
+## Install
+
+```bash
+pip install "pyursa[all]"     # Polars + DuckDB backends
+pip install "pyursa[mcp]"     # + MCP server (pyursa-mcp)
+```
+
+Python 3.10+. From a source checkout: `pip install -e ".[dev]"`.
+
+## Highlights
+
+- **Same answers on every engine.** One semantics contract (nulls, NaN, sort stability,
+  rounding, decimals, casts, overflow, quantiles, window ties) enforced by conformance tests
+  on every backend. Float sums may differ in the last digits; everything else is identical.
+- **Strict types, no silent corruption.** Exact `Decimal(p,s)` math, time-zone-aware
+  `Datetime(tz)`, `List`/`Struct` pass-through, strict casts, integer overflow errors;
+  lossy inputs raise errors instead of corrupting data.
+- **Complete toolkit.** Filters, joins (inner, left, full, semi, anti), group-by with
+  median/quantile/std, window functions (rank, row_number, running totals, lag), `when/then`,
+  string and date functions, distinct, concat, Parquet/CSV/JSON in and out.
+- **Built for agents.** Errors are JSON with paste-ready fixes, raised before execution.
+  Immutable frames with `history()`/`undo()`, column `lineage()`, `explain()` dry runs, and
+  `describe_for_llm(tokens=N)` that always fits and flags prompt-injection text.
+- **LLM operators.** `llm_filter`, `llm_map`, `llm_extract` with **any major LLM**: 53
+  OpenAI-compatible providers (OpenAI, Gemini, Mistral, Cohere, xAI, DeepSeek, Qwen, Kimi, GLM,
+  Groq, Together, Fireworks, Azure, Vertex, Databricks, Snowflake, Cloudflare, OpenRouter, LiteLLM,
+  Ollama, vLLM, ...) plus native Claude and Amazon Bedrock (Nova, Claude on AWS). Dedup, batching,
+  caching, row/token budgets, cost reports and PII redaction included. See [providers](docs/providers.md).
+- **MCP server.** Handles instead of data, sandboxed files, a code-free expression parser,
+  per-client session isolation.
+- **Fast.** About 3–4× pandas on a typical analysis at 2M rows (see `scripts/e2e.py`).
+
+## Documentation
+
+[Guide](docs/guide.md) · [Types](docs/types.md) · [Agents and MCP](docs/agents.md) ·
+[LLM operators](docs/llm.md) · [LLM providers](docs/providers.md) · [Semantics](docs/semantics.md) · [API reference](docs/api.md) ·
+[Security](SECURITY.md) · [Stability policy](docs/stability.md) · [Changelog](CHANGELOG.md)
+
+## Testing
+
+```bash
+pytest                                    # unit, conformance, provider and security tests
+python scripts/e2e.py                     # end-to-end checks, including pandas comparison
+python scripts/e2e.py --llm gemini:<model>   # live LLM check with any provider
+python benchmarks/agent_bench.py --llm gemini:<model> --allow-code-exec   # agent benchmark
+```
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).