Metadata-Version: 2.5
Name: profitelligence
Version: 0.1.1
Summary: SEC filings, insider trading and market signals in Python.
Project-URL: Homepage, https://profitelligence.com
Project-URL: Documentation, https://profitelligence.com/api-reference/python
Project-URL: Issues, https://profitelligence.com/support
Author-email: Profitelligence <support@profitelligence.com>
License: MIT License
        
        Copyright (c) 2026 Profitelligence
        
        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.
License-File: LICENSE
Keywords: 13f,api-client,edgar,finance,form4,fred,insider-trading,institutional-holdings,market-data,quant,sec
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Description-Content-Type: text/markdown

# profitelligence

SEC filings, insider trading and market signals in Python.

```bash
pip install profitelligence
```

```python
import profitelligence as prof

prof.api_key("pk_live_...")  # or set PROFITELLIGENCE_API_KEY
prices = prof.company.ohlc("AAPL", days=90)  # 90 rows, typed
prices[0].close  # 305.69, a float
prices.df  # a DataFrame, with [pandas]
```

That is the whole idea. The Profitelligence API answers in pipe-delimited CSV.
This package parses it, types it, and hands you rows you can work with.

---

## What you get

Nine namespaces cover 68 endpoints. Every method is generated from the same API
reference the documentation site renders, so the package cannot describe an
endpoint the API does not have.

| Namespace | Data |
|---|---|
| `prof.company` | Profiles, daily prices, technical signals, corporate actions |
| `prof.filings` | 8-K summaries and filing patterns |
| `prof.form4` | Insider transactions, clusters, insider profiles |
| `prof.institutional` | 13F holdings, managers, crowded trades |
| `prof.financials` | Income statement, balance sheet, cash flow |
| `prof.fred` | Economic series from the Federal Reserve |
| `prof.discovery` | Search, spotlights, interesting companies |
| `prof.graph` | The knowledge graph |
| `prof.analytics` | Correlations, opportunity scores, strategies |

Every method carries the endpoint's own documentation. In a notebook,
`prof.form4.clusters?` shows the arguments, the tier it needs, and the columns
it returns.

## Authentication

Get a key at [profitelligence.com/account/api-keys](https://profitelligence.com/account/api-keys).

```python
prof.api_key("pk_live_...")  # for a notebook
```

```bash
export PROFITELLIGENCE_API_KEY=pk_live_...
```

You can also call with no key at all. Guests reach the free endpoints on the
top 500 symbols, which is enough to try the package before you sign up.

In a service, build a client and hold it. One client is one connection pool.

```python
from profitelligence import Client

with Client(api_key="pk_live_...", timeout=60) as prof:
    holdings = prof.institutional.manager_top_holdings("0001067983")
```

## Tables

CSV endpoints return a `Table`: named columns, typed values, one row object per
record. It is a normal Python sequence, so index it, slice it, and iterate it.

```python
prices = prof.company.ohlc("AAPL,MSFT", days=180)

prices.columns  # ['symbol', 'time', 'open', 'high', 'low', 'close']
len(prices)  # 360
prices[0].close  # 305.69            a float
prices[0].time  # date(2026, 8, 17) a date
prices.column("close")  # the whole column
prices.to_dicts()  # plain dictionaries
```

Types come from the API reference where it declares them, and from the data
where it does not. A column is typed as a whole: if one value will not parse,
the column stays text rather than becoming a mix you cannot do arithmetic on.
An empty cell is `None`, never `0` and never `""`.

For pandas, install the extra:

```bash
pip install 'profitelligence[pandas]'
```

```python
frame = prices.df  # or prices.to_pandas()
frame.set_index("time").close.resample("W").last()
```

Date columns arrive as `datetime64`, so resampling and plotting work with no
further conversion.

JSON endpoints — the page routes, FRED, search, and the knowledge graph —
return the decoded body as it stands.

## When a call does not work

Errors say what happened, in the API's own words.

```python
try:
    scores = prof.analytics.opportunities()
except prof.UpgradeRequired as error:
    print(error.message)  # the plan this endpoint needs
except prof.RateLimited as error:
    print(error.retry_after)  # seconds until the window resets
```

| Error | Means |
|---|---|
| `AuthenticationError` | The key is absent, wrong, or revoked |
| `UpgradeRequired` | Your plan does not include this endpoint or this symbol |
| `RateLimited` | The window is spent. `retry_after`, `limit`, `remaining`, `reset` |
| `BadRequest` | An argument is missing or out of range |
| `NoData` | The API looked and found nothing to return |
| `ServerError` | The API failed. The client already retried twice |
| `Timeout` | No answer inside the timeout |

All of them inherit `ProfitelligenceError`.

A rate limit is never retried behind your back. A notebook that sleeps for a
minute without telling you is worse than an error you can see. Server errors
and timeouts are retried twice, with backoff.

Two of these deserve a word. The API sometimes reports a problem in-band: HTTP
200, with a body of `error,<message>`. Read raw, that looks like success and
parses to nothing. This package raises instead — `BadRequest` when you caused
it, `NoData` when the API simply had nothing — so an empty result never passes
for a real one. A genuinely empty result, which the API returns as a header row
with no data rows, stays an empty `Table`.

## What this package does not do

It reads. There is nothing here that writes to your account, and nothing that
places a trade.

It reports what filings and prices show. It does not advise, predict, or
recommend. What you do with the data is your decision, and a licensed advisor
is the right person to help you make it.

## Rate limits and tiers

Each key has a request window and a symbol list that follow your plan. Guests
and Free see the top 500 symbols, Pro the top 6,000, Elite all of them. A
symbol outside your tier raises `UpgradeRequired` with the plan it needs.

## How this package is built

The client is **generated**. The nine modules under
`src/profitelligence/resources/` are produced by `codegen/generate.py` from
`codegen/spec.json`, which is exported from the same API reference that renders
at [profitelligence.com/api-reference](https://profitelligence.com/api-reference).
That reference is the contract: an endpoint reaches this package by being
documented, not by someone hand-writing a signature.

Editing a generated file therefore has no lasting effect — the next generation
replaces it. The hand-written part is the core: `client.py`, `_http.py`,
`table.py` and `errors.py`.

```bash
uv sync --group dev
pytest                  # offline, every response mocked
pytest -m live          # hits the public API; no key needed for the free endpoints
ruff check . && ruff format --check .
```

The source repository is private, so there is nowhere to send a pull request.
Bug reports are genuinely useful and are acted on: mail
[support@profitelligence.com](mailto:support@profitelligence.com) or use
[profitelligence.com/support](https://profitelligence.com/support), and say
what you called, what came back, what you expected, and your Python and
`profitelligence.__version__`. A failing five-line script is worth more than a
paragraph.

## License

MIT.
