itop-ai-assistant 0.5.0__tar.gz

itop_ai_assistant-0.5.0/.dockerignore

@@ -0,0 +1,185 @@
+test
+.pre-commit-config.yaml
+README.md
+pytest.toml
+ruff.toml
+*.iml
+
+### VirtualEnv template
+# Virtualenv
+# http://iamzed.com/2009/05/07/a-primer-on-virtualenv/
+.Python
+[Bb]in
+[Ii]nclude
+[Ll]ib
+[Ll]ib64
+[Ll]ocal
+[Ss]cripts
+pyvenv.cfg
+.venv
+pip-selfcheck.json
+
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$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
+.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
+
+# 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
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs 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/
+

itop_ai_assistant-0.5.0/.env.test.dist

@@ -0,0 +1,17 @@
+# Integration test environment — copy to .env.test and fill in real values.
+# .env.test is gitignored.
+#
+# These settings override config.yaml for integration test runs.
+# LLM must be reachable when running: uv run pytest test/integration/
+
+# openai_compatible (default) | openai | google_genai | ollama
+LLM_PROVIDER=openai_compatible
+LLM_BASE_URL=http://localhost:1234/v1
+LLM_MODEL=your-model-name
+LLM_API_KEY=none
+# Set true if the endpoint accepts a forced tool_choice (vLLM yes, DeepSeek no)
+# LLM_SUPPORTS_FORCED_TOOL_CHOICE=true
+
+# Dummy iTop credentials — real iTop is NOT used (mocked via httpx transport)
+ITOP_USER=dummy
+ITOP_PWD=dummy

itop_ai_assistant-0.5.0/.gitignore

@@ -0,0 +1,256 @@
+.env
+.env.*
+!.env.example
+!.env.test.dist
+src/routes/VERSION
+
+### VisualStudioCode template
+.vscode
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+### Linux template
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### Windows template
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+### macOS template
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$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
+.hypothesis/
+.pytest_cache/
+cover/
+report.xml
+
+# 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
+
+# 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
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs 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/
+*.iml
+# Generated at build time by hatch_build.py
+src/itop_ai_assistant/_build_info.py
+
+# Built by `npm run build` in ui/ — see ui/vite.config.ts
+src/itop_ai_assistant/ui_dist/
+
+.import_linter_cache/

itop_ai_assistant-0.5.0/.importlinter

@@ -0,0 +1,145 @@
+; Module-boundary invariants expressible as a plain import graph — see
+; test/unit/test_package_layers.py for the invariants an import graph has no
+; vocabulary for (declared names, class shapes, signatures, file layout),
+; which stay hand-written there.
+; grimp only walks into subpackages that have an `__init__.py`; most of ours
+; are plain PEP 420 namespace packages, so each is listed as its own root too
+; or its modules would be invisible to every contract below.
+[importlinter]
+root_packages =
+    itop_ai_assistant
+    itop_ai_assistant.core
+    itop_ai_assistant.itop
+    itop_ai_assistant.repositories
+    itop_ai_assistant.request
+    itop_ai_assistant.schedule
+    itop_ai_assistant.settings
+    itop_ai_assistant.util
+    itop_ai_assistant.webhook
+    itop_ai_assistant.vector.adapters
+    itop_ai_assistant.vector.ports
+    itop_ai_assistant.vector.state
+    itop_ai_assistant.vector.use_cases
+
+; `.claude/rules/itop.md`: nothing outside the repositories touches iTop.
+; `core/principal.py` is not an exception to the rule but to its wording: it
+; names `ItopAuth` as the type of a principal's credentials, and never calls
+; iTop.
+[importlinter:contract:itop-boundary]
+name = Only itop/, repositories/ and core/principal.py import the vendored client
+type = forbidden
+; Direct imports only, matching the AST check this replaced — a module
+; reaching itop_client through another module's re-export is that module's
+; boundary to answer for, not this one's.
+allow_indirect_imports = true
+source_modules =
+    itop_ai_assistant.admin
+    itop_ai_assistant.agents
+    itop_ai_assistant.config
+    itop_ai_assistant.content_sources
+    itop_ai_assistant.core
+    itop_ai_assistant.domain
+    itop_ai_assistant.main
+    itop_ai_assistant.pipelines
+    itop_ai_assistant.request
+    itop_ai_assistant.schedule
+    itop_ai_assistant.settings
+    itop_ai_assistant.state
+    itop_ai_assistant.telemetry
+    itop_ai_assistant.util
+    itop_ai_assistant.vector
+    itop_ai_assistant.webhook
+forbidden_modules =
+    itop_ai_assistant.itop_client
+ignore_imports =
+    itop_ai_assistant.core.principal -> itop_ai_assistant.itop_client
+
+; `ports/` and `state/` are the bottom of vector/'s own dependency graph.
+; `adapters/`, `use_cases/` and `router.py` are ordered as they already are
+; in practice (use_cases depends on adapters, router depends on use_cases).
+[importlinter:contract:vector-layers]
+name = vector/: ports and state sit below adapters, use_cases and router
+type = layers
+layers =
+    router
+    use_cases
+    adapters
+    ports | state
+containers =
+    itop_ai_assistant.vector
+; reindex.py is the `itop-ai-reindex` CLI script (pyproject.toml
+; [project.scripts]) — it bootstraps the whole app through the composition
+; root and the pipeline registry, both of which loop back through the vector
+; facade into router. That is the composition root's business, not a
+; use_cases-reaches-upward violation.
+ignore_imports =
+    itop_ai_assistant.vector.use_cases.reindex -> itop_ai_assistant.core.deps
+    itop_ai_assistant.vector.use_cases.reindex -> itop_ai_assistant.pipelines.registry
+
+; Rule 3.4, TASK-040: a port must not import a settings section.
+[importlinter:contract:source-port-sheds-config]
+name = vector/ports/source.py does not import the settings section
+type = forbidden
+allow_indirect_imports = true
+source_modules =
+    itop_ai_assistant.vector.ports.source
+forbidden_modules =
+    itop_ai_assistant.vector.config
+
+; architecture/alignment-plan.md §5: content providers live outside vector/
+; entirely, so nothing under vector/ may import the ticket/FAQ domain models
+; or their repositories. router.py's import of repositories.sets is not
+; domain knowledge (ADR-022) and is deliberately not listed here.
+[importlinter:contract:vector-does-not-know-content-domains]
+name = vector/ does not know the ticket/FAQ content domains
+type = forbidden
+allow_indirect_imports = true
+source_modules =
+    itop_ai_assistant.vector
+forbidden_modules =
+    itop_ai_assistant.domain.ticket
+    itop_ai_assistant.domain.faq
+    itop_ai_assistant.repositories.ticket
+    itop_ai_assistant.repositories.faq
+
+; Rule 6.10, TASK-044: agents/ is business logic, webhook/ is one entry
+; point's transport shape.
+[importlinter:contract:agents-do-not-import-webhook]
+name = agents/ does not import the webhook transport
+type = forbidden
+allow_indirect_imports = true
+source_modules =
+    itop_ai_assistant.agents
+forbidden_modules =
+    itop_ai_assistant.webhook
+
+; Rule 1.3/5.1, TASK-045: a module reaches the LLM factory through
+; `RunDeps.create_llm`, not by importing the composition root that assembles
+; `AppDeps` and holds the Redis/Qdrant wiring.
+[importlinter:contract:agents-do-not-import-core-deps]
+name = agents/ does not import the composition root
+type = forbidden
+allow_indirect_imports = true
+source_modules =
+    itop_ai_assistant.agents
+forbidden_modules =
+    itop_ai_assistant.core.deps
+
+; The mirror image of vector-does-not-know-content-domains above — that one
+; keeps the domain out of vector/ entirely, this one keeps search.py,
+; indexer.py and router.py from building the source *list* themselves via the
+; door content_sources.registry leaves open: vector/assembly.py is the one
+; caller of build_vector_sources() in the process (TASK-037). Whole-module,
+; not just the one name — stronger than the invariant this replaces, since
+; none of the three currently has any other reason to import that module
+; either.
+[importlinter:contract:vector-sources-are-injected-not-built]
+name = search.py, indexer.py and router.py do not build the source list themselves
+type = forbidden
+allow_indirect_imports = true
+source_modules =
+    itop_ai_assistant.vector.use_cases.search
+    itop_ai_assistant.vector.use_cases.indexer
+    itop_ai_assistant.vector.router
+forbidden_modules =
+    itop_ai_assistant.content_sources.registry

itop_ai_assistant-0.5.0/.python-version

@@ -0,0 +1 @@
+3.13

itop_ai_assistant-0.5.0/CLAUDE.md

@@ -0,0 +1,25 @@
+# Development Commands
+
+All commands run from `assistant/` unless noted.
+
+```bash
+uv sync                                # deps (--no-dev for production)
+uv run uvicorn itop_ai_assistant.main:app --host 0.0.0.0 --port 8001 --reload
+uv run pytest                          # unit tests (the default suite)
+uv run pytest -k "test_name"           # one test
+uv run ruff check . && uv run ruff format .
+cd ../docker && docker-compose up -d   # full stack: iTop + assistant + Redis + Qdrant
+```
+
+**Before pushing**, run what CI runs: `uv run pre-commit run --all-files` and
+`uv run pytest`. Note that `pre-commit run mypy --all-files` is the **strict**
+type gate — `uv run mypy src/` is not the same check and passing it proves
+less. CI (`.github/workflows/ci.yml`) runs on every push to `main` and every PR
+and gates the image publish; it adds `npm run build` for the UI.
+`test/integration` needs a real model endpoint and is excluded there.
+
+**Live verification on the stand** (`docker-compose up`, manual checks against
+the running stack) happens only after the user confirms — don't start the
+stack or poke it unprompted, even to "just double-check" a change. Unit tests
+and `pre-commit` are enough to report work as done; note in the summary that
+live verification is still pending.

itop_ai_assistant-0.5.0/Dockerfile

@@ -0,0 +1,66 @@
+# Build context is the repository root (ui/ and assistant/ are siblings):
+#   docker build -f assistant/Dockerfile .
+
+FROM node:22-alpine AS ui-builder
+
+WORKDIR /ui
+
+# Install dependencies first — this layer is cached unless the lockfile changes
+COPY ui/package.json ui/package-lock.json ./
+RUN npm ci
+
+COPY ui/ ./
+RUN npm run build
+
+# ---- python dependencies + the project itself ----
+FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim AS builder
+
+WORKDIR /app
+
+# Install dependencies into a separate venv — this layer is cached unless lockfile changes.
+# `--extra tracing` even though tracing is off by default (TRACING_ENABLED): an
+# image without the packages could not be told to trace at all, and a
+# deployment cannot pip-install into a published image. Cheap here — the extra
+# is the OTel SDK, the HTTP exporter and the OpenInference conventions, no gRPC.
+COPY assistant/pyproject.toml assistant/uv.lock ./
+RUN uv sync --frozen --no-dev --extra tracing --no-install-project --no-editable
+
+# The build stamp, baked into the package by hatch_build.py and readable at
+# run time through importlib.metadata and _build_info.py. No git here: the
+# tag is something CI already knows, so it is handed over rather than
+# rediscovered from history. Unset (a local build) yields the 0.0.0 fallback.
+# BUILD_CHANNEL is what telemetry gates on: `release` only from the publish
+# workflow, so an image built here by hand reports nothing.
+ARG APP_VERSION=""
+ARG BUILD_COMMIT=""
+ARG BUILD_CHANNEL=""
+ENV SETUPTOOLS_SCM_PRETEND_VERSION=${APP_VERSION} BUILD_COMMIT=${BUILD_COMMIT} BUILD_CHANNEL=${BUILD_CHANNEL}
+
+# Install the application itself. --no-editable puts the package inside the
+# venv, so the runtime image needs nothing but /app/.venv.
+COPY assistant/ ./
+# The SPA is part of the package (ADR-032) — `npm run build` writes it here in
+# a checkout, and here is where the wheel picks it up. Copied after the source
+# so a frontend change does not invalidate the layers above, and so the build
+# fails (hatch_build.py) if the stage above produced nothing.
+COPY --from=ui-builder /assistant/src/itop_ai_assistant/ui_dist ./src/itop_ai_assistant/ui_dist
+RUN uv sync --frozen --no-dev --extra tracing --no-editable
+
+# ---- runtime image ----
+FROM python:3.13-slim-bookworm
+
+LABEL org.opencontainers.image.title="iTop AI Assistant"
+LABEL org.opencontainers.image.licenses="AGPL-3.0"
+
+WORKDIR /app
+
+# The venv already contains the application, its build stamp, default prompts,
+# config.yaml and the admin SPA — no source, and no .git, reaches the runtime
+# image
+COPY --from=builder /app/.venv ./.venv
+
+ENV PATH="/app/.venv/bin:$PATH"
+
+EXPOSE 8000
+
+CMD ["uvicorn", "itop_ai_assistant.main:app", "--host", "0.0.0.0", "--port", "8000"]