Metadata-Version: 2.5
Name: langsuite
Version: 1.0.1
Summary: A research knowledge base of programming languages: how they work, how they relate, with evidence.
Project-URL: Homepage, https://github.com/ao3575911/langsuite
Project-URL: Source, https://github.com/ao3575911/langsuite
Project-URL: Changelog, https://github.com/ao3575911/langsuite/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/ao3575911/langsuite/issues
Author: ao3575911
License-Expression: MIT
License-File: LICENSE
Keywords: cli,knowledge-base,programming-languages,research,telegram-bot,tui
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: cryptography>=43
Requires-Dist: duckdb>=1.1
Requires-Dist: numpy>=2.5.4
Requires-Dist: platformdirs>=4
Requires-Dist: python-telegram-bot[job-queue]==22.8
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13.7
Requires-Dist: textual-serve>=1.1.3
Requires-Dist: textual>=8.2.8
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# langsuite

[![PyPI](https://img.shields.io/pypi/v/langsuite?label=PyPI&color=blue&cacheSeconds=3600)](https://pypi.org/project/langsuite/) [![Python](https://img.shields.io/pypi/pyversions/langsuite)](https://pypi.org/project/langsuite/) [![CI](https://github.com/ao3575911/langsuite/actions/workflows/ci.yml/badge.svg)](https://github.com/ao3575911/langsuite/actions/workflows/ci.yml) [![Docs](https://img.shields.io/badge/docs-pages-blue)](https://ao3575911.github.io/langsuite/)

A research knowledge base of programming languages, with a CLI, a Textual app and a Telegram bot. Every fact links to its source.

![langsuite CLI and Textual app: lang show, rank, similar, then the Explore, Analyse, Dashboard, Docs and Account panes](docs/media/cli.gif)

## Install

```sh
pipx install langsuite        # or: uv tool install langsuite
langsuite base build          # PLDB + Linguist, about 11 MB
langsuite                     # opens the app; `langsuite --help` for the CLI
```

You need Python 3.12 or newer. Docker is optional and only used by `verify`. To install from source: `git clone https://github.com/ao3575911/langsuite && cd langsuite && uv sync`.

## What it does

Every command in this table runs as written once `base build` has finished.

| | Command | Evidence |
|---|---|---|
| Sourced facts | `langsuite lang show haskell --evidence` | Each fact carries its source, URL and retrieval time (PLDB, Linguist). |
| Query | `langsuite query "macros top=3"` | Same DSL in the CLI, the Query pane and `/q` in the bot. |
| Similarity | `langsuite similar haskell` | Rarity-weighted Jaccard with a z-score against 1,000 shuffles. |
| Scores | `langsuite rank --top 5` | Points per criterion; a missing criterion lowers confidence and never counts as zero. |
| Verified code | `langsuite verify main.rs` | Runs in a digest-pinned, offline Docker sandbox (20 toolchains). |
| Official docs | `langsuite docs search "unpacking"` | Exact quotes with a link, version and anchor. |
| Signed data | `langsuite base pull URL --key cosign.pub` | Refuses unsigned or tampered snapshots (cosign-compatible). |
| Workspaces | `langsuite finding save similar scheme` | Findings re-run bit-for-bit on their pinned snapshot. |
| Plan and quota | `langsuite usage` | Shows the monthly quota and exits with code 5 at 100%. |

## Telegram bot

![Telegram bot: /start, /l haskell, /q, /similar, /r, /dc search](docs/media/bot.gif)

*The bot GIF is a mock-up. The replies are real output from langsuite's bot engine (`langsuite bot try`), drawn in a Telegram-style frame. It is not a screen recording of Telegram.*

`langsuite bot run` serves the same commands and aliases as the CLI. Each chat gets its own workspace, with roles, rate limits and daily digests.

## Status

**1.0.0 is released on [PyPI](https://pypi.org/project/langsuite/)** (`pipx install langsuite`). Milestones M0 to M5i are built, with M5i on the client side only. The hosted service (tenants, sync, backups) is not deployed. Releases are published from signed `v*` tags ([docs/RELEASING.md](docs/RELEASING.md)).

Not done yet: [open questions](docs/OPEN_QUESTIONS.md) and [issues](https://github.com/ao3575911/langsuite/issues).

## More

[Wiki](https://github.com/ao3575911/langsuite/wiki) · [Full guide](https://ao3575911.github.io/langsuite/guide/) · [Spec](docs/SPEC.md) · [Changelog](CHANGELOG.md) · [Discussions](https://github.com/ao3575911/langsuite/discussions) · Licence: see [LICENSE](LICENSE)
