Metadata-Version: 2.4
Name: oh-my-share
Version: 0.1.2
Summary: Local, agent-native CLI for querying public stock data
Project-URL: Repository, https://github.com/geoqiao/oh-my-share
Project-URL: Documentation, https://github.com/geoqiao/oh-my-share#readme
Author: Oh My Share contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent-skills,cli,market-data,stocks
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Requires-Dist: akshare==1.18.83
Requires-Dist: click<9,>=8.1
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: yfinance==1.5.2
Description-Content-Type: text/markdown

# Oh My Share

Oh My Share is an open-source, local Python CLI that lets Claude Code, Codex, Pi, and humans query public listed-equity data through one stable interface.

It ships query software—not a stock-market dataset, hosted API, research platform, or investment advice.

## What it provides

Six stable capabilities:

- `search` — resolve listed equities
- `quote` — latest available price observation
- `bars` — unadjusted daily OHLCV
- `company` — company profile
- `financials` — normalized financial statements
- `actions` — dividends, splits, and other corporate actions

Tier 1 covers mainland China, Hong Kong, and major US venues. Canonical identity is `MIC:ticker`, such as `XSHG:600519`, `XHKG:0700`, or `XNAS:AAPL`; common aliases are accepted when unambiguous.

## Requirements

- Python 3.11 or newer
- macOS or Linux
- Network access to the selected public data source

Windows is not part of the `v0.1.2` support contract.

## Install

From a clone:

```bash
uv sync
uv run oh-my-share --help
```

As an isolated tool from PyPI:

```bash
uv tool install oh-my-share
oh-my-share skill install
oh-my-share --help
```

`skill install` copies the complete versioned Skill—including the bounded reader and Receipt Schema—to `~/.agents/skills/oh-my-share`. Pi and Codex can then use it outside a source checkout.

No account, API key, bundled market data, database, Node runtime, or background service is required.

## Query examples

```bash
oh-my-share search Apple --market us
oh-my-share quote XNAS:AAPL
oh-my-share bars XSHG:600519 --start 2026-07-01 --end 2026-07-10
oh-my-share company 0700.HK
oh-my-share financials XNAS:AAPL --frequency latest
oh-my-share actions XSHG:600519
```

Every query command supports `--provider` and `--timeout`. An explicit Provider disables fallback. The default timeout is 30 seconds where the upstream adapter can enforce it.

Standard output contains only a compact JSON Receipt. Complete normalized data is written privately to:

```text
~/.oh-my-share/results/<UTC-date>/<uuid>.json
```

Files use mode `0600`; directories use mode `0700`. Results are never written to the current repository.

```bash
oh-my-share artifacts prune --older-than 30d          # dry-run
oh-my-share artifacts prune --older-than 30d --delete # explicit deletion
```

See the [CLI reference](https://github.com/geoqiao/oh-my-share/blob/main/docs/cli.md), [data contract](https://github.com/geoqiao/oh-my-share/blob/main/docs/data-contract.md), and [local live validation guide](https://github.com/geoqiao/oh-my-share/blob/main/docs/local-live-validation.md).

## Agent integration

The shared Agent Skill is [`skills/oh-my-share/SKILL.md`](https://github.com/geoqiao/oh-my-share/blob/main/skills/oh-my-share/SKILL.md). It teaches an Agent to:

1. translate the request into the Canonical CLI;
2. validate the compact Receipt;
3. read Artifact metadata first;
4. use the bundled bounded reader for any selected records;
5. report the actual Provider and Data Source.

The distribution includes:

- `oh-my-share skill install` for user-level Pi and Codex discovery under `~/.agents/skills/oh-my-share`;
- `.agents/skills/oh-my-share` as a repository-development link to the same Skill;
- `.claude-plugin/plugin.json` for Claude Code plugin packaging;
- one shared Skill implementation—no host-specific data engine.

The Skill never installs the CLI automatically and never dumps a complete Artifact into Agent context. Bundled scripts and Schemas are always resolved relative to the installed `SKILL.md`, never from a repository path.

## Providers and data sources

Oh My Share wraps maintained packages (`AKShare`, `yfinance`) and a small set of verified Python Native routes for Eastmoney, Tencent, and Sina. Provider provenance always identifies the actual Data Source.

A `v0.1.2` A-share Quote resolves through Tencent then Yahoo. A-share Bars uses verified Eastmoney, Tencent, Sina, and Yahoo routes. Same-source alternate adapters are labeled and do not masquerade as distinct-source resilience.

Coverage and limitations are recorded in the [Provider Capability Matrix](https://github.com/geoqiao/oh-my-share/blob/main/docs/provider-capability-matrix.md). Upstream availability, delay, fields, and personal-use conditions can change. Users are responsible for following each source's current terms. Oh My Share does not claim exchange-direct or guaranteed real-time data.

## Development

```bash
uv run pytest
uv run ruff check .
uv run mypy src
uv build
git diff --check
```

Committed JSON Schemas live under [`schemas/`](https://github.com/geoqiao/oh-my-share/tree/main/schemas). Live tests are opt-in and bounded.

## License

Apache-2.0. This license covers the repository software and does not grant rights to third-party market data.
