dot-agora 2.0.0__tar.gz

dot_agora-2.0.0/.env.template

@@ -0,0 +1,7 @@
+# Real LLM runs: see dot-inference for every provider and setting
+DOTI_GENERATION__PROVIDER=openrouter
+DOTI_GENERATION__OPENROUTER__MODEL_NAME=openai/gpt-5-mini
+DOTI_GENERATION__OPENROUTER__API_KEY=
+
+# Web search participant
+LINKUP_API_KEY=

dot_agora-2.0.0/.gitignore

@@ -0,0 +1,63 @@
+# Python
+*.py[cod]
+*.pyo
+*.egg
+*.egg-info/
+**/__pycache__/
+*.so
+build/
+dist/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.ty_cache/
+.mypy_cache/
+
+# Coverage
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+coverage_html_report/
+
+# Environment & Secrets
+.venv/
+venv/
+.env
+.env.*
+!.env.template
+.envrc
+
+# IDE
+.vscode/
+.idea/
+
+# Agent config
+.agents/
+.claude/
+/graft/
+.ignore
+.mcp.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Local files
+local/
+sources/
+working-notes/
+/dev
+
+# Pin Python (overrides the global ignore)
+!.python-version
+
+# --- CI caches (UV_CACHE_DIR / PRE_COMMIT_HOME point here in .gitlab-ci.yml) ---
+# Not just local hygiene: hatchling would otherwise pull them into the sdist,
+# and a cached virtualenv carries absolute symlinks that break the build.
+.uv-cache/
+.pre-commit-cache/

dot_agora-2.0.0/.gitlab-ci.yml

@@ -0,0 +1,183 @@
+# Pipeline for a Python library published to PyPI.
+#
+#   quality  lint, format and type checks (pre-commit)
+#   test     pytest on every supported Python version
+#   publish  tag-only: build, then TestPyPI, then PyPI behind a manual gate
+#
+# Publishing uses PyPI Trusted Publishing (OIDC): GitLab mints a short-lived ID
+# token, PyPI exchanges it for a publish token valid for minutes. No API token
+# is stored in the project. Declare this repository as a trusted publisher at
+# https://pypi.org/manage/project/dot-agora/settings/publishing/ (and the same on
+# test.pypi.org) before the first release.
+
+workflow:
+  rules:
+    # Merge requests take priority...
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      when: always
+    # ...release tags (vX.Y.Z, or a candidate vX.Y.ZrcN: the PEP 440 spelling,
+    # since check_version compares the tag with the normalised project version)...
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+(?:rc\d+)?$/
+      when: always
+    # ...and pushes to main. The MR rule above keeps this from double-firing.
+    - if: $CI_COMMIT_BRANCH == "main"
+      when: always
+    # Anything else (branch pushes without an MR, malformed tags) runs nothing.
+    - when: never
+
+stages:
+  - quality
+  - test
+  - publish
+
+variables:
+  UV_CACHE_DIR: "$CI_PROJECT_DIR/.uv-cache"
+  PRE_COMMIT_HOME: "$CI_PROJECT_DIR/.pre-commit-cache"
+  # Keep resolution reproducible: fail rather than silently relock.
+  UV_FROZEN: "1"
+
+default:
+  image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+  cache:
+    key:
+      files:
+        - uv.lock
+    paths:
+      - .uv-cache
+      - .pre-commit-cache
+
+# --------------------------------------------------------------------------
+# quality
+# --------------------------------------------------------------------------
+
+quality:
+  stage: quality
+  before_script:
+    - apt-get update && apt-get install -y --no-install-recommends git
+    - uv sync --all-extras --all-groups
+  script:
+    - uv run pre-commit run --all-files --show-diff-on-failure
+
+# --------------------------------------------------------------------------
+# test
+# --------------------------------------------------------------------------
+
+test:
+  stage: test
+  image: ghcr.io/astral-sh/uv:python$PYTHON_VERSION-bookworm-slim
+  parallel:
+    matrix:
+      # Every version the package claims to support in requires-python.
+      - PYTHON_VERSION: ["3.12", "3.13"]
+  before_script:
+    - uv sync --all-extras --all-groups --python "$PYTHON_VERSION"
+  script:
+    - uv run --python "$PYTHON_VERSION" pytest --cov=src --cov-report=term --cov-report=xml
+  coverage: '/^TOTAL.*\s+(\d+%)$/'
+  artifacts:
+    when: always
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
+
+# --------------------------------------------------------------------------
+# publish  (release tags only)
+# --------------------------------------------------------------------------
+
+# The tag drives the release, so it must agree with the packaged version:
+# publishing v1.2.3 from a tree that says 1.2.2 cannot be undone on PyPI.
+check_version:
+  stage: publish
+  script:
+    - VERSION="$(uv version --short)"
+    - |
+      if [ "v$VERSION" != "$CI_COMMIT_TAG" ]; then
+        echo "Tag $CI_COMMIT_TAG does not match project version v$VERSION."
+        echo "Run 'uv version <new>' and retag."
+        exit 1
+      fi
+    - echo "Tag matches version v$VERSION."
+  rules:
+    - if: $CI_COMMIT_TAG
+
+build:
+  stage: publish
+  needs: ["check_version"]
+  # No cache here on purpose: the shared cache restores .uv-cache/ and
+  # .pre-commit-cache/ into the project directory, and the sdist would pick
+  # them up — cached virtualenvs carry absolute symlinks that fail the build.
+  cache: []
+  script:
+    # --no-sources ignores tool.uv.sources, so the build matches what a user
+    # installing from PyPI will actually get.
+    - uv build --no-sources
+    - ls -l dist/
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 1 week
+  rules:
+    - if: $CI_COMMIT_TAG
+
+.publish:
+  stage: publish
+  needs: ["build"]
+  before_script:
+    - apt-get update && apt-get install -y --no-install-recommends curl jq
+  script:
+    # Exchange the GitLab OIDC token for a short-lived PyPI publish token.
+    # Never echoed: it would land in the job log in clear text.
+    - |
+      MINTED="$(curl -sS -X POST "$PYPI_MINT_URL" \
+        -H 'Content-Type: application/json' \
+        -d "{\"token\":\"${PYPI_ID_TOKEN}\"}" | jq -r '.token // empty')"
+      if [ -z "$MINTED" ]; then
+        echo "Could not mint a publish token. Is this project registered as a"
+        echo "trusted publisher on $PYPI_HOST, with the right branch/tag rules?"
+        exit 1
+      fi
+      export UV_PUBLISH_TOKEN="$MINTED"
+    - uv publish --publish-url "$PYPI_PUBLISH_URL" dist/*
+
+publish_testpypi:
+  extends: .publish
+  id_tokens:
+    PYPI_ID_TOKEN:
+      aud: testpypi
+  variables:
+    PYPI_HOST: test.pypi.org
+    PYPI_MINT_URL: https://test.pypi.org/_/oidc/mint-token
+    PYPI_PUBLISH_URL: https://test.pypi.org/legacy/
+  environment:
+    name: testpypi
+    url: https://test.pypi.org/project/dot-agora/
+  rules:
+    - if: $CI_COMMIT_TAG
+
+publish_pypi:
+  extends: .publish
+  # `extends` REPLACES `needs`, it does not merge it: redeclaring the
+  # dependency on publish_testpypi drops the one on build inherited from
+  # `.publish`, and the job starts with an empty dist/ ("No files found to
+  # publish"). Both edges have to be spelled out here.
+  needs:
+    - job: build
+      artifacts: true
+    - job: publish_testpypi
+      artifacts: false
+  id_tokens:
+    PYPI_ID_TOKEN:
+      aud: pypi
+  variables:
+    PYPI_HOST: pypi.org
+    PYPI_MINT_URL: https://pypi.org/_/oidc/mint-token
+    PYPI_PUBLISH_URL: https://upload.pypi.org/legacy/
+  environment:
+    name: pypi
+    url: https://pypi.org/project/dot-agora/
+  rules:
+    # Final releases only: a candidate (vX.Y.ZrcN) stops at TestPyPI.
+    # Manual on purpose: a PyPI release cannot be taken back, only yanked.
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+      when: manual

dot_agora-2.0.0/.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+# Verbatim legal texts: the AGPL and the DCO both forbid modification,
+# so no hook may normalise their whitespace or line endings.
+exclude: '^(LICENSE\.md|DCO)$'
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: check-added-large-files
+        args: ["--maxkb=1000"]
+      - id: detect-private-key
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.0
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty (type check)
+        entry: uv run --frozen ty check
+        language: system
+        types: [python]
+        pass_filenames: false

dot_agora-2.0.0/.python-version

@@ -0,0 +1 @@
+3.12

dot_agora-2.0.0/AUTHORS.md

@@ -0,0 +1,14 @@
+# Authors
+
+Copyright in this project is held by **Kannon For Deep Tech**.
+This file credits the individuals who have contributed to it. Being listed
+here does not confer any ownership of, or rights in, the project.
+
+## Kannon For Deep Tech
+
+- Adrien Marjollet
+- Clément Olivier
+- Jean Fechter
+- Louis Le Tarnec
+
+## External contributors

dot_agora-2.0.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0] - 2026-09-15
+
+First public release. The 1.x line was internal, developed under the name
+`dot-agent` with a different architecture (`Agent`, tools and middleware);
+2.0.0 is a rewrite and offers no migration path from it.
+
+### Added
+
+- `Room`: a conversation whose every act is judged by a mediator and recorded in
+  an append-only `Journal`, with its ruling (admitted, held or refused).
+- The built-in language: `say`, `request` → `reply`, `join`, `leave`,
+  `interrupt`, and the mediator's `refusal` and `cancel`.
+- Composable protocols in `dot_agora.protocols`: `Approval` and `Vote`, with
+  their `PlaysApproval` and `PlaysVote` gestures and hooks.
+- Policies in `dot_agora.policies`: `permission`, `approval`, `answer_first` and
+  `ballot`. Any `(state, face) -> verdicts` function is a policy.
+- Views in `dot_agora.views`: `public`, `addressed`, `full`, `by_role`, and
+  `rewire` to keep causal links inside a custom view.
+- `Participant`: hooks per act (`on_request`, `on_reply`…), checked at class
+  definition, and `serving` to find the request a reaction serves.
+- `Assistant`: an LLM participant that discovers tools from the journal, asks
+  the user through a virtual `ask` tool, and checks structured answers against a
+  schema.
+- `LLMClient`, built by `dot-inference` from `DOTI_*` settings or wrapping a
+  given client, with streaming to subscribers. `SearchClient` for Linkup web
+  search.
+- Runtimes: `Stepper` (deterministic, synchronous) and `Session` (async).
+- `fork` and `resume` a room from a journal; `dot_agora.hosts.wire` dumps and
+  loads journals as JSON.
+- Hosts: `hosts.local`, the interactive `hosts.cli` and `hosts.terminal`
+  (`[cli]` extra), and the REST/SSE `hosts.http` (`[http]` extra).
+
+[Unreleased]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-agora/-/compare/v2.0.0...main
+[2.0.0]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-agora/-/tags/v2.0.0

dot_agora-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing
+
+Thanks for your interest in this project. Contributions are welcome.
+
+This project is maintained by **Kannon For Deep Tech** and released under the
+GNU Affero General Public License v3.0 or later (`AGPL-3.0-or-later`).
+
+## 1. Sign off your commits (DCO)
+
+Every commit must carry a `Signed-off-by` line. Add it automatically with:
+
+```
+git commit -s
+```
+
+This appends:
+
+```
+Signed-off-by: Jane Doe <jane@example.com>
+```
+
+The name and email must be your real ones and must match your commit author
+details. By signing off, you certify the [Developer Certificate of Origin](DCO)
+(v1.1) **and** you agree to the licensing terms in section 2 below.
+
+Pull requests with unsigned commits will not be merged.
+
+## 2. Licensing of your contribution
+
+By contributing to this project, you agree to the following.
+
+**2.1 — Outbound licence.** Your contribution is licensed to the public under
+`AGPL-3.0-or-later`, the same terms as the rest of the project.
+
+**2.2 — Additional grant to the maintainer.** You additionally grant Kannon For
+Deep Tech a perpetual, worldwide, irrevocable, non-exclusive, royalty-free,
+transferable and sublicensable right to reproduce, modify, adapt, translate,
+publish, distribute and otherwise exploit your contribution, in whole or in
+part, in any form and by any means, on any medium, **under any licensing terms,
+including proprietary and commercial terms**, for the entire duration of the
+applicable copyright protection and worldwide.
+
+**2.3 — What this means in practice.** This project is dual-licensed: it is
+available to everyone under the AGPL, and Kannon For Deep Tech also sells
+commercial licences to organisations that cannot comply with the AGPL. Section
+2.2 is what makes that possible. Without it, no contribution could be included
+in a commercially licensed version.
+
+**2.4 — You keep your copyright.** This is a licence grant, not a transfer of
+ownership. You remain the author and copyright holder of your contribution and
+stay free to use and relicense it however you wish, elsewhere.
+
+**2.5 — Your warranties.** You confirm that you are entitled to grant the above
+rights, that your contribution is your original work or that you hold the
+necessary rights over it, and that it does not infringe any third-party rights.
+If you are contributing in the course of your employment or under a service
+agreement, you confirm that your employer or client has authorised you to
+contribute under these terms, or has waived any rights that would conflict with
+them.
+
+## 3. Contractors and employees of Kannon For Deep Tech
+
+If you are working for Kannon For Deep Tech as an employee or under a service
+agreement, the assignment of rights set out in your contract governs, and takes
+precedence over this file. The sign-off above does not replace it.
+
+## 4. Submitting a change
+
+1. Open an issue first for anything substantial, so we can agree on the approach.
+2. Fork, branch, and keep commits focused.
+3. Add or update tests where relevant.
+4. Add the SPDX headers to any new file:
+
+   ```
+   # SPDX-FileCopyrightText: Kannon For Deep Tech and contributors
+   # SPDX-License-Identifier: AGPL-3.0-or-later
+   ```
+
+   Do not modify the copyright lines of existing files. If you would like to be
+   credited individually, add yourself to [AUTHORS.md](AUTHORS.md) in the same pull request.
+
+5. Sign off every commit (`git commit -s`) and open a pull request.
+
+## 5. Questions
+
+For anything about licensing, including commercial licences, contact
+<louis.letarnec@deepika.ai>.

dot_agora-2.0.0/DCO

@@ -0,0 +1,34 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.