tumblrbot 1.8.0__tar.gz → 1.9.1__tar.gz

{tumblrbot-1.8.0 → tumblrbot-1.9.1}/.gitignore

@@ -1,10 +1,3 @@
-# Custom
-data
-*.lnk
-config.toml
-custom_prompts.jsonl
-examples.jsonl
-
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]
@@ -138,6 +131,19 @@ __pypackages__/
 celerybeat-schedule
 celerybeat.pid
 
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
 # SageMath parsed files
 *.sage.py
 
@@ -189,11 +195,11 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
 #  you could uncomment the following to ignore the entire vscode folder
-.vscode/
+# .vscode/
 
 # Ruff stuff:
 .ruff_cache/
@@ -207,4 +213,10 @@ marimo/_lsp/
 __marimo__/
 
 # Streamlit
-.streamlit/secrets.toml
+.streamlit/secrets.toml
+
+.vscode
+data
+*.jsonl
+config.toml
+tumblrbot.exe.lnk

{tumblrbot-1.8.0 → tumblrbot-1.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tumblrbot
-Version: 1.8.0
+Version: 1.9.1
 Summary: An updated bot that posts to Tumblr, based on your very own blog!
 Requires-Python: >= 3.13
 Description-Content-Type: text/markdown
@@ -39,13 +39,15 @@ Project-URL: Source, https://github.com/MaidScientistIzutsumiMarin/tumblrbot
 [Tumblr API Documentation on Blog Identifiers]: https://tumblr.com/docs/en/api/v2#blog-identifiers
 [Tumblr API Documentation on Rate Limits]: https://tumblr.com/docs/en/api/v2#rate-limits
 
+[Format String]: https://docs.python.org/3/library/string.html#format-string-syntax
+
 [Download]: src/tumblrbot/flow/download.py
 [Examples]: src/tumblrbot/flow/examples.py
 [Fine-Tune]: src/tumblrbot/flow/fine_tune.py
 [Generate]: src/tumblrbot/flow/generate.py
 [Main]: src/tumblrbot/__main__.py
 
-[Config]: #configuration
+[Configurable]: #configuration
 [Fine-Tuning]: #manual-fine-tuning
 [![PyPI - Version](https://img.shields.io/pypi/v/tumblrbot)](https://python.org/pypi/tumblrbot)
 
@@ -60,36 +62,34 @@ Features:
    1. Asks for [OpenAI] and [Tumblr] tokens.
       - Stores API tokens using [keyring].
    1. Retrieves [Tumblr] [OAuth] tokens.
-   1. [Downloads posts][Download] from the [configured][config] blogs.
+   1. [Downloads posts][Download] from specified blogs ([configurable]).
       - Skips redownloading already downloaded posts.
       - Shows progress and previews the current post.
-   1. [Creates examples][Examples] to fine-tune the model from your posts.
+   1. [Creates examples][Examples] to fine-tune the model from the downloaded posts.
       - Filters out posts that contain more than just text data.
-      - Filters out posts that contain [configured][config] regular expressions.
-      - Adds custom user messages and assistant responses to the dataset from the [configured][config] file.
+      - Filters out posts that contain regular expressions ([configurable]).
+      - Only uses the most recent posts from each blog ([configurable]).
+      - Adds custom user messages and assistant responses to the dataset ([configurable]).
    1. Filters out any posts flagged by the [OpenAI Moderation API].
    1. [Uploads examples][Fine-Tune] to [OpenAI] and begins the fine-tuning process.
-      - Provides cost estimates if the currently saved examples are used to fine-tune the [configured][config] model.
+      - Provides cost estimates if the currently saved examples are used to fine-tune a base model ([configurable]).
       - Resumes monitoring the same fine-tuning process when restarted.
       - Deletes the uploaded examples file if fine-tuning does not succeed (optional).
       - Stores the output model automatically when fine-tuning is completed.
-   1. [Generates and uploads posts][Generate] to the [configured][config] blog using the [configured][config] fine-tuned model.
-      - Creates tags by extracting keywords at the [configured][config] frequency using the [configured][config] model.
-      - Uploads posts as drafts to the [configured][config] blog.
-      - Reblogs posts from the [configured][config] blogs at the [configured][config] frequency.
+   1. [Generates and uploads posts][Generate] to a blog using the fine-tuned model ([configurable]).
+      - Creates tags by extracting keywords using the base model ([configurable]).
+      - Uploads posts as drafts.
+      - Reblogs posts from allowed blogs ([configurable]).
       - Shows progress and previews the current post.
 - Colorful output, progress bars, and post previews using [rich].
-- Automatically keeps the [config] file up-to-date and recreates it if missing.
-
-**To-Do:**
-
-- Create training data from a sample of posts (possible).
+- Automatically keeps the [config][configurable] file up-to-date and recreates it if missing (without overriding user settings).
 
 **Known Issues:**
 
 - Sometimes, you will get an error about the training file not being found when starting fine-tuning. We do not currently have a fix or workaround for this. You should instead use the online portal for fine-tuning if this continues to happen. Read more in [fine-tuning].
 - Post counts are incorrect when downloading posts. We are not certain what the cause of this is, but our tests suggest this is a [Tumblr] API problem that is giving inaccurate numbers.
 - During post downloading or post generation, you may receive a "Limit Exceeded" error message from the [Tumblr] API. This is caused by server-side rate-limiting by [Tumblr]. The only workaround is trying again or waiting for a period of time before retrying. In most cases, you either have to wait for a minute or an hour for the limits to reset. You can read more about the limits in the [Tumblr API documentation on rate limits].
+- Similar to the above issue, you may sometimes get a message saying your IP is blocked. This block is temporary and probably follows the same rules as previously described.
 
 **Please submit an issue or contact us for features you want added/reimplemented.**
 
@@ -106,7 +106,7 @@ Features:
 
 ## Usage
 
-Run `tumblrbot` from anywhere. Run `tumblrbot --help` for command-line options. Every command-line option corresponds to a value from the [config].
+Run `tumblrbot` from anywhere. Run `tumblrbot --help` for command-line options. Every command-line option corresponds to a value from the [config][configurable].
 
 ## Obtaining Tokens
 
@@ -143,6 +143,13 @@ All file options can include directories that will be created when the program i
 
 All config options that involve *blog identifiers* expect any version of a blog URL, which is explained in more detail in the [Tumblr API documentation on blog identifiers].
 
+A valid post:
+
+- Contains any content.
+- Only has text.
+- Is not an ask.
+- Is not a reblog.
+
 Specific Options:
 
 - `custom_prompts_file` This file should follow the following file format:
@@ -155,6 +162,7 @@ Specific Options:
 
    To be specific, it should follow the [JSON Lines] file format with one collection of name/value pairs (a dictionary) per line. You can validate your file using the [JSON Lines Validator].
 
+- **`post_limit`** - At most, this many valid posts will be included in the training data. This effectively is a filter to select the `N` most recent valid posts from each blog. `0` will use every available valid post.
 - **`filtered_words`** - During training data generation, any posts with the specified words will be removed. Word boundaries are not checked by default, so "the" will also filter out posts with "them" or "thematic". This setting supports regular expressions, so you can explicitly look for word boundaries by surrounding an entry with "\\\b", i.e. "\\\bthe\\\b". Regular expressions have to be escaped like so due to how JSON data is read in. If you are familiar with regular expressions, it could be useful for you to know that every entry is joined with a "|" which is then used to search the post content for any matches.
 - **`developer_message`** - This message is used in for fine-tuning the AI as well as generating prompts. If you change this, you will need to run the fine-tuning again with the new value before generating posts.
 - **`user_message`** - This setting is used and works in the same way as `developer_message`.
@@ -166,16 +174,17 @@ Specific Options:
 - **`tags_chance`** - This should be between 0 and 1. Setting it to 0 corresponds to a 0% chance (never) to add tags to a post. 1 corresponds to a 100% chance (always) to add tags to a post. Adding tags incurs a very small token cost.
 - **`reblog_blog_identifiers`** - Whenever a reblog is attempted, a random blog from this list will be chosen to be reblogged from.
 - **`reblog_chance`** - This setting works the same way as `tags_chance`.
-- **`reblog_user_message`** - This setting is a prefix that is directly prepended to the contents of the post being reblogged.
+- **`reblog_user_message`** - This setting is a [format string]. The only argument it is formatted with is the content of the post being reblogged. In simple terms, the `{}` will be replaced with said content.
+  - *Note: The bot is only given the latest message in a reblog chain due to the required complexity and added costs of including the entire chain.*
 
 ## Manual Fine-Tuning
 
 You can manually upload the examples file to [OpenAI] and start the fine-tuning here: [fine-tuning portal].
 
 1. Press `+ Create`.
-1. Select the desired `Base Model` from the dropdown. This should ideally match the model set in the [config].
-1. Upload the generated examples file to the section under `Training data`. You can find the path for this in the [config].
+1. Select the desired `Base Model` from the dropdown. This should ideally match the model set in the [config][configurable].
+1. Upload the generated examples file to the section under `Training data`. You can find the path for this in the [config][configurable].
 1. Press `Create`.
-1. (Optional) Copy the value next to `Job ID` and paste it into the [config] under `job_id`. You can then run the program and monitor its progress as usual.
-1. If you do not do the above, you will have to copy the value next to `Output model` once the job is complete and paste it into the [config] under `fine_tuned_model`.
+1. (Optional) Copy the value next to `Job ID` and paste it into the [config][configurable] under `job_id`. You can then run the program and monitor its progress as usual.
+1. If you do not do the above, you will have to copy the value next to `Output model` once the job is complete and paste it into the [config][configurable] under `fine_tuned_model`.
 

{tumblrbot-1.8.0 → tumblrbot-1.9.1}/README.md

@@ -21,13 +21,15 @@
 [Tumblr API Documentation on Blog Identifiers]: https://tumblr.com/docs/en/api/v2#blog-identifiers
 [Tumblr API Documentation on Rate Limits]: https://tumblr.com/docs/en/api/v2#rate-limits
 
+[Format String]: https://docs.python.org/3/library/string.html#format-string-syntax
+
 [Download]: src/tumblrbot/flow/download.py
 [Examples]: src/tumblrbot/flow/examples.py
 [Fine-Tune]: src/tumblrbot/flow/fine_tune.py
 [Generate]: src/tumblrbot/flow/generate.py
 [Main]: src/tumblrbot/__main__.py
 
-[Config]: #configuration
+[Configurable]: #configuration
 [Fine-Tuning]: #manual-fine-tuning
 [![PyPI - Version](https://img.shields.io/pypi/v/tumblrbot)](https://python.org/pypi/tumblrbot)
 
@@ -42,36 +44,34 @@ Features:
    1. Asks for [OpenAI] and [Tumblr] tokens.
       - Stores API tokens using [keyring].
    1. Retrieves [Tumblr] [OAuth] tokens.
-   1. [Downloads posts][Download] from the [configured][config] blogs.
+   1. [Downloads posts][Download] from specified blogs ([configurable]).
       - Skips redownloading already downloaded posts.
       - Shows progress and previews the current post.
-   1. [Creates examples][Examples] to fine-tune the model from your posts.
+   1. [Creates examples][Examples] to fine-tune the model from the downloaded posts.
       - Filters out posts that contain more than just text data.
-      - Filters out posts that contain [configured][config] regular expressions.
-      - Adds custom user messages and assistant responses to the dataset from the [configured][config] file.
+      - Filters out posts that contain regular expressions ([configurable]).
+      - Only uses the most recent posts from each blog ([configurable]).
+      - Adds custom user messages and assistant responses to the dataset ([configurable]).
    1. Filters out any posts flagged by the [OpenAI Moderation API].
    1. [Uploads examples][Fine-Tune] to [OpenAI] and begins the fine-tuning process.
-      - Provides cost estimates if the currently saved examples are used to fine-tune the [configured][config] model.
+      - Provides cost estimates if the currently saved examples are used to fine-tune a base model ([configurable]).
       - Resumes monitoring the same fine-tuning process when restarted.
       - Deletes the uploaded examples file if fine-tuning does not succeed (optional).
       - Stores the output model automatically when fine-tuning is completed.
-   1. [Generates and uploads posts][Generate] to the [configured][config] blog using the [configured][config] fine-tuned model.
-      - Creates tags by extracting keywords at the [configured][config] frequency using the [configured][config] model.
-      - Uploads posts as drafts to the [configured][config] blog.
-      - Reblogs posts from the [configured][config] blogs at the [configured][config] frequency.
+   1. [Generates and uploads posts][Generate] to a blog using the fine-tuned model ([configurable]).
+      - Creates tags by extracting keywords using the base model ([configurable]).
+      - Uploads posts as drafts.
+      - Reblogs posts from allowed blogs ([configurable]).
       - Shows progress and previews the current post.
 - Colorful output, progress bars, and post previews using [rich].
-- Automatically keeps the [config] file up-to-date and recreates it if missing.
-
-**To-Do:**
-
-- Create training data from a sample of posts (possible).
+- Automatically keeps the [config][configurable] file up-to-date and recreates it if missing (without overriding user settings).
 
 **Known Issues:**
 
 - Sometimes, you will get an error about the training file not being found when starting fine-tuning. We do not currently have a fix or workaround for this. You should instead use the online portal for fine-tuning if this continues to happen. Read more in [fine-tuning].
 - Post counts are incorrect when downloading posts. We are not certain what the cause of this is, but our tests suggest this is a [Tumblr] API problem that is giving inaccurate numbers.
 - During post downloading or post generation, you may receive a "Limit Exceeded" error message from the [Tumblr] API. This is caused by server-side rate-limiting by [Tumblr]. The only workaround is trying again or waiting for a period of time before retrying. In most cases, you either have to wait for a minute or an hour for the limits to reset. You can read more about the limits in the [Tumblr API documentation on rate limits].
+- Similar to the above issue, you may sometimes get a message saying your IP is blocked. This block is temporary and probably follows the same rules as previously described.
 
 **Please submit an issue or contact us for features you want added/reimplemented.**
 
@@ -88,7 +88,7 @@ Features:
 
 ## Usage
 
-Run `tumblrbot` from anywhere. Run `tumblrbot --help` for command-line options. Every command-line option corresponds to a value from the [config].
+Run `tumblrbot` from anywhere. Run `tumblrbot --help` for command-line options. Every command-line option corresponds to a value from the [config][configurable].
 
 ## Obtaining Tokens
 
@@ -125,6 +125,13 @@ All file options can include directories that will be created when the program i
 
 All config options that involve *blog identifiers* expect any version of a blog URL, which is explained in more detail in the [Tumblr API documentation on blog identifiers].
 
+A valid post:
+
+- Contains any content.
+- Only has text.
+- Is not an ask.
+- Is not a reblog.
+
 Specific Options:
 
 - `custom_prompts_file` This file should follow the following file format:
@@ -137,6 +144,7 @@ Specific Options:
 
    To be specific, it should follow the [JSON Lines] file format with one collection of name/value pairs (a dictionary) per line. You can validate your file using the [JSON Lines Validator].
 
+- **`post_limit`** - At most, this many valid posts will be included in the training data. This effectively is a filter to select the `N` most recent valid posts from each blog. `0` will use every available valid post.
 - **`filtered_words`** - During training data generation, any posts with the specified words will be removed. Word boundaries are not checked by default, so "the" will also filter out posts with "them" or "thematic". This setting supports regular expressions, so you can explicitly look for word boundaries by surrounding an entry with "\\\b", i.e. "\\\bthe\\\b". Regular expressions have to be escaped like so due to how JSON data is read in. If you are familiar with regular expressions, it could be useful for you to know that every entry is joined with a "|" which is then used to search the post content for any matches.
 - **`developer_message`** - This message is used in for fine-tuning the AI as well as generating prompts. If you change this, you will need to run the fine-tuning again with the new value before generating posts.
 - **`user_message`** - This setting is used and works in the same way as `developer_message`.
@@ -148,15 +156,16 @@ Specific Options:
 - **`tags_chance`** - This should be between 0 and 1. Setting it to 0 corresponds to a 0% chance (never) to add tags to a post. 1 corresponds to a 100% chance (always) to add tags to a post. Adding tags incurs a very small token cost.
 - **`reblog_blog_identifiers`** - Whenever a reblog is attempted, a random blog from this list will be chosen to be reblogged from.
 - **`reblog_chance`** - This setting works the same way as `tags_chance`.
-- **`reblog_user_message`** - This setting is a prefix that is directly prepended to the contents of the post being reblogged.
+- **`reblog_user_message`** - This setting is a [format string]. The only argument it is formatted with is the content of the post being reblogged. In simple terms, the `{}` will be replaced with said content.
+  - *Note: The bot is only given the latest message in a reblog chain due to the required complexity and added costs of including the entire chain.*
 
 ## Manual Fine-Tuning
 
 You can manually upload the examples file to [OpenAI] and start the fine-tuning here: [fine-tuning portal].
 
 1. Press `+ Create`.
-1. Select the desired `Base Model` from the dropdown. This should ideally match the model set in the [config].
-1. Upload the generated examples file to the section under `Training data`. You can find the path for this in the [config].
+1. Select the desired `Base Model` from the dropdown. This should ideally match the model set in the [config][configurable].
+1. Upload the generated examples file to the section under `Training data`. You can find the path for this in the [config][configurable].
 1. Press `Create`.
-1. (Optional) Copy the value next to `Job ID` and paste it into the [config] under `job_id`. You can then run the program and monitor its progress as usual.
-1. If you do not do the above, you will have to copy the value next to `Output model` once the job is complete and paste it into the [config] under `fine_tuned_model`.
+1. (Optional) Copy the value next to `Job ID` and paste it into the [config][configurable] under `job_id`. You can then run the program and monitor its progress as usual.
+1. If you do not do the above, you will have to copy the value next to `Output model` once the job is complete and paste it into the [config][configurable] under `fine_tuned_model`.

{tumblrbot-1.8.0 → tumblrbot-1.9.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tumblrbot"
-version = "1.8.0"
+version = "1.9.1"
 description = "An updated bot that posts to Tumblr, based on your very own blog!"
 readme = "README.md"
 requires-python = ">= 3.13"

{tumblrbot-1.8.0 → tumblrbot-1.9.1}/src/tumblrbot/flow/examples.py

@@ -3,6 +3,7 @@ from collections.abc import Generator
 from itertools import batched
 from json import loads
 from math import ceil
+from pathlib import Path
 from re import search
 from typing import IO, override
 
@@ -29,7 +30,7 @@ class ExamplesWriter(FlowClass):
             for post in self.get_valid_posts():
                 self.write_example(
                     self.config.user_message,
-                    post.get_content_text(),
+                    str(post),
                     fp,
                 )
 
@@ -55,13 +56,17 @@ class ExamplesWriter(FlowClass):
                 yield from data.items()
 
     def get_valid_posts(self) -> Generator[Post]:
+        for path in self.get_data_paths():
+            posts = list(self.get_valid_posts_from_path(path))
+            yield from posts[-self.config.post_limit :]
+
+    def get_valid_posts_from_path(self, path: Path) -> Generator[Post]:
         pattern = re.compile("|".join(self.config.filtered_words), re.IGNORECASE)
-        for data_path in self.get_data_paths():
-            with data_path.open("rb") as fp:
-                for line in fp:
-                    post = Post.model_validate_json(line)
-                    if post.valid_text_post() and not (self.config.filtered_words and pattern.search(post.get_content_text())):
-                        yield post
+        with path.open("rb") as fp:
+            for line in fp:
+                post = Post.model_validate_json(line)
+                if post.valid_text_post() and not (post.trail and self.config.filtered_words and pattern.search(str(post))):
+                    yield post
 
     def filter_examples(self) -> None:
         examples = self.config.examples_file.read_text("utf_8").splitlines()

{tumblrbot-1.8.0 → tumblrbot-1.9.1}/src/tumblrbot/flow/generate.py

@@ -34,7 +34,7 @@ class DraftGenerator(FlowClass):
 
     def generate_post(self) -> Post:
         if original := self.get_random_post():
-            user_message = f"{self.config.reblog_user_message}\n\n{original.get_content_text()}"
+            user_message = self.config.reblog_user_message.format(original)
         else:
             original = Post()
             user_message = self.config.user_message
@@ -79,7 +79,7 @@ class DraftGenerator(FlowClass):
                     offset,
                 ).response.posts:
                     post = Post.model_validate(raw_post)
-                    if post.valid_text_post():
+                    if post.valid_text_post() and self.is_trail_valid(post.trail):
                         return post
 
         return None
@@ -89,3 +89,7 @@ class DraftGenerator(FlowClass):
         total = self.tumblr.retrieve_blog_info(blog_identifier).response.blog.posts
         # The same Iterable object is cached, so reading an element will effectively discard it. This prevents checking the same offsets twice.
         return iter(sample(range(total), total))
+
+    def is_trail_valid(self, trail: list[Post]) -> bool:
+        # Checks if every post in the reblog trail is valid and that the blog that created the post is in the allowed reblog list.
+        return all(post.valid_text_post() and post.blog.name in self.config.reblog_blog_identifiers for post in trail)

{tumblrbot-1.8.0 → tumblrbot-1.9.1}/src/tumblrbot/utils/models.py

@@ -9,7 +9,7 @@ import tomlkit
 from keyring import get_password, set_password
 from openai.types import ChatModel
 from pwinput import pwinput
-from pydantic import BaseModel, ConfigDict, Field, NonNegativeFloat, PlainSerializer, PositiveFloat, PositiveInt, model_validator
+from pydantic import BaseModel, ConfigDict, Field, NonNegativeFloat, NonNegativeInt, PlainSerializer, PositiveFloat, PositiveInt, model_validator
 from pydantic.json_schema import SkipJsonSchema
 from requests_oauthlib import OAuth1Session
 from rich.panel import Panel
@@ -50,7 +50,8 @@ class Config(FileSyncSettings):
     data_directory: Path = Field(Path("data"), description="Where to store downloaded post data.")
 
     # Writing Examples
-    max_moderation_batch_size: PositiveInt = Field(100, description="How many posts, at most, to submit to the OpenAI moderation API. This is also capped by the API.")
+    post_limit: NonNegativeInt = Field(0, description="The number of the most recent posts from each blog that should be included in the training data.")
+    max_moderation_batch_size: PositiveInt = Field(100, description="The number of posts, at most, to submit to the OpenAI moderation API. This is also capped by the API.")
     custom_prompts_file: Path = Field(Path("custom_prompts.jsonl"), description="Where to read in custom prompts from.")
     filtered_words: list[str] = Field([], description="A case-insensitive list of disallowed words used to filter out training data. Regular expressions are allowed, but must be escaped.")
 
@@ -77,7 +78,7 @@ class Config(FileSyncSettings):
     tags_developer_message: str = Field("You will be provided with a block of text, and your task is to extract a very short list of the most important subjects from it.", description="The developer message used to generate tags.")
     reblog_blog_identifiers: list[str] = Field([], description="The identifiers of blogs that can be reblogged from when generating drafts.")
     reblog_chance: NonNegativeFloat = Field(0.1, description="The chance to generate a reblog of a random post. This will use more OpenAI tokens.")
-    reblog_user_message: str = Field("Please write a comical Tumblr post in response to the following post:", description="The prefix for the user message used to reblog posts.")
+    reblog_user_message: str = Field("Please write a comical Tumblr post in response to the following post:\n{}", description="The format string for the user message used to reblog posts.")
 
     @classmethod
     @override
@@ -144,12 +145,16 @@ class Tokens(FileSyncSettings):
     @model_validator(mode="after")
     @override
     def write(self) -> Self:
+        # Check if any tokens are missing or if the user wants to reset them, then set tokens if necessary.
         if not self.openai_api_key or Confirm.ask("Reset OpenAI API key?", default=False):
             (self.openai_api_key,) = self.online_token_prompt("https://platform.openai.com/api-keys", "API key")
 
         if not all(self.tumblr.model_dump().values()) or Confirm.ask("Reset Tumblr API tokens?", default=False):
             self.tumblr.client_key, self.tumblr.client_secret = self.online_token_prompt("https://tumblr.com/oauth/apps", "consumer key", "consumer secret")
 
+            # This is the whole OAuth 1.0 process.
+            # https://requests-oauthlib.readthedocs.io/en/latest/examples/tumblr.html
+            # We tried setting up OAuth 2.0, but the token refresh process is far too unreliable for this sort of program.
             with OAuth1Session(
                 self.tumblr.client_key,
                 self.tumblr.client_secret,
@@ -169,12 +174,15 @@ class Tokens(FileSyncSettings):
 
             self.tumblr.resource_owner_key, self.tumblr.resource_owner_secret = self.get_oauth_tokens(oauth_tokens)
 
+        # Regardless of whether any values were changed, we may as well write to the keyring.
+        # Any unchanged values will be set to the value they already were, since this is run after reading from the keyring.
         set_password(self.service_name, self.username, self.model_dump_json())
 
         return self
 
 
 class Blog(FullyValidatedModel):
+    name: str = ""
     posts: int = 0
     uuid: str = ""
 
@@ -205,24 +213,31 @@ class Post(FullyValidatedModel):
 
     content: SkipJsonSchema[list[Block]] = []
     layout: SkipJsonSchema[list[Block]] = []
-    trail: SkipJsonSchema[list[Any]] = []
+    trail: SkipJsonSchema[list[Self]] = []
 
     is_submission: SkipJsonSchema[bool] = False
 
     def __rich__(self) -> Panel:
         return Panel(
-            self.get_content_text(),
+            str(self),
             title="Preview",
             subtitle=" ".join(f"#{tag}" for tag in self.tags),
             subtitle_align="left",
         )
 
-    def valid_text_post(self) -> bool:
-        return bool(self.content) and all(block.type == "text" for block in self.content) and not (self.is_submission or self.trail or any(block.type == "ask" for block in self.layout))
-
-    def get_content_text(self) -> str:
+    def __str__(self) -> str:
+        # This function is really only relevant when a post is already valid, so we don't have to check the block types.
+        # If it is called on an invalid post, it would also work, but might give strange data.
         return "\n\n".join(block.text for block in self.content)
 
+    def valid_text_post(self) -> bool:
+        # Checks if this post:
+        # - has any content blocks (some glitched empty posts have no content)
+        # - only has content blocks of type 'text' (this excludes photo/video/poll/etc posts)
+        # - is not a submitted post
+        # - has no ask blocks in the content
+        return bool(self.content) and all(block.type == "text" for block in self.content) and not (self.is_submission or any(block.type == "ask" for block in self.layout))
+
 
 class Example(FullyValidatedModel):
     class Message(FullyValidatedModel):