profitelligence 0.1.0__tar.gz

profitelligence-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+uv.lock

profitelligence-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+The Python client versions independently of the web app. Releases go out from
+the public mirror at github.com/profitelligence/profitelligence-py; the
+package itself is developed and generated upstream.
+
+## 0.1.0 — unreleased
+
+First release.
+
+- A typed client over the public Profitelligence API: 68 endpoints in nine
+  namespaces, generated from the API reference so the package cannot drift
+  from the documented contract.
+- Pipe-delimited CSV responses parse into a `Table` of typed rows. Numbers are
+  numbers, dates are dates, and empty cells are `None`.
+- `Table.to_pandas()` for a DataFrame, behind the `[pandas]` extra.
+- API-key auth with the `ApiKey` scheme, or guest access with no key at all.
+- Errors say what happened: `UpgradeRequired` carries the tier message,
+  `RateLimited` carries the retry window, and an in-band `error,...` body on a
+  200 becomes `BadRequest` or `NoData` instead of a silent empty result.

profitelligence-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

profitelligence-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.5
+Name: profitelligence
+Version: 0.1.0
+Summary: SEC filings, insider trading and market signals in Python.
+Project-URL: Homepage, https://profitelligence.com
+Project-URL: Documentation, https://profitelligence.com/api-reference
+Project-URL: Changelog, https://github.com/profitelligence/profitelligence-py/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/profitelligence/profitelligence-py/issues
+Project-URL: Source, https://github.com/profitelligence/profitelligence-py
+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 .
+```
+
+Development happens in a private repository and is pushed here in one
+direction, so a pull request cannot be merged into this tree. Bug reports are
+genuinely useful and are acted on — see
+[CONTRIBUTING.md](CONTRIBUTING.md) for what helps most.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

profitelligence-0.1.0/README.md

@@ -0,0 +1,185 @@
+# 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 .
+```
+
+Development happens in a private repository and is pushed here in one
+direction, so a pull request cannot be merged into this tree. Bug reports are
+genuinely useful and are acted on — see
+[CONTRIBUTING.md](CONTRIBUTING.md) for what helps most.
+
+## License
+
+MIT. See [LICENSE](LICENSE).