mcts-agent 0.1.0__tar.gz

mcts_agent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    name: Test & Lint (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    env:
+      MCTS_AGENT_DISABLE_UPDATE_CHECK: "1"
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -e .
+          pip install pytest
+
+      - name: Run unit tests
+        env:
+          USE_MOCK_PRIMITIVES: "true"
+        run: |
+          python -m pytest tests -v
+
+      - name: Verify CLI Mock Run
+        env:
+          USE_MOCK_PRIMITIVES: "true"
+        run: |
+          python main.py --mock --max-steps 1 --iterations 2
+
+      - name: Verify research CLI offline
+        run: |
+          mcts_research_workspace=$(mktemp -d)
+          mcts-agent research --query "Investigate a test question" --workspace "$mcts_research_workspace" --mock --max-steps 1 --json

mcts_agent-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,82 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  test-and-build:
+    name: Test and build distributions
+    runs-on: ubuntu-latest
+    env:
+      MCTS_AGENT_DISABLE_UPDATE_CHECK: "1"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install project and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Run tests
+        env:
+          USE_MOCK_PRIMITIVES: "true"
+        run: python -m pytest tests -v
+      - name: Verify tag and package version match
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PACKAGE_VERSION="$(python -c 'from importlib.metadata import version; print(version("mcts-agent"))')"
+          test "$TAG_VERSION" = "$PACKAGE_VERSION"
+      - name: Build wheel and source distribution
+        run: |
+          python -m pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/*
+          if-no-files-found: error
+
+  github-release:
+    name: Create GitHub Release
+    needs: test-and-build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist
+      - uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          generate_release_notes: true
+          files: dist/*
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: github-release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mcts-agent
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

mcts_agent-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv
+.venv/
+venv/
+ENV/
+env/
+env.bak/
+venv.bak/
+
+# Environment variables & secrets
+.env
+.env.*
+!.env.example
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+agent/_version.py
+
+# Testing & linting caches
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# IDE / Editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Operating system files
+.DS_Store
+Thumbs.db
+
+# Workspace / runtime scratch
+scratch/
+logs/
+.mcts-research/
+mock-observation-*.txt

mcts_agent-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing to MCTS-Agent
+
+Thank you for your interest in contributing to **MCTS-Agent**! We welcome bug reports, feature suggestions, documentation enhancements, and code contributions.
+
+---
+
+## Code of Conduct
+
+Please be respectful, collaborative, and constructive when engaging in this project. Treat fellow contributors with kindness.
+
+---
+
+## Development Setup
+
+### 1. Clone the Repository
+```bash
+git clone https://github.com/<your-username>/mcts-agent.git
+cd mcts-agent
+```
+
+### 2. Create and Activate a Virtual Environment
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+### 3. Install Dependencies
+```bash
+pip install --upgrade pip
+pip install -r requirements.txt
+pip install -e ".[dev]"
+```
+
+---
+
+## Running Tests
+
+Tests run using Python's standard `unittest` framework or `pytest` with mock primitives enabled by default (`USE_MOCK_PRIMITIVES=true`):
+
+```bash
+# Run via unittest
+python3 -m unittest discover tests
+
+# Or run via pytest
+pytest -v
+```
+
+All test cases in `tests/` execute hermetically and require no external API keys.
+
+---
+
+## Running the Agent Locally
+
+### Mock Mode (Zero API Keys)
+Verify that the full search and execution loop functions:
+```bash
+python3 main.py --mock
+```
+
+### Pure MCTS Tree Search
+To run tree search with deep iterations:
+```bash
+python3 run_pure_mcts.py 10
+```
+
+### Live Mode
+Set your environment variables in `.env`:
+```bash
+TYPESAFE_API_KEY=your_typesafe_api_key
+```
+And ensure your Gemini environment (or `agy` CLI) is available:
+```bash
+python3 main.py
+```
+
+---
+
+## Pull Request Guidelines
+
+1. **Create a branch**: Use a descriptive branch name (e.g. `feature/parallel-eval` or `fix/puct-fpu-calc`).
+2. **Follow style guidelines**:
+   - Write clean, type-annotated Python (`typing` / Python 3.10+ annotations).
+   - Maintain docstrings for modules, classes, and public functions.
+3. **Add tests**: Any new feature or bug fix must include tests in `tests/`.
+4. **Ensure clean CI**: Verify that all tests pass locally before opening a pull request.
+5. **Write clear commit messages**: Describe the *what* and *why* of the change.
+
+---
+
+## Questions & Discussions
+
+Feel free to open an Issue on GitHub for any architecture questions, bug reports, or feature proposals.

mcts_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCTS-Agent Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.