From 7cefa5b19f60ecd6dcc85849afe85720f12749c7 Mon Sep 17 00:00:00 2001 From: William Fawcett Date: Fri, 1 May 2026 10:36:09 +0100 Subject: [PATCH 1/3] Add MIT LICENSE and CONTRIBUTING.md Establishes licensing terms and contributor guidelines so external users have clear expectations for reuse and PR conventions. --- CONTRIBUTING.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++ LICENSE | 21 ++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..90f41bf --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# Contributing to eve-api + +Thank you for your interest in contributing! `eve-api` is a minimal +authenticated HTTP client for the EVE (Earth Virtual Expert) API. See +the [README](README.md) for what the project does and how to use it. + +## Development setup + +Follow the [Installation](README.md#installation) section of the +README, then install the pre-commit hooks: + +```bash +poetry run pre-commit install +``` + +## Code quality + +Pre-commit runs black, isort, autoflake, mypy, pylint, detect-secrets, +and pytest with coverage. Run the full suite locally before pushing: + +```bash +poetry run pre-commit run --all-files +``` + +If a hook fails, fix the underlying issue rather than bypassing the +hook. If `detect-secrets` flags a false positive, update the baseline: + +```bash +poetry run detect-secrets scan --baseline .secrets.baseline +``` + +## Testing + +```bash +poetry run pytest +``` + +Tests use [`respx`](https://lundberg.github.io/respx/) to mock the EVE +API, so no live credentials are required. New behaviour should ship +with tests, and coverage is expected to stay at 100%. + +## Pull requests + +- Fork the repo and branch off `main`. +- Use a short branch prefix: `feat/`, `fix/`, `docs/`, or `chore/` etc. +- Keep each PR focused on one logical change. +- In the PR description, explain *what* changed and *why*, and link + any related issue. +- Commit messages: imperative mood, focused on the *why*. +- Be ready to iterate on review feedback. + +## Reporting issues + +Open a [GitHub issue](https://github.com/FrontierDevelopmentLab/eve-api/issues) +with: + +- steps to reproduce, +- expected vs actual behaviour, +- your environment (Python version, OS, relevant package versions). + +## For maintainers + +Maintainers can push branches directly to the repo; the same branch +naming, PR, and review expectations apply. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..b9b1854 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Trillium Technologies Ltd. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. From b3bc762e61acec097e6a9f7b79b3f6d8ac02fde2 Mon Sep 17 00:00:00 2001 From: William Fawcett Date: Fri, 1 May 2026 10:47:11 +0100 Subject: [PATCH 2/3] Improve instructions, add acknowledgements --- README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 67 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 2799742..2ced820 100644 --- a/README.md +++ b/README.md @@ -4,17 +4,16 @@ [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://github.com/FrontierDevelopmentLab/eve-api) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) -Minimal authenticated HTTP client for the EVE (Earth Virtual Expert) API. +EVE-API is a minimal authenticated HTTP client for EVE (Earth Virtual Expert). +It provides login, automatic JWT token refresh, and generic HTTP methods that return plain dicts. There are no domain-specific wrappers or Pydantic models. -Provides login, automatic JWT token refresh, and generic HTTP methods that return plain dicts. No domain-specific wrappers or Pydantic models. -## Installation +EVE-API is part of an initiative by [Trillium Technologies](https://trillium.tech/) and ESA to +realize the vision of Earth system predictability (ESP). +You can read about the ESP vision [here](https://eslab.ai/esp). - + +## Installation For the development version: ```bash @@ -25,6 +24,8 @@ or pip install -e ".[dev]" ``` +Supported Python versions: 3.11–3.14. + ## Usage ```python @@ -55,10 +56,66 @@ async with EVEClient() as eve: print(eve.auth_headers) ``` +## Configuration + +`EVEClient` is configured via constructor arguments — no environment +variables are read. + +| Argument | Default | Purpose | +| --- | --- | --- | +| `base_url` | `https://api.eve-chat.chat` | Base URL of the EVE API. | +| `timeout` | `30.0` | Default request timeout in seconds. Per-call timeouts can be passed to individual methods. | + +## Authentication + +`login()` exchanges email/password for a JWT access token and a +refresh token. Tokens are held in memory on the client instance. + +Before every authenticated request, the client refreshes the access +token if it is within 5 minutes of expiry (default expiry: 1 hour); +refresh is lazy, not background. If the refresh token itself has +expired, `TokenExpiredError` is raised and the caller must call +`login()` again. + +For unauthenticated endpoints, pass `auth_required=False` to +`request()`. + +## Examples + +See [`examples/quickstart.py`](examples/quickstart.py) for a runnable +script and [`examples/tutorial.ipynb`](examples/tutorial.ipynb) for a +notebook walk-through. + +## Errors + +All errors derive from `EVEError`. Common subclasses exported from +`eve_api`: `AuthenticationError`, `NotAuthenticatedError`, +`TokenExpiredError`, `APIError`, `NotFoundError`, `ForbiddenError`, +`ValidationError`, `ServerError`, `StreamError`. + ## Running tests ```bash -cd eve-api -pip install -e ".[dev]" pytest ``` + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, +pre-commit hooks, and PR conventions. + +## Acknowledgements + +Originally created by the GeoSTARS (STARS: Scientific Testing of Agentic Reasoning) team: +([Raúl Ramos](https://github.com/rramosp), [James Walsh](https://github.com/dead-water), +[Will Fawcett](https://github.com/will-fawcett), and [Russell Spiewak](https://github.com/r-spiewak)). +Supported by the ESA Phi-Lab as part of Trillium Technologies Earth Systems Lab [ESL](https://eslab.ai/). + + +## License + +MIT licensed. See [LICENSE](LICENSE) for the full text. + +## Copyright + +© 2026 Trillium Technologies Ltd. From 0181f8cd2e2ed5f0cfda42c4e7d7278654c5d208 Mon Sep 17 00:00:00 2001 From: William Fawcett Date: Fri, 1 May 2026 15:18:31 +0100 Subject: [PATCH 3/3] Authors --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2ced820..bcf7489 100644 --- a/README.md +++ b/README.md @@ -107,8 +107,12 @@ pre-commit hooks, and PR conventions. ## Acknowledgements Originally created by the GeoSTARS (STARS: Scientific Testing of Agentic Reasoning) team: -([Raúl Ramos](https://github.com/rramosp), [James Walsh](https://github.com/dead-water), -[Will Fawcett](https://github.com/will-fawcett), and [Russell Spiewak](https://github.com/r-spiewak)). +( + [James Walsh](https://github.com/dead-water), + [Russell Spiewak](https://github.com/r-spiewak), + [Will Fawcett](https://github.com/will-fawcett), + and [Raúl Ramos](https://github.com/rramosp) + ). Supported by the ESA Phi-Lab as part of Trillium Technologies Earth Systems Lab [ESL](https://eslab.ai/).