Metadata-Version: 2.4
Name: telmus
Version: 0.2.2
Summary: Financial statement analysis for AI IDEs and coding agents
Project-URL: Homepage, https://shubhwade.github.io/telmus
Project-URL: Documentation, https://shubhwade.github.io/telmus
Project-URL: Repository, https://github.com/shubhwade/telmus
Project-URL: Changelog, https://shubhwade.github.io/telmus/changelog/
Author-email: Shubh Wade <shubhwade@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai-agent,altman,beneish,claude,finance,financial-analysis,mcp,mcp-server,piotroski,yfinance
Classifier: Development Status :: 3 - 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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Requires-Dist: mcp>=0.1.0
Requires-Dist: openpyxl>=3.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: yfinance>=0.2.0
Provides-Extra: dev
Requires-Dist: bandit; extra == 'dev'
Requires-Dist: mkdocs-material; extra == 'dev'
Requires-Dist: mkdocstrings[python]; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: streamlit; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# telmus

[![PyPI version](https://img.shields.io/pypi/v/telmus)](https://pypi.org/project/telmus/)
[![Downloads](https://img.shields.io/pypi/dm/telmus)](https://pypi.org/project/telmus/)
[![Python](https://img.shields.io/pypi/pyversions/telmus)](https://pypi.org/project/telmus/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

Financial statement analysis for AI IDEs and coding agents.

```bash
pip install telmus
telmus scan INFY
```

## What is telmus?

telmus is a Python package and CLI for parsing financial statements, computing key valuation and health ratios, and exposing them through an MCP server for AI tools.

## Engines

| Engine | What it measures | Key metric |
|---|---|---|
| Valuation | Price multiples and peer comparison | P/E, P/B, EV/EBITDA |
| Health | Balance sheet strength and bankruptcy risk | Piotroski F-score, Altman Z-score |
| Flags | Earnings quality and cash flow risk | Beneish M-score, free cash flow trend |

## analyst_brief

A deterministic summary field that explains fundamentals, growth, and red flags without using an LLM.

Example output:

```json
{
  "analyst_brief": "Strong fundamentals (Piotroski F-score of 7). Financially safe (Altman Z-score of 4.20). Revenue growth is 11.2% over three years and operating margins are stable. No significant red flags detected. Suitable for DCF or comparable company analysis."
}
```

## Quick start

1. Install:

```bash
pip install telmus
```

2. Scan a ticker:

```bash
telmus scan INFY
```

3. Read the summary and analyst brief, or export JSON for automation.

## MCP server setup

```json
{
  "mcpServers": {
    "telmus": {
      "command": "telmus",
      "args": ["serve"],
      "description": "Financial statement analysis — real ratios for any ticker"
    }
  }
}
```

- Claude Desktop: use the config to register telmus as an MCP tool.
- Cursor: same config loads telmus as a tool for market research.
- Windsurf: connect the MCP server to get real financial metrics.

## Other commands

| Command | Description |
|---|---|
| `telmus scan TICKER` | Run a full financial scan |
| `telmus scan TICKER --json` | Print raw JSON |
| `telmus scan TICKER --export FILE.json` | Save JSON to a file |
| `telmus compare A B` | Compare two tickers |
| `telmus screen` | Run a simple sector screener |
| `telmus serve` | Start the MCP server |
| `telmus info` | Print package info |
| `telmus check TICKER` | Quick health check |

## Benchmark

| Test | Result |
|---|---|
| Piotroski score coverage | 9 signals |
| Altman Z distress detection | safe/grey/distress ranges |
| Flag detection | Beneish M, D/E, FCF trend |

## Architecture

```
yfinance -> loader -> valuation/health/growth/flags -> ScanResult -> CLI / MCP / SDK
```

## Contributing

1. Fork the repository.
2. Create a feature branch.
3. Run `pip install -e ."[dev]"`.
4. Write tests and update docs.
5. Submit a pull request.

## License

MIT License
