aegro 0.2.0__tar.gz

aegro-0.2.0/.gitignore

@@ -0,0 +1,37 @@
+# Environment & secrets
+.env
+.env.*
+!.env.example
+.farms.json
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+aegro/_version.py
+*.egg
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Virtual environments
+.venv/
+venv/
+
+# Git worktrees
+.worktrees/

aegro-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aegro
+
+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.

aegro-0.2.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: aegro
+Version: 0.2.0
+Summary: CLI for Aegro agricultural management API
+Project-URL: Homepage, https://github.com/aegro/tool-aegro-cli
+Project-URL: Repository, https://github.com/aegro/tool-aegro-cli.git
+Project-URL: Issues, https://github.com/aegro/tool-aegro-cli/issues
+Project-URL: Changelog, https://github.com/aegro/tool-aegro-cli/releases
+Author-email: Aegro Engineering <pedro@aegro.com.br>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agriculture,api-client,cli,farm-management,typer
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: structlog>=24.0.0
+Requires-Dist: typer[all]>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.34.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Aegro CLI
+
+Command-line interface for the [Aegro](https://aegro.com.br) agricultural management API.
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/aegro.svg)](https://pypi.org/project/aegro/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Install
+
+```bash
+# pipx (recommended)
+pipx install aegro
+
+# uv
+uv tool install aegro
+
+# Homebrew (macOS)
+brew tap aegro/tap
+brew install aegro
+```
+
+For development:
+
+```bash
+git clone https://github.com/aegro/tool-aegro-cli.git
+cd tool-aegro-cli
+uv sync
+uv run aegro --help
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Authenticate
+aegro auth login --farm-name "Fazenda Sul" --api-key "aegro_abc123..."
+
+# 2. Select a farm
+aegro farms list
+aegro farms select "Fazenda Sul"
+
+# 3. Start working
+aegro crops list --start-date 2025-01-01 --end-date 2025-12-31
+aegro financial installments --status PENDING
+aegro stock items --output table
+```
+
+---
+
+## Commands
+
+| Group | Commands | Domain |
+|-------|----------|--------|
+| `auth` | login, status, logout | Authentication |
+| `farms` | list, select, info | Farm management |
+| `crops` | get, list, prorate, harvest-discounts, prorates, glebes | Harvest management |
+| `activities` | get, list, plan, realizations, get-plan, get-realization, create-plan | Activity planning |
+| `financial` | bill, installment, installments, create/update/delete-installment, realize | Accounts payable/receivable |
+| `stock` | item, location, items, locations, logs, log, transfer, entry, removal | Inventory |
+| `elements` | get, list, create-defensive/fertilizer/item/seed/service, set-categories | Inputs/supplies |
+| `assets` | get, list, create-machine/vehicle/garner/immobilized/pivot/weather-station | Equipment |
+| `fuel-supplies` | get, list, create, update | Fuel management |
+| `maintenances` | get, list, create, update | Maintenance records |
+| `harvest-logs` | get, create | Harvest records |
+| `bank-accounts` | get, list, create | Bank accounts |
+| `companies` | get, list, create | Suppliers/vendors |
+| `fin-categories` | get, list, create, subcategories | Chart of accounts |
+| `catalogs` | list, element-keys, elements | Catalog lookups |
+| `tags` | get, list, create | Tags/labels |
+| `weather` | get, create | Weather data |
+| `purchase-orders` | get, list, create | Purchase orders |
+| `glebes` | get, list | Farm fields |
+| `crop-glebes` | get, list | Crop fields |
+
+---
+
+## Output Formats
+
+All commands support three output formats:
+
+```bash
+aegro crops list --output json    # JSON (default, for LLMs/scripts)
+aegro crops list --output table   # Rich table for humans
+aegro crops list --output csv     # CSV export
+```
+
+---
+
+## Usage Examples
+
+### Human workflow
+
+```bash
+# Morning overview
+aegro farms select "Fazenda Norte"
+aegro crops list --output table
+aegro financial installments --status PENDING --due-date-start 2025-03-01 --output table
+aegro stock items --output table
+
+# Register a fuel supply
+aegro fuel-supplies create --asset-key K --date 2025-03-13 --quantity 150 --unit L --cost 900
+
+# Check harvest
+aegro harvest-logs get <key>
+```
+
+### LLM/Agent workflow
+
+```bash
+# Agents use JSON output (default) for structured data
+aegro crops list --start-date 2025-01-01 --end-date 2025-12-31
+aegro activities list --crop-key <key>
+aegro stock items
+aegro financial installments --status PENDING
+```
+
+---
+
+## AI Skills
+
+The project includes guided workflows for AI assistants in `.claude/skills/`:
+
+### Domain skills (personas)
+
+| Skill | Purpose |
+|-------|---------|
+| `aegro-agronomo` | Agronomic domain — crops, fields, activities, harvests, weather, inputs |
+| `aegro-estoquista` | Stock domain — items, locations, movements, catalogs, elements |
+| `aegro-financeiro` | Financial domain — bills, installments, categories, bank accounts, companies |
+| `aegro-operacional` | Operational domain — farms, auth, tags, cross-domain orchestration |
+| `aegro-patrimonial` | Asset domain — machines, vehicles, fuel supplies, maintenances |
+
+### Workflow skills
+
+| Skill | Purpose |
+|-------|---------|
+| `aegro-visao-geral` | Farm overview dashboard |
+| `aegro-fechamento-safra` | Crop season closing checklist |
+| `aegro-lancamento-financeiro` | Financial entry guide |
+| `aegro-reconciliacao-estoque` | Stock reconciliation |
+| `aegro-monitoramento-pragas` | Pest monitoring |
+| `aegro-analise-rentabilidade` | Profitability analysis |
+| `aegro-cadastro-patrimonio` | Asset registration |
+
+---
+
+## Configuration
+
+### Authentication
+
+Credential resolution priority:
+
+1. `AEGRO_FARMS` env var (JSON) — for CI/CD and scripts
+2. `AEGRO_FARMS_FILE` env var (path) — for Docker/K8s secrets
+3. `~/.config/aegro/credentials.json` — interactive setup via `aegro auth login`
+
+```bash
+# Option 1: Environment variable
+export AEGRO_FARMS='{"Fazenda Norte": "aegro_key1", "Fazenda Sul": "aegro_key2"}'
+
+# Option 2: Interactive login (saves to ~/.config/aegro/credentials.json)
+aegro auth login --farm-name "Fazenda Norte" --api-key "aegro_key1"
+```
+
+### Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `AEGRO_API_BASE_URL` | `https://app.aegro.com.br` | Aegro API base URL |
+| `AEGRO_FARMS` | — | JSON map of farm name → API key |
+| `AEGRO_FARMS_FILE` | — | Path to JSON credentials file |
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest -v
+
+# Lint
+uv run ruff check aegro/ tests/
+
+# Format
+uv run ruff format aegro/ tests/
+```
+
+---
+
+## Links
+
+- [Aegro](https://aegro.com.br) — Agricultural management platform
+- [Typer](https://typer.tiangolo.com/) — CLI framework
+- [PyPI: aegro](https://pypi.org/project/aegro/) — Package page
+
+---
+
+## License
+
+[MIT](LICENSE)

aegro-0.2.0/README.md

@@ -0,0 +1,207 @@
+# Aegro CLI
+
+Command-line interface for the [Aegro](https://aegro.com.br) agricultural management API.
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/aegro.svg)](https://pypi.org/project/aegro/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Install
+
+```bash
+# pipx (recommended)
+pipx install aegro
+
+# uv
+uv tool install aegro
+
+# Homebrew (macOS)
+brew tap aegro/tap
+brew install aegro
+```
+
+For development:
+
+```bash
+git clone https://github.com/aegro/tool-aegro-cli.git
+cd tool-aegro-cli
+uv sync
+uv run aegro --help
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Authenticate
+aegro auth login --farm-name "Fazenda Sul" --api-key "aegro_abc123..."
+
+# 2. Select a farm
+aegro farms list
+aegro farms select "Fazenda Sul"
+
+# 3. Start working
+aegro crops list --start-date 2025-01-01 --end-date 2025-12-31
+aegro financial installments --status PENDING
+aegro stock items --output table
+```
+
+---
+
+## Commands
+
+| Group | Commands | Domain |
+|-------|----------|--------|
+| `auth` | login, status, logout | Authentication |
+| `farms` | list, select, info | Farm management |
+| `crops` | get, list, prorate, harvest-discounts, prorates, glebes | Harvest management |
+| `activities` | get, list, plan, realizations, get-plan, get-realization, create-plan | Activity planning |
+| `financial` | bill, installment, installments, create/update/delete-installment, realize | Accounts payable/receivable |
+| `stock` | item, location, items, locations, logs, log, transfer, entry, removal | Inventory |
+| `elements` | get, list, create-defensive/fertilizer/item/seed/service, set-categories | Inputs/supplies |
+| `assets` | get, list, create-machine/vehicle/garner/immobilized/pivot/weather-station | Equipment |
+| `fuel-supplies` | get, list, create, update | Fuel management |
+| `maintenances` | get, list, create, update | Maintenance records |
+| `harvest-logs` | get, create | Harvest records |
+| `bank-accounts` | get, list, create | Bank accounts |
+| `companies` | get, list, create | Suppliers/vendors |
+| `fin-categories` | get, list, create, subcategories | Chart of accounts |
+| `catalogs` | list, element-keys, elements | Catalog lookups |
+| `tags` | get, list, create | Tags/labels |
+| `weather` | get, create | Weather data |
+| `purchase-orders` | get, list, create | Purchase orders |
+| `glebes` | get, list | Farm fields |
+| `crop-glebes` | get, list | Crop fields |
+
+---
+
+## Output Formats
+
+All commands support three output formats:
+
+```bash
+aegro crops list --output json    # JSON (default, for LLMs/scripts)
+aegro crops list --output table   # Rich table for humans
+aegro crops list --output csv     # CSV export
+```
+
+---
+
+## Usage Examples
+
+### Human workflow
+
+```bash
+# Morning overview
+aegro farms select "Fazenda Norte"
+aegro crops list --output table
+aegro financial installments --status PENDING --due-date-start 2025-03-01 --output table
+aegro stock items --output table
+
+# Register a fuel supply
+aegro fuel-supplies create --asset-key K --date 2025-03-13 --quantity 150 --unit L --cost 900
+
+# Check harvest
+aegro harvest-logs get <key>
+```
+
+### LLM/Agent workflow
+
+```bash
+# Agents use JSON output (default) for structured data
+aegro crops list --start-date 2025-01-01 --end-date 2025-12-31
+aegro activities list --crop-key <key>
+aegro stock items
+aegro financial installments --status PENDING
+```
+
+---
+
+## AI Skills
+
+The project includes guided workflows for AI assistants in `.claude/skills/`:
+
+### Domain skills (personas)
+
+| Skill | Purpose |
+|-------|---------|
+| `aegro-agronomo` | Agronomic domain — crops, fields, activities, harvests, weather, inputs |
+| `aegro-estoquista` | Stock domain — items, locations, movements, catalogs, elements |
+| `aegro-financeiro` | Financial domain — bills, installments, categories, bank accounts, companies |
+| `aegro-operacional` | Operational domain — farms, auth, tags, cross-domain orchestration |
+| `aegro-patrimonial` | Asset domain — machines, vehicles, fuel supplies, maintenances |
+
+### Workflow skills
+
+| Skill | Purpose |
+|-------|---------|
+| `aegro-visao-geral` | Farm overview dashboard |
+| `aegro-fechamento-safra` | Crop season closing checklist |
+| `aegro-lancamento-financeiro` | Financial entry guide |
+| `aegro-reconciliacao-estoque` | Stock reconciliation |
+| `aegro-monitoramento-pragas` | Pest monitoring |
+| `aegro-analise-rentabilidade` | Profitability analysis |
+| `aegro-cadastro-patrimonio` | Asset registration |
+
+---
+
+## Configuration
+
+### Authentication
+
+Credential resolution priority:
+
+1. `AEGRO_FARMS` env var (JSON) — for CI/CD and scripts
+2. `AEGRO_FARMS_FILE` env var (path) — for Docker/K8s secrets
+3. `~/.config/aegro/credentials.json` — interactive setup via `aegro auth login`
+
+```bash
+# Option 1: Environment variable
+export AEGRO_FARMS='{"Fazenda Norte": "aegro_key1", "Fazenda Sul": "aegro_key2"}'
+
+# Option 2: Interactive login (saves to ~/.config/aegro/credentials.json)
+aegro auth login --farm-name "Fazenda Norte" --api-key "aegro_key1"
+```
+
+### Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `AEGRO_API_BASE_URL` | `https://app.aegro.com.br` | Aegro API base URL |
+| `AEGRO_FARMS` | — | JSON map of farm name → API key |
+| `AEGRO_FARMS_FILE` | — | Path to JSON credentials file |
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest -v
+
+# Lint
+uv run ruff check aegro/ tests/
+
+# Format
+uv run ruff format aegro/ tests/
+```
+
+---
+
+## Links
+
+- [Aegro](https://aegro.com.br) — Agricultural management platform
+- [Typer](https://typer.tiangolo.com/) — CLI framework
+- [PyPI: aegro](https://pypi.org/project/aegro/) — Package page
+
+---
+
+## License
+
+[MIT](LICENSE)

aegro-0.2.0/aegro/__init__.py

@@ -0,0 +1,4 @@
+try:
+    from aegro._version import __version__
+except ImportError:
+    __version__ = "0.0.0+unknown"

aegro-0.2.0/aegro/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

aegro-0.2.0/aegro/api_client.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import asyncio
+
+import structlog
+import httpx
+
+from aegro.errors import AegroAPIError, translate_api_error
+
+logger = structlog.get_logger()
+
+
+class AegroClient:
+    def __init__(
+        self,
+        base_url: str = "https://app.aegro.com.br",
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ):
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._http: httpx.AsyncClient | None = None
+
+    def _get_http(self) -> httpx.AsyncClient:
+        if self._http is None or self._http.is_closed:
+            self._http = httpx.AsyncClient(timeout=self._timeout)
+        return self._http
+
+    async def close(self) -> None:
+        if self._http is not None and not self._http.is_closed:
+            await self._http.aclose()
+            self._http = None
+
+    def _headers(self, api_key: str) -> dict[str, str]:
+        return {
+            "Aegro-Public-API-Key": api_key,
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+    async def _request(
+        self, method: str, path: str, api_key: str, json_body: dict | None = None
+    ) -> dict | list | None:
+        url = f"{self._base_url}{path}"
+        attempt = 0
+        last_response = None
+        http = self._get_http()
+
+        while attempt <= self._max_retries:
+            try:
+                response = await http.request(
+                    method, url, headers=self._headers(api_key), json=json_body
+                )
+                last_response = response
+                if response.status_code == 204:
+                    return None
+                if response.status_code in (200, 201):
+                    return response.json()
+                if response.status_code >= 500 and attempt < self._max_retries:
+                    attempt += 1
+                    logger.warning(
+                        "aegro_api_retry", path=path, status=response.status_code, attempt=attempt
+                    )
+                    await asyncio.sleep(2**attempt)
+                    continue
+                body = {}
+                try:
+                    body = response.json()
+                except Exception:
+                    pass
+                raise translate_api_error(response.status_code, body)
+            except httpx.TimeoutException:
+                if attempt < self._max_retries:
+                    attempt += 1
+                    logger.warning("aegro_api_timeout", path=path, attempt=attempt)
+                    await asyncio.sleep(2**attempt)
+                    continue
+                raise AegroAPIError(
+                    504, "Timeout ao conectar com o servico Aegro. Tente novamente.", retryable=True
+                )
+            except AegroAPIError:
+                raise
+            except httpx.HTTPError as exc:
+                raise AegroAPIError(
+                    502,
+                    f"Erro de conexao com o servico Aegro: {type(exc).__name__}",
+                    retryable=True,
+                ) from exc
+
+        if last_response is not None:
+            body = {}
+            try:
+                body = last_response.json()
+            except Exception:
+                pass
+            raise translate_api_error(last_response.status_code, body)
+        raise AegroAPIError(502, "Erro inesperado de conexao.", retryable=True)
+
+    async def get(self, path: str, *, api_key: str) -> dict | list | None:
+        return await self._request("GET", path, api_key)
+
+    async def post(
+        self, path: str, *, api_key: str, json_body: dict | None = None
+    ) -> dict | list | None:
+        return await self._request("POST", path, api_key, json_body)
+
+    async def put(
+        self, path: str, *, api_key: str, json_body: dict | None = None
+    ) -> dict | list | None:
+        return await self._request("PUT", path, api_key, json_body)
+
+    async def delete(self, path: str, *, api_key: str) -> dict | list | None:
+        return await self._request("DELETE", path, api_key)
+
+    async def get_user_identity(self, api_key: str) -> str | None:
+        """Return the email address associated with the given API key.
+
+        Calls ``/pub/v1/users/me`` and extracts the ``email`` field.
+        Returns ``None`` when the endpoint does not return a usable email.
+        """
+        try:
+            data = await self.get("/pub/v1/users/me", api_key=api_key)
+            if isinstance(data, dict):
+                return data.get("email")
+        except (AegroAPIError, httpx.HTTPError):
+            logger.warning("identity_lookup_failed", exc_info=True)
+        return None