studytrails 0.2.0__tar.gz → 0.2.2__tar.gz

{studytrails-0.2.0 → studytrails-0.2.2}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: studytrails
-Version: 0.2.0
+Version: 0.2.2
 Summary: A personal multi-subject AI study coach with tools, local progress, and an offline demo.
 License-Expression: MIT
 License-File: LICENSE
-Requires-Python: <3.14,>=3.12
+Requires-Python: <3.15,>=3.10
 Requires-Dist: keyring<26,>=25
 Requires-Dist: openai<3,>=2.0
 Requires-Dist: platformdirs<5,>=4
@@ -20,9 +20,14 @@ Learn a little. Practise with purpose. See your progress.
 StudyTrail is a terminal AI study coach. Bring your own compatible provider API
 key, add study notes, practise with quizzes, and track progress locally.
 
-Requires Python 3.12 or 3.13. Once this release is published, install it in an
-activated environment with `pip install studytrails`, or install an isolated CLI
-with `uv tool install studytrails`. Run `studytrails` to open the welcome menu.
+Requires Python 3.10 through 3.14. Install the latest release in an activated
+environment with `python -m pip install --upgrade studytrails`, or install an
+isolated CLI with `uv tool install --upgrade studytrails`. Run `studytrails` to
+open the welcome menu.
+
+Created by Yash Patil, a Python and AI learner. The project uses OpenAI's Python
+SDK for compatible chat APIs. OpenAI created the GPT-OSS model family; the API host
+may be another provider, such as Groq. Users may configure other model families.
 
 ## Features
 

{studytrails-0.2.0 → studytrails-0.2.2}/README.md

@@ -6,38 +6,46 @@
 
 **Learn a little. Practise with purpose. See your progress.**
 
-StudyTrail is a terminal study coach for Python, Java, and other subjects. Bring
-an API key from a compatible provider, add your notes, and practise with quizzes.
-Your progress stays on your computer. You do not need to run a server.
+StudyTrail is a terminal study coach for Python, Java, and other subjects. Bring
+an API key from a compatible provider, add your notes, and practise with quizzes.
+Your progress stays on your computer. You do not need to run a server.
+
+StudyTrail was created by Yash Patil, a Python and AI learner. The project uses
+OpenAI's Python SDK for compatible chat APIs. OpenAI created the GPT-OSS model
+family; the API host may be another provider, such as Groq, and users can select
+other model families too.
 
-**Python 3.12 or 3.13 | Your choice of compatible AI provider | Local progress**
+**Python 3.10–3.14 | Your choice of compatible AI provider | Local progress**
 
 ## Get started
 
-This version is prepared for packaging but **has not been published to PyPI**.
-Do not assume a package currently using the name `studytrails` is this project.
-
-From the source checkout:
-
-```powershell
-cd C:\CLAUDE_env\Study_Agent_python
-uv sync --locked
-uv run studytrails
-```
-
-If uv is not on your terminal PATH after installation, run the existing environment:
-
-```powershell
-& .\.venv\Scripts\studytrails.exe
-```
-
-The original command also works: `python -m study_agent` in the activated environment.
-Keep development environments under `C:\CLAUDE_env`; do not install into system Python.
-
-After the maintainer publishes a verified release, users will be able to install it
-in an activated Python environment with `pip install studytrails`, or use
-`uv tool install studytrails` for an isolated command-line installation. They can
-then run `studytrails` from any directory.
+Install the published release in a virtual environment (recommended for people new
+to Python):
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install studytrails
+studytrails
+```
+
+On macOS/Linux, use these commands instead:
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install studytrails
+studytrails
+```
+
+After activating `.venv`, users can run `studytrails` whenever they open a new
+terminal for that environment. See the [downloadable setup guide](docs/SETUP.md)
+for uv installation, first-run configuration, and troubleshooting.
+
+For a one-time isolated CLI installation, `uv tool install studytrails` installs
+the command so it can run from any directory without activating a virtual environment.
 
 ## First launch
 

{studytrails-0.2.0 → studytrails-0.2.2}/docs/PYPI.md

@@ -5,9 +5,14 @@ Learn a little. Practise with purpose. See your progress.
 StudyTrail is a terminal AI study coach. Bring your own compatible provider API
 key, add study notes, practise with quizzes, and track progress locally.
 
-Requires Python 3.12 or 3.13. Once this release is published, install it in an
-activated environment with `pip install studytrails`, or install an isolated CLI
-with `uv tool install studytrails`. Run `studytrails` to open the welcome menu.
+Requires Python 3.10 through 3.14. Install the latest release in an activated
+environment with `python -m pip install --upgrade studytrails`, or install an
+isolated CLI with `uv tool install --upgrade studytrails`. Run `studytrails` to
+open the welcome menu.
+
+Created by Yash Patil, a Python and AI learner. The project uses OpenAI's Python
+SDK for compatible chat APIs. OpenAI created the GPT-OSS model family; the API host
+may be another provider, such as Groq. Users may configure other model families.
 
 ## Features
 

{studytrails-0.2.0 → studytrails-0.2.2}/docs/RELEASING.md

@@ -1,23 +1,22 @@
 # Releasing StudyTrail
 
-The package is prepared locally. No upload or public release is performed by setup,
-tests, or CI. The distribution name is `studytrails`; the import remains `study_agent`.
-Version 0.2.0 adds packaging, personal settings, provider setup, and subject notes.
+The distribution name is `studytrails`; the import remains `study_agent`.
+Versions 0.2.0 and 0.2.1 are published on PyPI. Version 0.2.2 is the next local candidate.
+Build, tests, and CI do not publish a release.
 
-## Before the first release
+## Before each release
 
-1. Create your PyPI account and enable two-factor authentication. Check the current
-   availability of `studytrails` on PyPI and TestPyPI separately. A missing project
-   page is not a reservation or a guarantee that PyPI will accept the name.
+1. Choose a new version in `pyproject.toml`. PyPI versions cannot be overwritten;
+   check that the version has not already been published.
 2. Review the MIT licence and package metadata. Add your public repository URL to
    `[project.urls]` when ready; no repository URL is invented by this project.
 3. Check package contents for accidental secrets, databases, or personal notes.
    Wheels include only the `study_agent` package and its bundled example notes.
    Source distributions use an explicit allowlist. `notes/`, `.env`, and `data/`
    from the local checkout are not published.
-4. Update the README's unpublished status only when the release is actually live.
-   Use absolute public links/images in the PyPI description if adding repository
-   branding there. The package uses a self-contained `docs/PYPI.md` description.
+4. Commit and push the reviewed source to GitHub. Use absolute public links/images
+   in the PyPI description if adding repository branding there. The package uses a
+   self-contained `docs/PYPI.md` description.
 
 ## Build and verify
 
@@ -50,20 +49,19 @@ TestPyPI is a separate service with separate accounts, tokens, and project names
 Install dependencies from the regular index when testing a TestPyPI package; avoid
 blindly combining indexes for production installs.
 
-For an explicitly approved manual release, uv supports:
+For a manual release, first review the files listed under `dist/`, then publish:
 
 ```powershell
-uv publish dist/studytrails-0.2.0-py3-none-any.whl dist/studytrails-0.2.0.tar.gz
+uv publish
 ```
 
 Supply authentication securely as documented by uv. This command publishes publicly;
-it is not part of the build/test workflow. Inspect the exact two artifacts before
-running it. A published version cannot simply be replaced with different contents;
-increment the version for a correction.
+it is not part of the build/test workflow. A published version cannot be replaced
+with different contents; increment the version for a correction.
 
-After publishing, test a fresh install of the exact published version and update
-the README. Users can then run `pip install studytrails` in an activated environment
-or `uv tool install studytrails`, followed by `studytrails`.
+After publishing, confirm the new version on PyPI and install it in a fresh
+environment. Users can update with `python -m pip install --upgrade studytrails`
+or `uv tool upgrade studytrails`.
 
 References: [uv publishing](https://docs.astral.sh/uv/guides/package/),
 [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/), and

studytrails-0.2.2/docs/SETUP.md

@@ -0,0 +1,187 @@
+# StudyTrail setup guide
+
+This guide helps you install StudyTrail on a new computer. It is a terminal app:
+you install it once, then run `studytrails` from PowerShell, Terminal, or a shell.
+
+StudyTrail is free and MIT licensed. Live AI uses an API key from a compatible
+provider. Your provider controls its own free allowance, usage limits, and charges.
+You can use the offline demo without an API key.
+
+## 1. Install Python
+
+StudyTrail supports Python **3.10, 3.11, 3.12, 3.13, and 3.14**. Python 3.12 is
+shown in the commands below; replace `3.12` with your installed version when you
+want to use another supported release. The `openai` library used by StudyTrail
+requires Python 3.10 or newer.
+
+- **Windows:** Install Python from [python.org](https://www.python.org/downloads/).
+  In the installer, enable **Add python.exe to PATH**. Then open a new PowerShell
+  window and check `py --version`.
+- **macOS:** Install Python 3.10–3.14 from [python.org](https://www.python.org/downloads/)
+  or your preferred package manager. Check `python3.12 --version`.
+- **Linux:** Install Python 3.10–3.14 and its `venv` support using your
+  distribution's package manager. Check `python3.12 --version`.
+
+## 2. Install StudyTrail in its own environment
+
+An environment keeps StudyTrail's Python packages separate from other projects.
+Choose the instructions for your operating system. Run the commands in the folder
+where you want to keep this environment; create a folder first if needed.
+
+### Windows PowerShell
+
+```powershell
+mkdir StudyTrail
+cd StudyTrail
+py -3.12 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install studytrails
+studytrails
+```
+
+If PowerShell blocks activation, use this for the current terminal only, then
+activate the environment again:
+
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
+.\.venv\Scripts\Activate.ps1
+```
+
+Or skip activation and run the installed command directly:
+
+```powershell
+.\.venv\Scripts\studytrails.exe
+```
+
+### macOS or Linux
+
+```bash
+mkdir StudyTrail
+cd StudyTrail
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install studytrails
+studytrails
+```
+
+If your system's `python3.12` command has another name, use the command for your
+chosen supported Python version to create the environment.
+
+### Optional: install uv
+
+You can use [uv](https://docs.astral.sh/uv/getting-started/installation/) to
+install StudyTrail as an isolated command-line tool. After installing uv, run:
+
+```powershell
+uv tool install studytrails
+uv tool update-shell
+```
+
+On macOS or Linux, the commands are the same. Open a new terminal after
+`uv tool update-shell`, then run `studytrails` from any folder. If the command
+is still not found, follow uv's PATH instructions for your shell.
+
+## 3. Set up an AI provider (optional)
+
+The first run opens a welcome menu. Choose **Configure AI** to use live coaching.
+You will need:
+
+1. An API key from a provider you choose.
+2. The provider's API address, if you choose a custom OpenAI-compatible endpoint.
+3. A model ID that your provider account can access and that supports
+   OpenAI-compatible Chat Completions with tool calling.
+
+StudyTrail offers address presets for OpenAI and Groq. A preset only fills in the
+provider address; it does not provide a key or guarantee every model will work.
+For another compatible service, choose the custom endpoint option and enter its
+API base URL and model ID. StudyTrail cannot use provider APIs with an incompatible
+request format in this release.
+
+The key prompt is hidden while you type. Paste the key only into that prompt. Do
+not paste it into the provider number or model prompt, a command line, this guide,
+or a public issue. Setup can make an optional small connection test; the request
+may use provider quota or incur charges. Choose **No** to skip it.
+
+StudyTrail stores API keys in a supported operating-system credential manager.
+Provider usage and billing are controlled by the provider. Review your provider's
+plan and limits before making live requests. Each study interaction may use more
+than one request.
+
+To configure later, run:
+
+```text
+studytrails config
+```
+
+## 4. Start studying
+
+In the welcome menu, select **Start learning** to chat with the coach. Select
+**Manage notes** to paste notes or import a UTF-8 `.txt` or `.md` file; choose a
+subject such as `python`, `java`, or `biology`. When pasting, enter `.done` on a
+line by itself to save the note. Then start learning and choose the same subject
+to search those notes.
+
+Try asking:
+
+```text
+Explain Java inheritance using my notes, then give me two beginner questions.
+```
+
+The app includes sample Python and Java notes. Notes are searched by keywords;
+PDF and Word files are not supported. Note excerpts and study requests are sent to
+the AI provider you configured. Avoid adding private information unless you are
+comfortable sharing it with that provider.
+
+If you want to try the app without an API key, choose **Offline demo** from the
+menu. It runs a fixed Python quiz and stores demo results separately from your
+regular progress. It is not a local AI model.
+
+## 5. Run StudyTrail next time
+
+For a virtual environment installation, open a new terminal, go to the folder
+where you installed StudyTrail, activate `.venv`, then type `studytrails`:
+
+```powershell
+cd .\StudyTrail
+.\.venv\Scripts\Activate.ps1
+studytrails
+```
+
+The macOS/Linux activation command is `source .venv/bin/activate`. If you used
+`uv tool install`, simply open a new terminal and type `studytrails`.
+
+## 6. Find your notes and progress
+
+Run this command from an activated environment or uv tool installation:
+
+```text
+studytrails doctor
+```
+
+It reports the local folder used for your settings, notes, and progress. Installed
+releases store these under your operating-system application data directory.
+Your progress belongs to your computer and is not automatically uploaded or
+synchronized.
+
+## Troubleshooting
+
+- **`studytrails` is not recognized / command not found:** activate the same
+  virtual environment where you installed it. With uv, open a new terminal after
+  `uv tool update-shell` and check uv's PATH instructions.
+- **Python version error:** use Python 3.10 through 3.14 and recreate the `.venv`
+  with that version.
+- **PowerShell says scripts are disabled:** use the current-terminal command in
+  the Windows section above, then activate again.
+- **401 / authentication failed:** run `studytrails config` and check that the key
+  belongs to the displayed provider address. Never share the key in a support
+  request.
+- **404 / model not found:** check the exact model ID and that the account can use
+  it. Also verify the provider address.
+- **429 / quota exceeded:** check the provider's current plan, rate limit, or
+  quota reset time.
+- **Want to test without an API:** select **Offline demo** in the menu.
+
+For more features and command details, see the
+[user guide](USER_GUIDE.md) and [project README](../README.md).

{studytrails-0.2.0 → studytrails-0.2.2}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "studytrails"
-version = "0.2.0"
+version = "0.2.2"
 description = "A personal multi-subject AI study coach with tools, local progress, and an offline demo."
 readme = "docs/PYPI.md"
 license = "MIT"
 license-files = ["LICENSE"]
-requires-python = ">=3.12,<3.14"
+requires-python = ">=3.10,<3.15"
 dependencies = [
     "openai>=2.0,<3",
     "pydantic>=2.0,<3",

{studytrails-0.2.0 → studytrails-0.2.2}/study_agent/agent.py

@@ -9,8 +9,14 @@ from pydantic import ValidationError
 from .config import Settings
 from .tools import StudyTools, tool_definitions
 
-INSTRUCTIONS = """You are a practical personal multi-subject study coach for a beginner.
-Use plain English. Help the learner understand, practise, and improve.
+INSTRUCTIONS = """You are a practical personal multi-subject study coach for a beginner.
+StudyTrail was created by Yash Patil. If asked who created or made StudyTrail, say
+Yash Patil created the StudyTrail application and is learning Python and AI. The AI
+model is supplied by the provider configured by this user; credit OpenAI for an
+OpenAI model such as GPT-OSS, and name the configured provider as its API host when
+appropriate. Do not claim OpenAI created StudyTrail or guess other personal details
+about Yash Patil.
+Use plain English. Help the learner understand, practise, and improve.
 For practice recommendations, inspect get_scores first. Search local notes for the
 chosen topic before teaching or creating a quiz. Use recent attempts as well as totals.
 If no scores exist, say so and start at beginner level. Respect the learner's chosen topic.

{studytrails-0.2.0 → studytrails-0.2.2}/tests/test_agent.py

@@ -39,7 +39,7 @@ class ScriptedClient:
         return next(self.queue)
 
 
-def test_agent_uses_observations_and_creates_real_quiz(tools, quiz):
+def test_agent_uses_observations_and_creates_real_quiz(tools, quiz):
     client = ScriptedClient(
         [
             response(call("get_scores")),
@@ -56,10 +56,10 @@ def test_agent_uses_observations_and_creates_real_quiz(tools, quiz):
     assert json.loads(observations[0]["content"])["completed_quizzes"] == 0
     assert "loops.md" in observations[1]["content"]
     assert len(tools.store.pending_quizzes()) == 1
-    assert tools.store.get_scores()["completed_quizzes"] == 0
-
-
-def test_bad_tool_arguments_return_feedback_and_allow_recovery(tools):
+    assert tools.store.get_scores()["completed_quizzes"] == 0
+
+
+def test_bad_tool_arguments_return_feedback_and_allow_recovery(tools):
     client = ScriptedClient(
         [
             response(call("search_notes", "not-json")),