Metadata-Version: 2.4
Name: pacifico
Version: 0.0.9.43
Summary: This repository holds the pacifico user Python package for the API (client source code).
Home-page: https://github.com/BurrusFinancialIntelligence/pacifico-client.git
Author: Pacifico
Author-email: pacifico@bfi.lat
Project-URL: Bug Tracker, https://github.com/BurrusFinancialIntelligence/pacifico-client.git/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: julian
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: python-dateutil
Requires-Dist: pytz
Requires-Dist: paramiko==3.5.1
Requires-Dist: requests
Requires-Dist: six
Requires-Dist: urllib3
Requires-Dist: selenium
Requires-Dist: boto3
Requires-Dist: webdriver-manager
Requires-Dist: xlrd
Requires-Dist: pysftp
Dynamic: license-file

# Pacífico Python Client

Official Python interface for requesting financial values, structured reports, metadata, and hosted applications from the Pacífico API.

The package exposes one primary function—`pacifico.request(...)`—and handles request serialization, API-key authentication, asynchronous result polling, JSON parsing, and optional file output.

> **Access required:** The package is installable from PyPI, but API usage requires a token issued by Pacifico Research.

## Contents

- [Installation](#installation)
- [Quick start](#quick-start)
- [Authentication](#authentication)
- [Requesting values](#requesting-values)
- [Requesting reports](#requesting-reports)
- [Metadata discovery](#metadata-discovery)
- [Hosted applications](#hosted-applications)
- [Request reference](#request-reference)
- [Response formats](#response-formats)
- [Saving results](#saving-results)
- [How delivery works](#how-delivery-works)
- [Development](#development)
- [License](#license)

## Installation

Pacífico supports Python 3.6 or later according to the package metadata.

```bash
python -m pip install pacifico
```

For an isolated environment:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install pacifico
```

## Quick start

Store the token supplied by Pacifico Research in `token.key`, then request a ticker:

```python
import pacifico

values = pacifico.request("token.key", ticker="BCP0600323")
print(values)
```

The default result is a `pandas.DataFrame`. You may also pass the token value directly, but a token file is safer for local development when it is excluded from version control.

## Authentication

The `token` argument accepts:

- the API token as a string;
- a path ending in `.key` or `.txt`; or
- an empty value, in which case the client reads `token.key` from the current working directory.

```python
# Explicit token file (recommended for local use)
data = pacifico.request("/secure/path/pacifico.key", ticker="CHILE")

# Implicit ./token.key
data = pacifico.request(ticker="CHILE")
```

Never commit a real token, paste one into a notebook output, or include one in support logs. Tokens determine both identity and the enabled usage plan.

## Requesting values

Value requests can target one or more tickers or progressively broader levels of the instrument hierarchy:

```text
Country → Market → Group → Family → Ticker
```

```python
import pacifico

token = "token.key"

# One ticker
bond = pacifico.request(token, ticker="BCP0600323")

# Multiple tickers
portfolio = pacifico.request(token, ticker=["CHILE", "BCP0600323"])

# Hierarchy filters
family = pacifico.request(token, family="BCP")
group = pacifico.request(token, group="BT")
market = pacifico.request(token, market="RF")

# Select an author/source
central_bank = pacifico.request(token, author="BCCh")
```

### Historical values

Use `datetime.date` or `datetime.datetime` values for `dateStart` and `dateEnd`:

```python
from datetime import date, timedelta

import pacifico

end = date.today()
start = end - timedelta(days=7)

history = pacifico.request(
    "token.key",
    ticker="CHILE",
    dateStart=start,
    dateEnd=end,
)
```

Historical ranges must be ticker-specific. Broad family, group, market, or country requests are served as current/latest queries even when a historical range is supplied. A single-date request is permitted.

### Field, version, and quality filters

String values are accepted for `fieldType`; enum values are used for fixing, version type, and quality:

```python
from pacifico import Fixing, Quality, VersionType

import pacifico

prices = pacifico.request(
    "token.key",
    ticker="BCP0600323",
    fieldType="Price",
    fixing=Fixing.EOD,
    versionType=VersionType.Version_Pricing,
    quality=Quality.Quality_Production,
)
```

Available value fields include `Price`, `Yield`, `Duration`, `Convexity`, `Delta`, `Gamma`, `Vega`, `Volatility`, `Quote`, `Clean Price`, `Clean Quote`, and `Market Presence`. Leaving `fieldType` empty returns all available fields.

## Requesting reports

Report requests are selected automatically when any report hierarchy argument is present:

```text
Document → Chapter → Section → Subsection → Paragraph → Item
```

```python
import pacifico

token = "token.key"

# Reports associated with an entity
entity = pacifico.request(token, item="97004000-5")

# Instrument characteristics and related reports
instrument = pacifico.request(token, item="BCP0600323")

# A document across available items
identifications = pacifico.request(token, document="Identification")

# Combine hierarchy filters
balance_sheet = pacifico.request(
    token,
    document="Balance Sheet",
    item="96800570-7",
)
```

Report values are typed variants and may contain booleans, numbers, strings, dates, datetimes, URLs, files, browser content, or lists. Historical report ranges should specify both `document` and `item`; otherwise the service may normalize the request to current/latest data.

## Metadata discovery

Use metadata before building broad or user-selectable queries.

```python
import pacifico

token = "token.key"

# Entire value universe: authors, markets, groups, families, and tickers
value_metadata = pacifico.request(token)

# Value metadata filtered to a family
bcp_metadata = pacifico.request(token, family="BCP", ticker="metadata")

# Report universe: authors, documents, and items
report_metadata = pacifico.request(token, document="metadata")

# Reports available for one item
item_metadata = pacifico.request(
    token,
    document="metadata",
    item="97004000-5",
)
```

Passing `metadata` in an instrument filter selects value metadata. Passing it in `document`, `chapter`, `section`, `subsection`, `paragraph`, or `item` selects report metadata.

## Hosted applications

Set `app` to route a request to a hosted financial application. Application names and accepted arguments depend on the caller's access and the server-side application catalog.

```python
import pacifico

# Discover an application's argument contract
help_data = pacifico.request(
    "token.key",
    app="<APPLICATION_NAME>",
    help=True,
)

# Run it; additional keyword arguments are forwarded to the application
result = pacifico.request(
    "token.key",
    app="<APPLICATION_NAME>",
    help=False,
    ticker="CHILE",
    customArgument="value",
)
```

When the application contract marks an argument as a file, the client uploads the referenced local file to temporary storage and forwards its URL. Application requests use the same asynchronous delivery and output conversion as value and report requests.

## Request reference

```python
pacifico.request(
    token="",
    ticker="", family="", group="", market="", country="",
    document="", item="", chapter="", section="", subsection="", paragraph="",
    app="", help=False,
    dateStart=date.today(), dateEnd=date.today(),
    fixing=Fixing.EOD,
    fieldType="",
    versionType=VersionType.Version_Unspecified,
    author="", version="", quality=Quality.Quality_Unspecified,
    timeOut=300,
    fileName="", format="dataFrame",
    **kwargs,
)
```

| Argument | Description | Default |
| --- | --- | --- |
| `token` | Token value or `.key`/`.txt` path | Read `token.key` |
| `ticker` | One ticker or a list of tickers | `""` |
| `family`, `group`, `market` | Instrument hierarchy filters | `""` |
| `country` | Country name or `Country` enum | Unspecified |
| `document` … `item` | Report hierarchy filters | `""` |
| `app` | Hosted application name | `""` |
| `help` | Return an application's argument contract | `False` |
| `dateStart`, `dateEnd` | Effective-date interval | Today |
| `fixing` | EOD or a half-hour `Fixing` enum | `Fixing.EOD` |
| `fieldType` | Value field such as `Price` or `Yield` | Unspecified |
| `versionType` | Pricing, prediction, or unspecified | Unspecified |
| `author`, `version` | Source/scenario filters | `""` |
| `quality` | Production, certification, development, or unspecified | Unspecified |
| `timeOut` | Maximum polling time in seconds | `300` |
| `fileName` | Output path without extension | `""` |
| `format` | `dataFrame`, `dictionary`/`dict`, or `json` | `dataFrame` |
| `**kwargs` | Additional hosted-application arguments | — |

Public enums are importable from the package:

```python
from pacifico import Country, Fixing, Quality, VersionType
```

## Response formats

### DataFrame (default)

```python
data = pacifico.request("token.key", ticker="BCP0600323")
```

Value DataFrames contain:

```text
Scenario, Date Publication, Date Effective, Country, Market, Group,
Family, Ticker, Value, Field, Date Tenor, Other
```

Report DataFrames contain:

```text
Author, Document, Chapter, Section, Subsection, Paragraph, Item,
Date Publication, Date Effective, Fixing, Value, Value Type,
Date Tenor, Other
```

Date columns are converted to Python/pandas date-time objects where possible.

### Dictionary

```python
data = pacifico.request(
    "token.key",
    ticker="BCP0600323",
    format="dictionary",
)
```

The result is the decoded nested API response.

### JSON

```python
data = pacifico.request(
    "token.key",
    ticker="BCP0600323",
    format="json",
)
```

The result is the raw JSON string.

Value JSON follows this hierarchy:

```text
Scenario → Publication date → Effective date → Country → Market
         → Group → Family → Ticker → [{value, field, dateTenor?, other?}]
```

Report JSON follows this hierarchy:

```text
Author → Publication date → Effective date → Document → Chapter
       → Section → Subsection → Paragraph → Item
       → [{variant: {value, type}, dateTenor?, other?}]
```

## Saving results

Pass a base path through `fileName`. The client chooses the extension from the response format:

```python
# Writes pacifico_data.csv
pacifico.request(
    "token.key",
    ticker="BCP0600323",
    format="dataFrame",
    fileName="pacifico_data",
)

# Writes pacifico_data.txt
pacifico.request(
    "token.key",
    ticker="BCP0600323",
    format="json",
    fileName="pacifico_data",
)
```

DataFrames are written as CSV without the index. JSON strings and dictionaries are written as JSON text.

## How delivery works

1. The client serializes a value, report, or application service request.
2. It sends the request to the API with the token in `x-api-key`.
3. The API immediately returns a pre-signed result URL and processes the request asynchronously.
4. The client polls that URL until the result is ready.
5. The JSON payload is converted to the requested local format and optionally saved.

If processing exceeds `timeOut`, the client raises `TimeoutError`. Increase the timeout for legitimately large report or application requests; avoid unbounded retries.

## Tutorials

The repository includes two detailed, executable Spanish-language notebooks:

- [`TutorialValues.ipynb`](TutorialValues.ipynb) — values, metadata, historical ranges, formats, saving, and the value hierarchy.
- [`TutorialReports.ipynb`](TutorialReports.ipynb) — report discovery, hierarchy filters, typed results, formats, and saving.

The examples in this README intentionally use placeholders or token-file paths. Replace only the local token file contents—never commit the issued credential.

## Development

Clone with the shared private submodule and install the package in editable mode:

```bash
git clone --recurse-submodules <REPOSITORY_URL>
cd pacifico-client
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
```

If the repository was already cloned:

```bash
git submodule update --init --recursive
```

Build distributions with:

```bash
python -m pip install build
python -m build
```

The package uses a `src` layout:

```text
src/pacifico/
├── core/main/pacifico.py          # Public request workflow
├── core/Service/                  # Request and field models
└── util/                          # Arguments, polling, formats, and output
```

When changing the request contract, keep the client synchronized with the companion Pacífico API server repository and coordinate compatibility-sensitive migrations between releases.

## License

Copyright © Pacifico Research. This package is proprietary. Commercial integration, incorporation into a product, or third-party distribution requires an appropriate license from Pacifico Research. Contact Pacifico Research for the current governing terms.
