Metadata-Version: 2.4
Name: kessan
Version: 0.0.1
Summary: Python SDK for Kessan — Japan financial disclosure intelligence via DuckDB
Project-URL: Homepage, https://kessan.io
Project-URL: Documentation, https://kessan.io
Author: TBD
License: MIT
License-File: LICENSE
Keywords: ai-agent,edinet,financial-data,japan,llm,xbrl
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: duckdb>=1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# kessan — Python SDK

Local DuckDB SDK for [Kessan](https://kessan.io) (coming soon) — Japan financial disclosure intelligence.

> **Which Kessan package do I need?**
>
> - **`kessan`** (this package) — Query a local DuckDB file directly. For on-prem deployments and data teams running their own pipeline. No API key required.
> - **`kessan-client`** ([sdk-python-http](https://github.com/[org-TBD]/kessan-python-http) / `pip install kessan-client`) — HTTP client for `api.kessan.io`. For typical SaaS API users with an API key.

## Install

```bash
pip install "kessan>=0.0.1"  # coming soon — not yet on PyPI; install from source for now
# From source: pip install duckdb>=1.0 and use the repo directly
```

## Quickstart

Set the DB path once:
```bash
export KESSAN_DB_PATH=~/.kessan/db.duckdb
```

```python
import kessan

# EDINET-only (audited annual/quarterly XBRL data — default)
rows = kessan.get_financials("E02144")
print(rows[0]["revenue"], rows[0]["src_type"])  # 48036704000000  edinet

# IR PDF only (best-effort Q1/Q3 earnings short reports — unaudited)
ir_rows = kessan.get_financials("E02144", source_types=("ir_pdf",))
print(ir_rows[0]["period_type"], ir_rows[0]["src_type"])  # Q3  ir_pdf

# UNION: both EDINET XBRL and IR PDF sources
all_rows = kessan.get_financials("E02144", source_types=("edinet", "ir_pdf"))
for r in all_rows:
    print(r["fiscal_year"], r["period_type"], r["src_type"], r["revenue"])

# Disclosure filings
filings = kessan.get_filings("E02144", doc_type=120)  # 120 = 有価証券報告書
print(filings[0]["filed_date"], filings[0]["doc_id"])

# Company search (name JP/EN, EDINET code, ticker)
hits = kessan.search_companies("トヨタ", limit=5)
print(hits[0]["name_en"], hits[0]["edinet_code"])
```

## get_financials — source_types

`source_types` controls which tables are queried:

| source_types | Tables queried | Notes |
|---|---|---|
| `("edinet",)` | `financials` | Default. EDINET XBRL, audited |
| `("ir_pdf",)` | `ir_financials` | Best-effort IR PDF Q1/Q3 short reports |
| `("edinet", "ir_pdf")` | Both (UNION) | Full coverage incl. post-2024 Q1/Q3 |

Returned columns (unified across both tables):
`edinet_code`, `ticker`, `fiscal_year`, `period_type`, `period_end`,
`revenue`, `operating_income`, `ordinary_income`, `net_income`, `eps`,
`currency`, `src_type`, `src_publisher`, `src_audited`,
`src_fetched_at`, `src_source_url`

Note: EDINET rows have `period_end=None` (the `financials` table stores only
`fiscal_year` + `period`). IR PDF rows have `period_end` as an ISO date string.

Background: EDINET abolished Q1/Q3 quarterly filings from April 2024. IR PDF
parsing fills this gap for the 10 Nikkei225 companies in the alpha cohort.

## Path resolution

1. Explicit `db_path=` argument
2. `KESSAN_DB_PATH` env var
3. `~/.kessan/db.duckdb` (raises `FileNotFoundError` if missing)

## Links

- [kessan.io](https://kessan.io) — coming soon
