Sync all changes from TypeAgent/python/ta/ since last sync

.github/workflows/release-py.yml

@@ -0,0 +1,65 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+name: Release (PyPI via Trusted Publishing + uv)
+
+on:
+  push:
+    tags: [ "v*" ]      # tag to publish
+  workflow_dispatch:     # manual run
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: python/ta     # your project subdir
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Create .venv and install deps
+        run: uv sync
+
+      - name: Build sdist + wheel (via make)
+        run: make build                   # runs `uv build`, outputs to dist/
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: python/ta/dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/typeagent-py
+    permissions:
+      id-token: write     # REQUIRED for Trusted Publishing (no tokens!)
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # For TestPyPI first, add:
+        # with:
+        #   repository-url: https://test.pypi.org/legacy/

.gitignore

@@ -8,3 +8,5 @@ venv
 /evals
 /junk
 __pycache__
+testdata/MP/
+db

AGENTS.md

@@ -0,0 +1,102 @@
+---
+applyTo: '**/*.py'
+---
+
+**DO NOT BE OBSEQUIOUS**
+
+# For Agent mode
+
+**NEVER use TEST_MODEL_NAME or "test" embedding model outside of test files**
+
+Never run git commands that many any changes. (`git status` and `git diff` are fine)
+
+**NEVER COMMIT CODE. Do not run `git commit` or any other git commands that make changes to the repository. Not even `git add`**
+
+When moving, copying or deleting files, use the git commands: `git mv`, `git cp`, `git rm`
+
+When the working directory is ~/TypeAgent/python/ta/:
+
+- Don't use '!' on the command line, it's some bash magic (even inside single quotes)
+- Activate `.venv`: make venv; source .venv/bin/activate
+- To get API keys in ad-hoc code, run `typeagent.aitools.utils.load_dotenv()`
+- Use pytest to run tests in test/
+- Use pyright to check type annotations in tools/, test/, typeagent/
+- Ignore build/, dist/
+- You can also use the pylance extension for type checking in VS Code
+- Use `make check` to type-check all files
+- Use `make test` to run all tests
+- Use `make check test` to run `make check` and if it passes also run `make test`
+
+## Package Management with uv
+
+- Use `uv add <package>` to add new dependencies
+- Use `uv add <package> --upgrade` to upgrade existing packages
+- **Important**: uv automatically updates `pyproject.toml` when adding/upgrading packages
+- **Do NOT** manually edit `pyproject.toml` dependency versions after running uv commands
+- uv maintains consistency between `pyproject.toml`, `uv.lock`, and installed packages
+- Trust uv's automatic version resolution and file management
+
+**IMPORTANT! YOU ARE NOT DONE UNTIL `make check test format` PASSES**
+
+# Code generation
+
+When generating Python code (e.g. when translating TypeScript to Python),
+please follow these guidelines:
+
+* When creating a new file, add a copyright header to the top:
+```
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+```
+
+* Assume Python 3.12
+
+* Always strip trailing spaces
+
+* Keep class and type names in `PascalCase`
+* Use `python_case` for variable/field and function/method names
+
+* Use `Literal` for unions of string literals
+* Keep union notation (`X | Y`) for other unions
+* Use `Protocol` for interfaces whose name starts with `I`
+  followed by a capital letter
+* Use `dataclass` for other classes and structured types
+* Use `type` for type aliases (`PascalCase` again)
+* Use `list`, `tuple`, `dict`, `set` etc., not `List` etc.
+
+* Translate `foo?: string` to `foo: str | None = None`
+
+* When writing tests:
+  - don't mock; use the regular implementation (maybe introduce a fixture to create it)
+  - assume `pytest`; use `assert` statements
+  - match the type annotations of the tested functions
+  - read the code of the tested functions to understand their behavior
+  - When using fixtures:
+    - Fully type-annotate the fixture definitions (including return type)
+    - Fully type-annotate fixture usages
+
+* Don't put imports inside functions.
+  Put them at the top of the file with the other imports.
+  Exception: imports in a `if __name__ == "__main__":` block or a `main()` function.
+  Another exception: pydantic and logfire.
+  Final exception: to avoid circular import errors.
+
+* **Import Architecture Rules**:
+  - **Never import a symbol from a module that just re-exports it**
+  - **Always import directly from the module that defines the symbol**
+  - **Exception**: Package `__init__.py` files that explicitly re-export with `__all__`
+  - **Exception**: Explicit re-export patterns like `from ... import X as X` or marked with "# For export"
+  - This prevents circular imports and makes dependencies clear
+
+* Order imports alphabetically after lowercasing; group them as follows
+  (with a blank line between groups):
+  1. standard library imports
+  2. established third-party libraries
+  3. experimental third-party libraries (e.g. `typechat`)
+  4. local imports (e.g. `from typeagent.knowpro import ...`)
+
+* **Error Handling**: Don't use `try/except Exception` to catch errors broadly.
+  Let errors bubble up naturally for proper error handling and debugging at higher levels.
+
+* **Code Validation**: Don't use `py_compile` for syntax checking.
+  Use `pyright` or `make check` instead for proper type checking and validation.

Makefile

@@ -45,7 +45,7 @@ scaling: venv
 
 .PHONY: build
 build: venv
-	.venv/bin/python -m build --wheel
+	uv build
 
 .PHONY: venv
 venv: .venv