deepseek-cordis 0.1.0__tar.gz

deepseek_cordis-0.1.0/.gitignore

@@ -0,0 +1,227 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# deepseek-cordis development tools
+.ruff_cache/
+.mypy_cache/
+.uv-cache/
+
+.vscode/

deepseek_cordis-0.1.0/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+## 0.1.0 — Unreleased
+
+- Completed the deepseek-cordis rebrand: Python imports and source package are
+  deepseek_cordis, repository/documentation links target akkefa/deepseek-cordis,
+  and logger/context metadata identifiers use the new namespace.
+
+- Selected deepseek-cordis as the PyPI distribution name after pending publisher
+  registration; the later full rebrand changed imports to deepseek_cordis.
+- Updated archive and installed-distribution checks for the distinct distribution
+  and import names, normalized artifact names, and release/documentation links.
+
+- Added matching-version GitHub tag releases to PyPI through Trusted Publishing,
+  gated by reusable CI and isolated build artifacts; documented one-time setup.
+- Added release-tag guard tests and made clean-wheel version checks read package
+  metadata so future releases do not require a hardcoded checker edit.
+
+- Phase 15: GitHub Actions checks for Python 3.11, 3.12 and 3.13; locked tools,
+  warnings-as-errors tests, lint/format/type checks, builds, distribution audits,
+  strict metadata validation and isolated wheel installation.
+- Expanded contribution guidance and GitHub readiness checklist. Source archives
+  now include CONTRIBUTING.md; runtime behavior and dependencies are unchanged.
+
+- Added opt-in packaging tools, strict metadata validation, and reproducible
+  archive and clean-wheel installation checkers.
+
+- Phase 14: alpha package metadata/version, project URLs, package-index README,
+  explicit source archive contents, distribution integrity checks and clean wheel
+  installation verification. Zero runtime dependencies and no implemented extras.
+- Package artifacts are prepared locally; nothing is uploaded or published.
+
+- Phase 13: README ownership-first walkthrough, checkout installation, services,
+  dependency/reactive lifecycle, effects, events, waterfall and lifecycle diagram.
+- Mental-model guide, ordered index for 16 runnable examples, five beginner examples,
+  current guide wording and attribution; no runtime behavior changes.
+
+- Phase 12: 23 pinned-source behavioral compatibility cases and a catalog integrity
+  check; 72 classified source tests with commits, lines, fingerprints and Python
+  evidence. Current compatibility matrix replaces stale status with explicit gaps.
+- Historical phase evidence moved to compatibility-history.md; pinned decorator
+  source wording corrected. No runtime behavior changed and no full parity claim made.
+
+- Phase 11: separate deterministic Loader, PluginEntry records/config rows, explicit
+  Python imports, batch ownership and actual Fiber inspection, preflight/rollback,
+  dependency settlement and cancellation cleanup; 34 new cases, guide, ADR and example.
+- Discovery, file formats, nested configuration groups, expressions/update hooks
+  and HMR remain deferred. No runtime dependencies added.
+
+- Phase 10: synchronous ConfigValidator protocol, structured ValidationIssue /
+  ValidationError, raw and resolved Fiber config, validation before each valid
+  activation, failure cleanup/restart recovery, 27 new cases, guide, ADR and example.
+- No schema runtime dependencies; async validation, loader expression/update hooks
+  and schema-aware operation config merging remain future work.
+
+- Phase 9: immutable PluginMeta, PluginSpec, identity-preserving plugin_meta
+  decorator, inspect_plugin, per-runtime/per-mount snapshots, Service provide-name
+  fallback, 30 metadata cases, guide, ADR and runnable example.
+- Explicit declarations replace conventional attributes; provide/intercept remain
+  descriptive for generic plugins. Validator execution and automatic method
+  injection remain deferred.
+
+- Phase 8: identity ScopeLabel isolation, slot-specific reactive notifications,
+  owned bindings separated from dependency snapshots, inherited/copied intercept
+  mappings and inject config, Service config merge/filter helpers, task-local
+  caller scopes across setup/cleanup/events, 31 scope test cases, docs and example.
+- Deliberate scope strengthening: slots key by service name plus label; require
+  verifies snapshot labels to prevent crossing changed isolation boundaries.
+
+
+- Phase 7: scoped Events facade, owned on/once, prepend/global/filter options,
+  emit/parallel/serial/bail/waterfall, dispatch diagnostics, 57 event test cases,
+  guide, ADR and runnable example.
+- Python event policy: emit/bail reject awaitable results; async waterfall bridges
+  synchronous tails; once guards recursive stale snapshots. Async dispatch is
+  caller-owned and cancellable, distinct from shielded Fiber lifecycle waits.
+
+
+- Phase 6: exported Service base class with declared/overridden name, defining
+  context, original config, owned registration, start/check hooks and native
+  callable subclasses; 25 service-class cases, guide, ADR and runnable example.
+
+
+- Phase 5: owned service bindings, get/set/require, reactive inject declarations,
+  activation/cleanup snapshots, provider availability notifications, joined
+  dependent teardown, 41 service cases, guide, ADR and runnable example.
+- Intentional compatibility strengthening: binding generation epochs detect
+  same-provider replacement during loading; structural ancestors are excluded
+  from service-removal joins to prevent awaiting their own cleanup.
+
+
+- Phase 4: root-local Registry, Context.plugin mounting, shared PluginRuntime
+  inspection, function/object/class forms, synchronous unregister with joined
+  teardown, 26 registry test cases, guide, ADR and runnable example.
+
+- Phase 3: Context/Fiber effects, nested sync/async collection, rollback and
+  joined in-flight cleanup, immutable diagnostics, 29 effect test cases and docs.
+- Deliberate compatibility deviation: drain remaining nested cleanup callbacks
+  after errors, then report single/aggregated failures.
+
+- Phase 2: root and mounted Fiber ownership, serialized lifecycle epochs,
+  setup/cleanup rollback, await/restart/disposal, reentrancy/cancellation policy,
+  30 Fiber tests, guide, ADR and example.
+
+- Phase 1: public Context with root/parent/owner identity, read-only inherited
+  metadata, shallow-copy extend, Context tests, guide, example and design ADR.
+
+- Phase 0: source audit, compatibility plan, uv-managed typed package scaffold,
+  development checks, and import smoke test.
+- Kernel event publication hooks, advanced method reflection and tracing remain future work; no release published.

deepseek_cordis-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to deepseek-cordis
+
+deepseek-cordis is an independent Python implementation of the Cordis runtime model
+used by DeepSeek Harness. Its `0.1.0` API is alpha and compatibility is partial.
+Start with [the mental model](docs/mental-model.md),
+[the compatibility matrix](docs/compatibility.md), and
+[the architecture decisions](docs/adr/0001-phase-0-foundation.md).
+
+## Set up a checkout
+
+Use Python 3.11, 3.12 or 3.13 and uv. From a local clone:
+
+```sh
+uv sync --locked --python 3.11 --group packaging
+uv run --locked --group packaging python examples/first_plugin.py
+```
+
+The lockfile is committed. `dev` supplies test, lint and type tools; the opt-in
+`packaging` group supplies Twine. Neither group adds runtime dependencies.
+Do not update dependency versions as a side effect of unrelated changes. For an
+intentional dependency change, update `pyproject.toml` and regenerate `uv.lock`.
+
+## Make a focused change
+
+Work one reviewed phase or issue at a time. Before changing runtime behavior,
+inspect the pinned vendored Harness source and corresponding Cordis tests.
+Describe the observed contract and how Python will express it, then add a
+behavior test that exercises public APIs. Cover failure and cleanup paths when
+resource ownership, cancellation or dependency activation changes.
+
+Keep upstream fixes distinct from the primary compatibility target. Record
+deliberate deviations in `docs/adr/`, and update the compatibility matrix and
+source-indexed catalog when changing compatibility claims. Preserve source
+attribution and third-party notices. Avoid framework and agent dependencies in
+the kernel. Do not claim full Cordis parity or live Harness support from Python
+unit tests alone.
+
+Keep API guides and runnable examples aligned with behavior. Update the changelog
+for user-facing changes. For design background, use the relevant existing ADR
+rather than documenting a second conflicting contract.
+
+## Check before proposing a change
+
+Run the same checks as CI:
+
+```sh
+uv run --locked --group packaging pytest -W error
+uv run --locked --group packaging ruff check .
+uv run --locked --group packaging ruff format --check .
+uv run --locked --group packaging mypy --python-version 3.11 src tests examples scripts
+uv build
+uv run --locked --group packaging python scripts/check_distribution.py \
+  dist/deepseek_cordis-0.1.0-py3-none-any.whl dist/deepseek_cordis-0.1.0.tar.gz
+uv run --locked --group packaging twine check --strict \
+  dist/deepseek_cordis-0.1.0-py3-none-any.whl dist/deepseek_cordis-0.1.0.tar.gz
+```
+
+For a full local version matrix, set `export UV_PYTHON=3.12`, run
+`uv sync --locked --group packaging`, then repeat the checks with mypy
+`--python-version 3.12`. Repeat with `UV_PYTHON=3.13` and the matching mypy flag.
+Keep `UV_PYTHON` set for every check so `uv run` uses the selected interpreter.
+Use `unset UV_PYTHON` afterward to restore uv's normal selection. Synchronization
+replaces the project environment when its Python version changes.
+For wheel installation checks, follow [packaging.md](docs/packaging.md): use a
+fresh environment containing only the built distribution, then run
+`scripts/check_installation.py` outside the checkout with isolated Python imports.
+
+CI runs on pushes to `main`, pull requests, and manual dispatch. It checks all
+three Python versions on Linux, including a fresh wheel installation. Local
+macOS results and GitHub-hosted results are reported separately. See
+[GitHub readiness](docs/github-readiness.md) for the checklist and workflow scope.
+
+## Propose a pull request
+
+Describe the concrete problem, changed behavior, relevant source evidence and
+Python-specific decisions. Include checks run, their Python versions, and any
+remaining gaps. Keep changes conceptually focused and avoid unrelated refactors.
+The maintainer reviews release decisions; preparing artifacts does not authorize
+publishing them. In agent-assisted work, suggest a commit message and do not
+commit or publish without the maintainer's explicit request.

deepseek_cordis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ikram Ali
+
+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.

deepseek_cordis-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: deepseek-cordis
+Version: 0.1.0
+Summary: Python plugin runtime targeting DeepSeek Harness vendored Cordis semantics
+Project-URL: Homepage, https://github.com/akkefa/deepseek-cordis
+Project-URL: Repository, https://github.com/akkefa/deepseek-cordis
+Project-URL: Issues, https://github.com/akkefa/deepseek-cordis/issues
+Project-URL: Documentation, https://github.com/akkefa/deepseek-cordis/tree/main/docs
+Project-URL: Changelog, https://github.com/akkefa/deepseek-cordis/blob/main/CHANGELOG.md
+Author: Ikram Ali
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# deepseek-cordis
+
+A lightweight Python plugin runtime for services, reactive dependencies, owned
+effects and events. Python 3.11+; no runtime dependencies.
+
+PyPI distribution: `deepseek-cordis`. Python import: `deepseek_cordis`.
+
+Version 0.1.0 is an alpha API. deepseek-cordis adapts the ownership model of the vendored
+Cordis 4.0.4 runtime used by DeepSeek Harness at commit
+`639ed015397290b3745d163aafe02ffee4aa3f84`. It is an independent implementation,
+not the Harness application or an affiliated Cordis/DeepSeek product.
+
+## First plugin
+
+```python
+import asyncio
+from deepseek_cordis import Context
+
+
+def greeter(ctx: Context, config: object) -> object:
+    ctx.on("hello", lambda name: print("Hello,", name))
+    return lambda: print("Greeter stopped")
+
+
+async def main() -> None:
+    root = Context()
+    fiber = await root.plugin(greeter)
+    root.emit("hello", "Cordis")
+    await fiber.dispose()
+
+
+asyncio.run(main())
+```
+
+The Fiber owns the listener and returned cleanup. Disposal removes the listener
+and joins teardown. Named services can gate consumers through declared dependencies;
+provider loss unloads them and restoration starts a new activation. Context views
+share an owner unless a new plugin is mounted.
+
+## Features and boundaries
+
+- Sync/async setup, owned cleanup, generator effects and nested plugin lifetimes.
+- Scoped service bindings, reactive injection, caller intercept options and Service classes.
+- Owned events with emit, parallel, serial, bail and waterfall dispatch.
+- Explicit plugin metadata, synchronous config validation and deterministic loader batches.
+- Typed package with a py.typed marker.
+
+Compatibility is partial. Transparent method/property proxies, method injection,
+LoggerService exporters, kernel publication hooks, Fiber.update and advanced loader
+configuration/HMR remain unimplemented. Passing Python tests does not establish full
+Cordis or live DeepSeek Harness compatibility. There are no schema adapter extras.
+
+## Documentation
+
+- [Source and full walkthrough](https://github.com/akkefa/deepseek-cordis)
+- [Runtime mental model](https://github.com/akkefa/deepseek-cordis/blob/main/docs/mental-model.md)
+- [Runnable examples](https://github.com/akkefa/deepseek-cordis/blob/main/examples/README.md)
+- [Compatibility matrix](https://github.com/akkefa/deepseek-cordis/blob/main/docs/compatibility.md)
+- [Packaging and local installation](https://github.com/akkefa/deepseek-cordis/blob/main/docs/packaging.md)
+- [Issues](https://github.com/akkefa/deepseek-cordis/issues)
+- [Changelog](https://github.com/akkefa/deepseek-cordis/blob/main/CHANGELOG.md)
+
+MIT licensed, copyright 2026 Ikram Ali. Cordis (Shigma) and DeepSeek Harness
+(DeepSeek) are MIT-licensed behavioral references. The distribution includes the
+project license and retained third-party notices; the full
+[attribution](https://github.com/akkefa/deepseek-cordis/blob/main/THIRD_PARTY_NOTICES.md)
+is also available in the source repository.