https://github.com/janthmueller/kathekon
kathekon is a Python library and CLI tool for fetching Stoic quotes with interpretations.
https://github.com/janthmueller/kathekon
cli daily-stoic gpt openai python3 stoic-quotes
Last synced: 2 months ago
JSON representation
kathekon is a Python library and CLI tool for fetching Stoic quotes with interpretations.
- Host: GitHub
- URL: https://github.com/janthmueller/kathekon
- Owner: janthmueller
- License: mit
- Created: 2025-01-28T19:49:28.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-02-17T17:18:17.000Z (4 months ago)
- Last Synced: 2025-04-15T21:16:50.570Z (2 months ago)
- Topics: cli, daily-stoic, gpt, openai, python3, stoic-quotes
- Language: Python
- Homepage: https://pypi.org/project/kathekon/
- Size: 3.28 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# kathekon
[](https://pypi.org/project/kathekon/)
[](https://pepy.tech/project/kathekon)
[](https://github.com/janthmueller/kathekon/blob/main/LICENSE)
**kathekon** is a Python library and CLI tool for exploring Stoic philosophy through curated quotes. It allows you to fetch random or daily quotes, insert quotes into files like `README.md`, and generate thoughtful interpretations using OpenAI.
---
## Features
- **Fetch Quotes**:
- Retrieve random Stoic quotes or specific quotes by author or ID.
- Generate consistent daily quotes based on the day of the year.
- Fetch multiple quotes at once for broader inspiration.
- **CLI Tool**:
- Display quotes in the terminal with elegant formatting.
- Update files (e.g., `README.md`) with quotes and their interpretations.
- Customize quote fetching using multiple filtering options.
- **OpenAI Integration** *(Optional)*:
- Generate thoughtful interpretations of quotes using OpenAI's GPT models.
- **Library Integration**:
- Use `Quotes` from the library to integrate Stoic philosophy into your projects.
---
## Installation
Install `kathekon` using pip:
```bash
pip install kathekon
```
To include OpenAI features, install with the `[openai]` or `[all]` extras:
```bash
pip install kathekon[openai]
pip install kathekon[all]
```
---
## Usage
### CLI Commands
After installation, you can use the CLI commands `kathekon` or `stoic-quote`.
#### Display a Random Quote
```bash
kathekon --author "Marcus Aurelius"
```
#### Display Today’s Quote
```bash
kathekon daily
```
#### Insert a Quote into `README.md`
Ensure your `README.md` includes markers like this:
```markdown
```
Then, insert a random or daily quote:
```bash
# Insert a random quote by Marcus Aurelius
kathekon readme random --file README.md --author "Marcus Aurelius"
# Insert today’s Stoic quote
kathekon readme daily --file README.md
```
### Available CLI Arguments
#### General Options (for default/random quote behavior)
These options can be used when **running the CLI without a subcommand**, which will display a **random quote**.
| Argument | Short | Description | Default |
|-------------------------------|-------|----------------------------------------------------------------------------------------------------------|---------|
| `--id ID` | `-i` | Fetch a quote by its unique ID. If omitted, a **random quote** is used. | None |
| `--author "Author Name"` | `-a` | Fetch a random quote by the specified author. If omitted, **a random author is chosen**. | None |
| `--method METHOD` | `-m` | Choose method to fetch or generate interpretation: `gpt`, `db`, `gpt+fallback` | `db` |
| `--list-authors` | `-l` | List all available authors and exit. | - |
| `--version` | `-v` | Show version and exit. | - |
---
#### Method Choices Explained
| Method | Description |
|----------------|------------------------------------------------------------------------------------------------------|
| `gpt` | Generate a quote interpretation using OpenAI's GPT models. Requires an API key. |
| `db` | Fetch a (random) existing interpretation from the database. |
| `gpt+fallback` | Try generating an interpretation using GPT. If unavailable, fall back to a database interpretation. |
| `db+fixed` | Use a fixed interpretation from the database, ensuring consistency for `daily` quotes. |
---
#### `daily` Command
Displays **today’s Stoic quote**.
| Argument | Short | Description | Default |
|------------------------------|-------|----------------------------------------------------------------------------------------------------------|------------|
| `--method METHOD` | `-m` | Choose method to fetch or generate interpretation: `gpt`, `db`, `db+fixed`, `gpt+fallback` | `db+fixed` |
---
#### `readme random` Command
Updates the specified file with a **random quote**.
| Argument | Short | Description | Default |
|------------------------------|-------|----------------------------------------------------------------------------------------------------------|------------|
| `--file FILE` | `-f` | Path to the file to update | `README.md` |
| `--id ID` | `-i` | Fetch a quote by its unique ID. If omitted, a **random quote** is used. | None |
| `--author "Author Name"` | `-a` | Fetch a random quote by the specified author. If omitted, **a random author is chosen**. | None |
| `--method METHOD` | `-m` | Choose method to fetch or generate interpretation: `gpt`, `db`, `gpt+fallback` | `db` |
---
#### `readme daily` Command
Updates the specified file with **today’s Stoic quote**.
| Argument | Short | Description | Default |
|------------------------------|-------|----------------------------------------------------------------------------------------------------------|------------|
| `--file FILE` | `-f` | Path to the file to update | `README.md` |
| `--method METHOD` | `-m` | Choose method to fetch or generate interpretation: `gpt`, `db`, `db+fixed`, `gpt+fallback` | `db+fixed` |
---
## Library Usage
### Fetch a Random Quote
```python
from kathekon import Quotes
quotes = Quotes()
quote = quotes.get_quote(author="Epictetus")
print(f"{quote.text} — {quote.author}")
```
### Generate Today’s Quote
```python
daily_quote = quotes.get_daily_quote(method="gpt+fallback")
print(f"{daily_quote.text} — {daily_quote.author}")
print(f"Interpretation: {daily_quote.interpretation}")
```
### Fetch Multiple Quotes
You can fetch multiple quotes at once with optional filters like `author`, `limit`, or `interpretation`.
```python
from kathekon import Quotes
quotes = Quotes()
# Fetch up to 5 random quotes
for quote in quotes.get_quotes(limit=5):
print(f"{quote.text} — {quote.author}")
# Fetch 3 quotes by Seneca with interpretations from the database
for quote in quotes.get_quotes(author="Seneca", limit=3, method="db"):
print(f"{quote.text} — {quote.author}")
print(f"Interpretation: {quote.interpretation}")
```
---
## OpenAI Integration
To enable OpenAI-powered interpretations, set your API key in the `OPENAI_API_KEY` environment variable:
```bash
export OPENAI_API_KEY="your-api-key"
```
Then, use the CLI or library to fetch quotes with AI-generated interpretations.
---
## Contributing
Contributions are welcome! Feel free to submit issues or pull requests on the [GitHub repository](https://github.com/janthmueller/kathekon).
---
## Acknowledgements
The Stoic quotes used in this project are sourced from [benhoneywill/stoic-quotes](https://github.com/benhoneywill/stoic-quotes).
---
## License
`kathekon` is licensed under the MIT License. See [LICENSE](LICENSE) for details.