protocore 2.0.0a1__tar.gz

protocore-2.0.0a1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,53 @@
+name: Bug report
+description: Report a reproducible bug
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug.
+        Please provide enough detail to reproduce and debug it.
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: What version are you using?
+      placeholder: "e.g. 1.0.0"
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version, runtime/backend details
+      placeholder: "macOS 15, Python 3.12, vLLM ..."
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. ...
+        2. ...
+        3. ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs/output
+      render: shell

protocore-2.0.0a1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

protocore-2.0.0a1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,32 @@
+name: Feature request
+description: Suggest a new feature or improvement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the idea.
+        Please describe the problem first, then the proposed solution.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What pain point does this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: API shape, behavior, compatibility considerations
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context

protocore-2.0.0a1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## What changed
+
+<!-- What the change does, in a sentence or two. -->
+
+## Why
+
+<!-- The reason it needed changing. If it fixes something subtle, what was the
+     symptom? -->
+
+## Checklist
+
+- [ ] `uv run pytest .` passes (tests plus the 90% coverage floor)
+- [ ] `uv run ruff check .` is clean
+- [ ] `uv run mypy --strict` is clean — no path argument, it replaces the
+      configured file list and silently skips the tests
+- [ ] `uv run bandit -r protocore -q -c pyproject.toml` is clean
+- [ ] Behaviour changes have a test that fails without the change
+- [ ] New tunables are `RuntimeConstants` fields with a description, and
+      default to the previous behaviour
+- [ ] Docs updated if anything user-facing moved

protocore-2.0.0a1/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  test-lint-typecheck:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: python -m pip install --upgrade uv
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run contract unit gate
+        id: contracts
+        run: uv run pytest tests/unit/contracts -q --no-cov
+
+      - name: Run full test suite
+        id: tests
+        run: uv run pytest . --cov=protocore --cov-fail-under=90
+
+      - name: Run lint gate
+        id: lint
+        run: uv run ruff check .
+
+      - name: Run strict typing gate
+        id: typing
+        # No path argument on purpose: a path on the command line REPLACES the
+        # configured `files` list, which silently drops the test tree and
+        # leaves every test double unchecked.
+        run: uv run mypy --strict
+
+      - name: Run security audit
+        id: security
+        run: uv run bandit -r protocore -q -c pyproject.toml
+
+      - name: Publish quality gate summary
+        if: always()
+        run: |
+          {
+            echo "## Quality Gate Summary"
+            echo ""
+            echo "- contract unit tests: ${{ steps.contracts.outcome }}"
+            echo "- full test suite: ${{ steps.tests.outcome }}"
+            echo "- lint: ${{ steps.lint.outcome }}"
+            echo "- strict typing: ${{ steps.typing.outcome }}"
+            echo "- security: ${{ steps.security.outcome }}"
+          } >> "$GITHUB_STEP_SUMMARY"

protocore-2.0.0a1/.gitignore

@@ -0,0 +1,42 @@
+# --- Python ---
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# --- Virtualenvs ---
+.venv/
+venv/
+.python-version
+
+# --- Tool caches ---
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.tox/
+.nox/
+
+# --- Coverage ---
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# --- Build output ---
+build/
+dist/
+
+# --- Lockfile ---
+# Protocore is a library: pinning a resolution here would push it onto every
+# consumer. The dependency floors in pyproject.toml are the contract.
+uv.lock
+
+# --- Editors ---
+.idea/
+.vscode/
+*.iml
+*.swp
+
+# --- OS ---
+.DS_Store
+Thumbs.db

protocore-2.0.0a1/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0a1]
+
+First public release.
+
+Protocore has existed for some time as the closed core of an agent product.
+This is that core, extracted and published under the MPL — the same code, with
+the parts that only made sense inside one company's repository rewritten to
+describe the boundary rather than the company.
+
+### Added
+
+- The protocol boundary: 20 interface `Protocol`s and an `IBlobStore` ABC in
+  `protocore/contracts/`, covering the model client, run and session stores,
+  the tool registry, memory, workspace, search, blobs, skills, todos, hooks,
+  event transport, and subagent dispatch.
+- The ReAct runtime: `QueryEngine` plus `query()`, driving one agent turn at a
+  time and emitting typed `TurnEvent`s. Snapshot and resume are first-class.
+- A three-layer tool surface — tenant policy, a lean clipped surface, and
+  progressive discovery over BM25 retrieval — with a permission gate ahead of
+  dispatch and a shell-safety policy behind a real command-chain parser.
+- Two-tier context compaction, session memory folding, and a token-budget model
+  that keeps a long run inside its window.
+- `RuntimeConstants`: 524 per-tenant tunables as a frozen Pydantic snapshot,
+  every one of them documented, with new behaviour defaulting off.
+- In-memory adapters (`protocore.tests_support.adapters`) that implement the
+  same protocols the real ones do, so a turn runs end to end with no external
+  services.
+- Documentation in English and Russian under `docs/`.
+- 2964 tests, a 90% coverage floor, strict typing, lint, and a security scan,
+  all gated on Python 3.12, 3.13, and 3.14.
+
+[Unreleased]: https://github.com/ascorblack-labs/protocore-community/compare/v2.0.0a1...HEAD
+[2.0.0a1]: https://github.com/ascorblack-labs/protocore-community/releases/tag/v2.0.0a1

protocore-2.0.0a1/CODE_OF_CONDUCT.md

@@ -0,0 +1,45 @@
+# Code of Conduct
+
+## Our pledge
+
+We want participating in this project to be a straightforwardly good use of
+your time, regardless of your age, body size, disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Standards
+
+Things that make this project work:
+
+- Assuming the other person is trying to help.
+- Critiquing the code rather than the person who wrote it.
+- Accepting a "no" gracefully, and giving reasons with your own.
+- Saying when you were wrong.
+
+Things that do not:
+
+- Harassment, public or private.
+- Insults, or personal or political attacks.
+- Sexualised language or imagery, and unwelcome sexual attention.
+- Publishing someone's private information without their explicit permission.
+
+## Scope
+
+This applies in the issue tracker, in pull requests, in discussions, and
+anywhere someone is representing the project in public.
+
+## Enforcement
+
+Report a problem to the maintainers privately, through GitHub. Reports are
+handled confidentially and you will get a response.
+
+Maintainers may edit or remove contributions that do not fit these standards,
+and may temporarily or permanently ban anyone whose behaviour they judge
+inappropriate. Where a maintainer takes such an action they will say so and
+say why.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

protocore-2.0.0a1/CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to Protocore
+
+Thanks for considering it. This document is short because the project has few
+rules — but the ones it has are load-bearing.
+
+## The one rule that is not negotiable
+
+**The core never imports upward.** `protocore/` may import from `protocore` and
+from its four runtime dependencies. It may not import any package whose name
+begins `protocore_`, and it may not grow a database driver, an HTTP client, a
+cloud SDK, or a model-provider SDK.
+
+If the core needs something from the outside, that need is expressed as a
+`Protocol` in `protocore/contracts/` and injected. `tests/test_core_import_boundary.py`
+enforces this and will fail your pull request rather than argue about it.
+
+## Setup
+
+```bash
+uv sync --extra dev
+```
+
+Python ≥ 3.12. No services, no containers, no fixtures to provision — the whole
+suite runs offline against in-memory doubles and finishes in well under a minute.
+
+## The gates
+
+Run all four before you open a pull request. CI runs the same ones on Python
+3.12, 3.13, and 3.14.
+
+```bash
+uv run pytest .                                     # tests + 90% coverage floor
+uv run ruff check .                                 # lint
+uv run mypy --strict                                # typing, strict, no path argument
+uv run bandit -r protocore -q -c pyproject.toml     # security
+```
+
+Two things people trip over:
+
+- **Do not pass a path to `mypy`.** A path on the command line *replaces* the
+  configured `files` list, which silently excludes the test tree. Bare
+  `mypy --strict` checks the surface `pyproject.toml` declares.
+- **Do not pipe a gate into `tail` or `head`.** A shell pipeline reports the
+  *last* command's status, so a failing gate reads as a pass. Redirect to a file
+  and read the exit code separately. This is not hypothetical; the security gate
+  sat red for a while because of exactly this.
+
+## Conventions
+
+- **No magic numbers in the executable path.** A tunable value belongs on
+  `RuntimeConstants` as a field with a description, so an operator can change it
+  without a deploy. `protocore/constants.py` is only for memory-safety caps that
+  are not per-tenant.
+- **New behaviour defaults off**, or to a value that reproduces the previous
+  behaviour exactly. A tenant opts in deliberately; an upgrade never changes
+  what a running system does.
+- **No module-level mutable state.** No module-level dicts, no locks held as
+  module state. Correctness-affecting state lives per-run on the `QueryEngine`
+  so the runtime stays safe to scale horizontally.
+- **Log at WARNING or above** on paths that run in production. `logger.info` in
+  the hot loop is noise someone else has to pay for.
+- **Docstrings explain why**, not what. The code says what it does. The comment
+  is for the reason it does it that way — usually a failure mode that is not
+  obvious from the surrounding lines.
+
+## Tests
+
+A change to behaviour needs a test that fails without it. The suite is large
+(2964 tests) precisely so that the loop's edge cases stay pinned; adding to it is
+the normal cost of a change, not an extra.
+
+Coverage is enforced at 90% and the current margin is thin. If your change adds
+a branch, cover it.
+
+## Commits and pull requests
+
+Write the commit message for someone reading `git log` in a year with no other
+context. Say what changed and why it needed changing; if the change fixes
+something subtle, say what the symptom was.
+
+Keep a pull request to one concern. A refactor bundled with a behaviour change
+is two reviews wearing one hat, and the behaviour change is the one that gets
+skimmed.
+
+## Reporting bugs
+
+Open an issue with a reproduction. A failing test is the ideal form of one.
+
+Security problems do **not** go in the issue tracker — see
+[`SECURITY.md`](SECURITY.md).
+
+## License of contributions
+
+By contributing you agree that your contribution is licensed under the
+[Mozilla Public License 2.0](LICENSE), the same terms as the rest of the
+project. There is no CLA.