dspyteach

Name	dspyteach JSON
Version	0.1.2b1 JSON
	download
home_page	None
Summary	CLI utility that summarizes single files into teaching briefs using DSPy
upload_time	2025-10-06 19:29:40
maintainer	None
docs_url	None
author	DSPy File Maintainers
requires_python	<3.12,>=3.10
license	None
keywords	dspy teaching summaries cli
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # dspyteach – DSPy File Teaching Analyzer

This folder contains a DSPy-powered CLI that analyzes source files (one or many) and produces teaching briefs. Each run captures:

- an overview of the file and its major sections
- key teaching points, workflows, and pitfalls highlighted in the material
- a polished markdown brief suitable for sharing with learners

The implementation mirrors the multi-file tutorial (`tutorials/multi-llmtxt_generator`) but focuses on per-file inference. The program is split into:

- `dspy_file/signatures.py` – DSPy signatures that define inputs/outputs for each step
- `dspy_file/file_analyzer.py` – the main DSPy module that orchestrates overview, teaching extraction, and report composition. It now wraps the final report stage with `dspy.Refine`, pushing for 450–650+ word briefs.
- `dspy_file/file_helpers.py` – utilities for loading files and rendering the markdown brief
- `dspy_file/analyze_file_cli.py` – command line entry point that configures the local model and prints results. It can walk directories, apply glob filters, and batch-generate briefs.

## Requirements

- Python 3.12+
- DSPy installed in the environment
- Ollama running locally with the model `hf.co/Mungert/osmosis-mcp-4b-GGUF:Q4_K_M` available
- (Optional) `.env` file for any additional DSPy configuration; `dotenv` is loaded automatically

Install the Python dependencies if you have not already:

```bash
uv init

uv venv -p 3.12
source .venv/bin/activate
```

```bash
uv pip install dspy python-dotenv
```

```bash
uv sync
```

```bash
ollama pull hf.co/Mungert/osmosis-mcp-4b-GGUF:Q4_K_M
```

```bash
uv pip install dspyteach
```

```bash
# install the package locally (editable or regular)
uv pip install -e .
```

## Usage

Run the CLI to extract a teaching brief from a single file:

```bash
dspyteach path/to/your_file
```

You can also point the CLI at a directory. The tool will recurse by default:

```bash
dspyteach path/to/project --glob "**/*.py" --glob "**/*.md"
```

Use `--non-recursive` to stay in the top-level directory, add `--glob` repeatedly to narrow the target set, and pass `--raw` to print the raw DSPy prediction object instead of the formatted report.

To change where reports land, supply `--output-dir /path/to/reports`. When omitted the CLI writes to `dspy_file/data/` next to the module. Every run prints the active model name and the resolved output directory before analysis begins so you can confirm the environment at a glance. For backwards compatibility the installer also registers `dspy-file-teaching` as an alias.

Each analyzed file is saved under the chosen directory with a slugged name (e.g. `src__main.teaching.md`). If a file already exists, the CLI appends a numeric suffix to avoid overwriting previous runs.

The generated brief is markdown that mirrors the source material:

- Overview paragraphs for quick orientation
- Section-by-section bullets capturing the narrative
- Key concepts, workflows, pitfalls, and references learners should review
- A `dspy.Refine` wrapper keeps retrying until the report clears a length reward (defaults scale to ~50% of the source word count, with min/max clamps), so the content tends to be substantially longer than a single LM call.
- If a model cannot honour DSPy's structured-output schema, the CLI prints a `Structured output fallback` notice and heuristically parses the textual response so you still get usable bullets.

Behind the scenes the CLI:

1. Loads environment variables via `python-dotenv`.
2. Configures DSPy with the same local Ollama model used in the tutorial.
3. Resolves all requested files, reads contents, runs the DSPy `FileTeachingAnalyzer` module, and prints a human-friendly report for each.
4. Persists each report to the configured output directory so results are easy to revisit.
5. Attempts to stop the Ollama model when finished, mirroring the fail-safe logic from the tutorial.

## Extending

- Adjust the `TeachingReport` signature or add new chains in `dspy_file/file_analyzer.py` to capture additional teaching metadata.
- Customize the render logic in `dspy_file.file_helpers.render_prediction` if you want richer CLI output or structured JSON.
- Tune `TeachingConfig` inside `file_analyzer.py` to raise `max_tokens`, adjust the `Refine` word-count reward, or add extra LM kwargs.
- Add more signatures and module stages to capture additional metadata (e.g., security checks) and wire them into `FileAnalyzer`.

## Packaging & Publishing

The repository is configured for standard Python packaging via `pyproject.toml` and the `setuptools` backend. A typical release flow with [`uv`](https://docs.astral.sh/uv/guides/package/) looks like:

```bash
# (optional) bump the version before you publish
uv version --bump patch

# build the source distribution and wheel; artifacts land in dist/
uv build --no-sources

# publish to PyPI (or TestPyPI) once you have an API token
UV_PUBLISH_TOKEN=... uv publish
```

If you want to stage a release first, point `uv publish --index testpypi` at the alternate index configured in `pyproject.toml`.

To install the package from a freshly built artifact:

```bash
pip install dist/dspyteach-0.1.1-py3-none-any.whl
```

Once the project is on PyPI, users can install it directly:

```bash
pip install dspyteach
```

After installation, the `dspyteach` console script (plus the legacy `dspy-file-teaching` alias) is available in any environment so you can run analyses outside of this repository or integrate the tool into CI jobs.

### CI Publishing

GitHub Actions users can trigger `.github/workflows/publish-testpypi.yml` to build and push the current checkout to TestPyPI. The workflow:

- Checks out the repository (ensuring `pyproject.toml` is present as required by uv publish).
- Installs uv with Python 3.12.
 - Runs `uv build --no-sources` from the repository root.
- Publishes with `uv publish --index testpypi dist/*` using the `TEST_PYPI_TOKEN` secret.

See the [uv publishing guide](https://docs.astral.sh/uv/guides/package/#publishing-your-package) for the official note about requiring a checkout when using `--index`.

## Troubleshooting

- If the program cannot connect to Ollama, verify that the server is running on `http://localhost:11434` and the requested model has been pulled.
- When you see `ollama command not found`, ensure the `ollama` binary is on your `PATH`.
- For encoding errors, the helper already falls back to `latin-1`, but you can add more fallbacks in `file_helpers.read_file_content` if needed.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "dspyteach",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<3.12,>=3.10",
    "maintainer_email": null,
    "keywords": "dspy, teaching, summaries, cli",
    "author": "DSPy File Maintainers",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/c5/d9/10ec1ae6fd98cf8918dfee1de265f0bc92f0032d039ff364c12e09c90961/dspyteach-0.1.2b1.tar.gz",
    "platform": null,
    "description": "# dspyteach \u2013 DSPy File Teaching Analyzer\n\nThis folder contains a DSPy-powered CLI that analyzes source files (one or many) and produces teaching briefs. Each run captures:\n\n- an overview of the file and its major sections\n- key teaching points, workflows, and pitfalls highlighted in the material\n- a polished markdown brief suitable for sharing with learners\n\nThe implementation mirrors the multi-file tutorial (`tutorials/multi-llmtxt_generator`) but focuses on per-file inference. The program is split into:\n\n- `dspy_file/signatures.py` \u2013 DSPy signatures that define inputs/outputs for each step\n- `dspy_file/file_analyzer.py` \u2013 the main DSPy module that orchestrates overview, teaching extraction, and report composition. It now wraps the final report stage with `dspy.Refine`, pushing for 450\u2013650+ word briefs.\n- `dspy_file/file_helpers.py` \u2013 utilities for loading files and rendering the markdown brief\n- `dspy_file/analyze_file_cli.py` \u2013 command line entry point that configures the local model and prints results. It can walk directories, apply glob filters, and batch-generate briefs.\n\n## Requirements\n\n- Python 3.12+\n- DSPy installed in the environment\n- Ollama running locally with the model `hf.co/Mungert/osmosis-mcp-4b-GGUF:Q4_K_M` available\n- (Optional) `.env` file for any additional DSPy configuration; `dotenv` is loaded automatically\n\nInstall the Python dependencies if you have not already:\n\n```bash\nuv init\n\nuv venv -p 3.12\nsource .venv/bin/activate\n```\n\n```bash\nuv pip install dspy python-dotenv\n```\n\n```bash\nuv sync\n```\n\n```bash\nollama pull hf.co/Mungert/osmosis-mcp-4b-GGUF:Q4_K_M\n```\n\n```bash\nuv pip install dspyteach\n```\n\n```bash\n# install the package locally (editable or regular)\nuv pip install -e .\n```\n\n## Usage\n\nRun the CLI to extract a teaching brief from a single file:\n\n```bash\ndspyteach path/to/your_file\n```\n\nYou can also point the CLI at a directory. The tool will recurse by default:\n\n```bash\ndspyteach path/to/project --glob \"**/*.py\" --glob \"**/*.md\"\n```\n\nUse `--non-recursive` to stay in the top-level directory, add `--glob` repeatedly to narrow the target set, and pass `--raw` to print the raw DSPy prediction object instead of the formatted report.\n\nTo change where reports land, supply `--output-dir /path/to/reports`. When omitted the CLI writes to `dspy_file/data/` next to the module. Every run prints the active model name and the resolved output directory before analysis begins so you can confirm the environment at a glance. For backwards compatibility the installer also registers `dspy-file-teaching` as an alias.\n\nEach analyzed file is saved under the chosen directory with a slugged name (e.g. `src__main.teaching.md`). If a file already exists, the CLI appends a numeric suffix to avoid overwriting previous runs.\n\nThe generated brief is markdown that mirrors the source material:\n\n- Overview paragraphs for quick orientation\n- Section-by-section bullets capturing the narrative\n- Key concepts, workflows, pitfalls, and references learners should review\n- A `dspy.Refine` wrapper keeps retrying until the report clears a length reward (defaults scale to ~50% of the source word count, with min/max clamps), so the content tends to be substantially longer than a single LM call.\n- If a model cannot honour DSPy's structured-output schema, the CLI prints a `Structured output fallback` notice and heuristically parses the textual response so you still get usable bullets.\n\nBehind the scenes the CLI:\n\n1. Loads environment variables via `python-dotenv`.\n2. Configures DSPy with the same local Ollama model used in the tutorial.\n3. Resolves all requested files, reads contents, runs the DSPy `FileTeachingAnalyzer` module, and prints a human-friendly report for each.\n4. Persists each report to the configured output directory so results are easy to revisit.\n5. Attempts to stop the Ollama model when finished, mirroring the fail-safe logic from the tutorial.\n\n## Extending\n\n- Adjust the `TeachingReport` signature or add new chains in `dspy_file/file_analyzer.py` to capture additional teaching metadata.\n- Customize the render logic in `dspy_file.file_helpers.render_prediction` if you want richer CLI output or structured JSON.\n- Tune `TeachingConfig` inside `file_analyzer.py` to raise `max_tokens`, adjust the `Refine` word-count reward, or add extra LM kwargs.\n- Add more signatures and module stages to capture additional metadata (e.g., security checks) and wire them into `FileAnalyzer`.\n\n## Packaging & Publishing\n\nThe repository is configured for standard Python packaging via `pyproject.toml` and the `setuptools` backend. A typical release flow with [`uv`](https://docs.astral.sh/uv/guides/package/) looks like:\n\n```bash\n# (optional) bump the version before you publish\nuv version --bump patch\n\n# build the source distribution and wheel; artifacts land in dist/\nuv build --no-sources\n\n# publish to PyPI (or TestPyPI) once you have an API token\nUV_PUBLISH_TOKEN=... uv publish\n```\n\nIf you want to stage a release first, point `uv publish --index testpypi` at the alternate index configured in `pyproject.toml`.\n\nTo install the package from a freshly built artifact:\n\n```bash\npip install dist/dspyteach-0.1.1-py3-none-any.whl\n```\n\nOnce the project is on PyPI, users can install it directly:\n\n```bash\npip install dspyteach\n```\n\nAfter installation, the `dspyteach` console script (plus the legacy `dspy-file-teaching` alias) is available in any environment so you can run analyses outside of this repository or integrate the tool into CI jobs.\n\n### CI Publishing\n\nGitHub Actions users can trigger `.github/workflows/publish-testpypi.yml` to build and push the current checkout to TestPyPI. The workflow:\n\n- Checks out the repository (ensuring `pyproject.toml` is present as required by uv publish).\n- Installs uv with Python 3.12.\n - Runs `uv build --no-sources` from the repository root.\n- Publishes with `uv publish --index testpypi dist/*` using the `TEST_PYPI_TOKEN` secret.\n\nSee the [uv publishing guide](https://docs.astral.sh/uv/guides/package/#publishing-your-package) for the official note about requiring a checkout when using `--index`.\n\n## Troubleshooting\n\n- If the program cannot connect to Ollama, verify that the server is running on `http://localhost:11434` and the requested model has been pulled.\n- When you see `ollama command not found`, ensure the `ollama` binary is on your `PATH`.\n- For encoding errors, the helper already falls back to `latin-1`, but you can add more fallbacks in `file_helpers.read_file_content` if needed.\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "CLI utility that summarizes single files into teaching briefs using DSPy",
    "version": "0.1.2b1",
    "project_urls": null,
    "split_keywords": [
        "dspy",
        " teaching",
        " summaries",
        " cli"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "12ae9e0976e885bc993cb2ce67784e4445a06240e84fc861a11bb5a4f79bc1c9",
                "md5": "aa03dd90d8b51f424bc937d0edf5a027",
                "sha256": "14cba587e7b78fc799f985ac4dda85f68009e599f6079f0b4abd9ab5c16525c7"
            },
            "downloads": -1,
            "filename": "dspyteach-0.1.2b1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "aa03dd90d8b51f424bc937d0edf5a027",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<3.12,>=3.10",
            "size": 13327,
            "upload_time": "2025-10-06T19:29:39",
            "upload_time_iso_8601": "2025-10-06T19:29:39.912387Z",
            "url": "https://files.pythonhosted.org/packages/12/ae/9e0976e885bc993cb2ce67784e4445a06240e84fc861a11bb5a4f79bc1c9/dspyteach-0.1.2b1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "c5d910ec1ae6fd98cf8918dfee1de265f0bc92f0032d039ff364c12e09c90961",
                "md5": "f9283829e188db17033bd13d36e7a3f6",
                "sha256": "71553947937e5b2e727af379550303344e27961df89b7625fd7bef8b54f1c3db"
            },
            "downloads": -1,
            "filename": "dspyteach-0.1.2b1.tar.gz",
            "has_sig": false,
            "md5_digest": "f9283829e188db17033bd13d36e7a3f6",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<3.12,>=3.10",
            "size": 14613,
            "upload_time": "2025-10-06T19:29:40",
            "upload_time_iso_8601": "2025-10-06T19:29:40.965460Z",
            "url": "https://files.pythonhosted.org/packages/c5/d9/10ec1ae6fd98cf8918dfee1de265f0bc92f0032d039ff364c12e09c90961/dspyteach-0.1.2b1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-06 19:29:40",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "dspyteach"
}