tixio 0.1.0__tar.gz

tixio-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: tixio
+Version: 0.1.0
+Summary: Confidence-gated, model-assisted issue triage for engineering teams
+Project-URL: Homepage, https://github.com/Bojan-Ivanovski/tixio
+Project-URL: Repository, https://github.com/Bojan-Ivanovski/tixio
+Project-URL: Issues, https://github.com/Bojan-Ivanovski/tixio/issues
+Keywords: github,issue-triage,classification,automation,decider
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Bug Tracking
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: decider-ai==1.5.0
+Requires-Dist: typer
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+
+<div align="center">
+
+# Tixio
+
+**Confidence-gated, model-assisted issue triage for engineering teams.**
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![PyPI](https://img.shields.io/pypi/v/tixio?logo=pypi&logoColor=white)](https://pypi.org/project/tixio/)
+[![Mapika Decider](https://img.shields.io/badge/powered%20by-Mapika%20Decider-6f42c1)](https://huggingface.co/Mapika)
+[![GitHub](https://img.shields.io/badge/platform-GitHub-181717?logo=github)](https://github.com/Bojan-Ivanovski/tixio)
+
+</div>
+
+Tixio turns incoming issues into structured, reviewable triage decisions. It
+reads the issue and recent discussion, classifies it with Mapika Decider, and
+proposes consistent labels and ownership without silently changing your
+repository.
+
+Dry-run is the default. Changes are only eligible for automatic application
+when their probability crosses the configured confidence threshold, and
+security-sensitive issues suppress normal automated routing.
+
+## Why Tixio?
+
+- **Safe by default** — preview every decision before applying it.
+- **Confidence gated** — uncertain classifications stay queued for human review.
+- **Shared taxonomy** — keep types, components, priorities, statuses, and sizes
+  consistent across repositories.
+- **Multi-component aware** — one issue can belong to several engineering areas.
+- **Provider-oriented design** — the triage engine depends on a common client
+  interface, with GitHub as the first implementation.
+- **Local model workflow** — classification is powered by Mapika Decider rather
+  than a hosted text-generation API.
+
+## What it classifies
+
+| Descriptor | Behavior |
+| --- | --- |
+| Type | Selects the primary nature of the issue. |
+| Component | Selects one or more affected project areas. |
+| Priority | Estimates impact and urgency. |
+| Status | Proposes the appropriate delivery state. |
+| Size | Estimates relative scope and decomposition level. |
+| Signals | Detects security, privacy, compliance, missing information, and reproduction needs. |
+| Assignee | Proposes an initial owner when confidence is sufficient. |
+
+## Installation
+
+Tixio requires Python 3.11 or newer. Install the published package with:
+
+```bash
+pip install tixio
+```
+
+Or install the latest source version:
+
+```bash
+git clone https://github.com/Bojan-Ivanovski/tixio.git
+cd tixio
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Set the target repository and a GitHub token with issue and label permissions:
+
+```bash
+export GITHUB_TOKEN=github_pat_...
+export GITHUB_REPOSITORY=owner/repository
+```
+
+The first triage run may download and initialize the configured Decider model.
+
+## Quick start
+
+```bash
+tixio triage 123                     # preview decisions
+tixio triage 123 --apply             # apply high-confidence changes
+tixio triage 123 --json              # machine-readable output
+tixio triage 123 --model Mapika/decider-4b
+```
+
+## Shared descriptors
+
+The canonical taxonomy lives in `tixio/data/descriptors.py`. Types and
+components can be synchronized with GitHub labels; priority, status, and size
+remain static shared definitions.
+
+```bash
+tixio descriptors view
+tixio descriptors view --diff
+tixio descriptors apply
+tixio descriptors apply --force
+```
+
+`descriptors apply` adds missing labels and updates mismatched descriptions or
+colors. `--force` deletes and recreates mutable type and component labels, so
+review the diff before using it on an established repository.
+
+## Safety model
+
+Tixio separates a model recommendation from permission to mutate a repository:
+
+1. The issue, bounded body text, and recent comments become model context.
+2. Decider evaluates closed descriptor choices and independent risk signals.
+3. Tixio parses probabilities and applies confidence thresholds.
+4. The CLI prints the proposed label and assignment changes.
+5. GitHub is only modified when `--apply` is explicitly provided.
+
+High-confidence security-sensitive results suppress normal label and assignee
+updates so maintainers can route them through a private security process.
+
+## Architecture
+
+```text
+tixio/
+├── cli/                 Typer commands and presentation
+├── clients/             Provider-neutral interfaces
+│   └── github/          GitHub transport, tickets, and descriptors
+├── data/                Canonical descriptor registry
+└── decider/             Context, model adapter, policy, and result models
+```
+
+The core `TriageService` accepts the shared `Client` abstraction. Additional
+issue trackers can implement the same ticket, descriptor, and transport
+interfaces without changing the classifier.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+tox -e lint
+```
+
+The lint environment runs Pyright, isort, and Black checks.
+
+## Project status
+
+Tixio is early-stage software. Run it in dry-run mode first, verify your label
+taxonomy, and review model recommendations before enabling repository writes.
+
+Contributions, issue reports, and provider integrations are welcome.

tixio-0.1.0/README.md

@@ -0,0 +1,142 @@
+<div align="center">
+
+# Tixio
+
+**Confidence-gated, model-assisted issue triage for engineering teams.**
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![PyPI](https://img.shields.io/pypi/v/tixio?logo=pypi&logoColor=white)](https://pypi.org/project/tixio/)
+[![Mapika Decider](https://img.shields.io/badge/powered%20by-Mapika%20Decider-6f42c1)](https://huggingface.co/Mapika)
+[![GitHub](https://img.shields.io/badge/platform-GitHub-181717?logo=github)](https://github.com/Bojan-Ivanovski/tixio)
+
+</div>
+
+Tixio turns incoming issues into structured, reviewable triage decisions. It
+reads the issue and recent discussion, classifies it with Mapika Decider, and
+proposes consistent labels and ownership without silently changing your
+repository.
+
+Dry-run is the default. Changes are only eligible for automatic application
+when their probability crosses the configured confidence threshold, and
+security-sensitive issues suppress normal automated routing.
+
+## Why Tixio?
+
+- **Safe by default** — preview every decision before applying it.
+- **Confidence gated** — uncertain classifications stay queued for human review.
+- **Shared taxonomy** — keep types, components, priorities, statuses, and sizes
+  consistent across repositories.
+- **Multi-component aware** — one issue can belong to several engineering areas.
+- **Provider-oriented design** — the triage engine depends on a common client
+  interface, with GitHub as the first implementation.
+- **Local model workflow** — classification is powered by Mapika Decider rather
+  than a hosted text-generation API.
+
+## What it classifies
+
+| Descriptor | Behavior |
+| --- | --- |
+| Type | Selects the primary nature of the issue. |
+| Component | Selects one or more affected project areas. |
+| Priority | Estimates impact and urgency. |
+| Status | Proposes the appropriate delivery state. |
+| Size | Estimates relative scope and decomposition level. |
+| Signals | Detects security, privacy, compliance, missing information, and reproduction needs. |
+| Assignee | Proposes an initial owner when confidence is sufficient. |
+
+## Installation
+
+Tixio requires Python 3.11 or newer. Install the published package with:
+
+```bash
+pip install tixio
+```
+
+Or install the latest source version:
+
+```bash
+git clone https://github.com/Bojan-Ivanovski/tixio.git
+cd tixio
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Set the target repository and a GitHub token with issue and label permissions:
+
+```bash
+export GITHUB_TOKEN=github_pat_...
+export GITHUB_REPOSITORY=owner/repository
+```
+
+The first triage run may download and initialize the configured Decider model.
+
+## Quick start
+
+```bash
+tixio triage 123                     # preview decisions
+tixio triage 123 --apply             # apply high-confidence changes
+tixio triage 123 --json              # machine-readable output
+tixio triage 123 --model Mapika/decider-4b
+```
+
+## Shared descriptors
+
+The canonical taxonomy lives in `tixio/data/descriptors.py`. Types and
+components can be synchronized with GitHub labels; priority, status, and size
+remain static shared definitions.
+
+```bash
+tixio descriptors view
+tixio descriptors view --diff
+tixio descriptors apply
+tixio descriptors apply --force
+```
+
+`descriptors apply` adds missing labels and updates mismatched descriptions or
+colors. `--force` deletes and recreates mutable type and component labels, so
+review the diff before using it on an established repository.
+
+## Safety model
+
+Tixio separates a model recommendation from permission to mutate a repository:
+
+1. The issue, bounded body text, and recent comments become model context.
+2. Decider evaluates closed descriptor choices and independent risk signals.
+3. Tixio parses probabilities and applies confidence thresholds.
+4. The CLI prints the proposed label and assignment changes.
+5. GitHub is only modified when `--apply` is explicitly provided.
+
+High-confidence security-sensitive results suppress normal label and assignee
+updates so maintainers can route them through a private security process.
+
+## Architecture
+
+```text
+tixio/
+├── cli/                 Typer commands and presentation
+├── clients/             Provider-neutral interfaces
+│   └── github/          GitHub transport, tickets, and descriptors
+├── data/                Canonical descriptor registry
+└── decider/             Context, model adapter, policy, and result models
+```
+
+The core `TriageService` accepts the shared `Client` abstraction. Additional
+issue trackers can implement the same ticket, descriptor, and transport
+interfaces without changing the classifier.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+tox -e lint
+```
+
+The lint environment runs Pyright, isort, and Black checks.
+
+## Project status
+
+Tixio is early-stage software. Run it in dry-run mode first, verify your label
+taxonomy, and review model recommendations before enabling repository writes.
+
+Contributions, issue reports, and provider integrations are welcome.

tixio-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tixio"
+version = "0.1.0"
+description = "Confidence-gated, model-assisted issue triage for engineering teams"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["decider-ai==1.5.0", "typer", "requests"]
+keywords = ["github", "issue-triage", "classification", "automation", "decider"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Bug Tracking",
+]
+
+[project.urls]
+Homepage = "https://github.com/Bojan-Ivanovski/tixio"
+Repository = "https://github.com/Bojan-Ivanovski/tixio"
+Issues = "https://github.com/Bojan-Ivanovski/tixio/issues"
+
+[project.scripts]
+tixio = "tixio.cli:main"
+
+[project.optional-dependencies]
+dev = ["tox", "black", "isort", "pyright"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tixio*"]
+
+[tool.setuptools.package-data]
+tbt_engine = ["py.typed"]
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[tool.pyright]
+include = ["tixio"]
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false

tixio-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tixio-0.1.0/tixio/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Tixio command-line interface."""
+
+from .app import app, main
+
+__all__ = ["app", "main"]

tixio-0.1.0/tixio/cli/app.py

@@ -0,0 +1,14 @@
+"""Root Typer application."""
+
+import typer
+
+from .descriptors import app as descriptors_app
+from .triage import triage
+
+app = typer.Typer(name="tixio", help="Ticket and issue classification tools")
+app.add_typer(descriptors_app, name="descriptors")
+app.command("triage")(triage)
+
+
+def main() -> None:
+    app()

tixio-0.1.0/tixio/cli/common.py

@@ -0,0 +1,18 @@
+"""Shared CLI dependencies."""
+
+import os
+
+import typer
+
+from ..clients.client import Client
+from ..clients.github import GithubClient
+
+
+def build_client(token: str | None, repo: str | None) -> Client:
+    resolved_token = token or os.getenv("GITHUB_TOKEN")
+    resolved_repo = repo or os.getenv("GITHUB_REPOSITORY")
+    if not resolved_token or not resolved_repo:
+        raise typer.BadParameter(
+            "Provide --token and --repo, or set GITHUB_TOKEN and GITHUB_REPOSITORY."
+        )
+    return GithubClient(resolved_token, resolved_repo)

tixio-0.1.0/tixio/cli/descriptors.py

@@ -0,0 +1,95 @@
+"""Descriptor CLI commands."""
+
+from copy import deepcopy
+from typing import Any
+
+import typer
+
+from ..clients.client import Client
+from ..data.descriptors import TICKET_DESCRIPTORS
+from .common import build_client
+
+app = typer.Typer(name="descriptors", help="Manage shared descriptors")
+
+
+def static_descriptors() -> dict[str, Any]:
+    return {
+        "types": deepcopy(TICKET_DESCRIPTORS["type"]),
+        "components": deepcopy(TICKET_DESCRIPTORS["component"]),
+        "priority": deepcopy(TICKET_DESCRIPTORS["priority"]),
+        "status": deepcopy(TICKET_DESCRIPTORS["status"]),
+        "size": deepcopy(TICKET_DESCRIPTORS["size"]),
+    }
+
+
+def client_descriptors(client: Client) -> dict[str, Any]:
+    return {
+        "types": client.descriptors.get_types(),
+        "components": client.descriptors.get_components(),
+        "priority": client.descriptors.get_priority(),
+        "status": client.descriptors.get_status(),
+        "size": client.descriptors.get_size(),
+    }
+
+
+@app.command("view")
+def view(
+    diff: bool = typer.Option(False, "--diff"),
+    token: str | None = typer.Option(None, "--token"),
+    repo: str | None = typer.Option(None, "--repo"),
+) -> None:
+    remote = client_descriptors(build_client(token, repo))
+    for group, descriptor in remote.items():
+        typer.echo(f"\n{group}")
+        for name, value in descriptor.get("labels", {}).items():
+            if isinstance(value, dict):
+                typer.echo(
+                    f"  {name}: {value.get('description', '')} ({value.get('color', '')})"
+                )
+            else:
+                typer.echo(f"  {name}: {value}")
+
+    if diff:
+        expected = static_descriptors()
+        typer.echo("\nDiff")
+        for group in expected:
+            expected_names = set(expected[group].get("labels", {}))
+            remote_names = set(remote[group].get("labels", {}))
+            for name in sorted(expected_names - remote_names):
+                typer.echo(f"  missing {name}")
+            for name in sorted(remote_names - expected_names):
+                typer.echo(f"  extra {name}")
+
+
+@app.command("apply")
+def apply(
+    force: bool = typer.Option(False, "--force"),
+    token: str | None = typer.Option(None, "--token"),
+    repo: str | None = typer.Option(None, "--repo"),
+) -> None:
+    client = build_client(token, repo)
+    remote = client_descriptors(client)
+    expected = static_descriptors()
+
+    for group in ("types", "components"):
+        delete = client.descriptors.delete_types if group == "types" else client.descriptors.delete_components
+        create = client.descriptors.create_types if group == "types" else client.descriptors.create_components
+        update = client.descriptors.update_types if group == "types" else client.descriptors.update_components
+        current: dict[str, Any] = remote[group].get("labels", {})
+        if force:
+            for name in current:
+                delete(name)
+            current = {}
+
+        color = str(expected[group].get("color", "#6f42c1"))
+        for name, description in expected[group].get("labels", {}).items():
+            existing = current.get(name)
+            if existing is None:
+                create(name, description, color=color)
+                typer.echo(f"added {name}")
+                continue
+            remote_description = existing.get("description", "")
+            remote_color = existing.get("color", "")
+            if remote_description != description or remote_color.lower() != color.lower():
+                update(name, description=description, color=color)
+                typer.echo(f"updated {name}")

tixio-0.1.0/tixio/cli/triage.py

@@ -0,0 +1,36 @@
+"""Ticket triage CLI command."""
+
+import json
+from dataclasses import asdict
+
+import typer
+
+from ..decider.service import DEFAULT_MODEL, TriageService
+from .common import build_client
+
+
+def triage(
+    issue_number: int,
+    apply: bool = typer.Option(False, "--apply", help="Apply high-confidence changes."),
+    model: str = typer.Option(DEFAULT_MODEL, "--model"),
+    json_output: bool = typer.Option(False, "--json"),
+    token: str | None = typer.Option(None, "--token"),
+    repo: str | None = typer.Option(None, "--repo"),
+) -> None:
+    result = TriageService(build_client(token, repo), model).triage(issue_number, apply=apply)
+    if json_output:
+        typer.echo(json.dumps(asdict(result), indent=2))
+        return
+
+    typer.echo(f"Issue: {result.ticket_title}")
+    for decision in result.decisions:
+        action = "AUTO" if decision.auto_apply else "REVIEW"
+        typer.echo(
+            f"{decision.field:20} {str(decision.value):24} "
+            f"p={decision.probability:.3f} {action}"
+        )
+    typer.echo(f"old labels: {result.previous_labels}")
+    typer.echo(f"new labels: {result.proposed_labels}")
+    for warning in result.warnings:
+        typer.echo(f"WARNING: {warning}", err=True)
+    typer.echo("Applied changes." if result.applied else "DRY RUN: nothing was changed.")

tixio-0.1.0/tixio/clients/__init__.py

@@ -0,0 +1 @@
+"""External service clients used by Tixio."""

tixio-0.1.0/tixio/clients/client.py

@@ -0,0 +1,25 @@
+"""Common client composition."""
+
+from abc import ABC
+from typing import Any
+
+from .tickets import Tickets
+from .transport import Transport
+from .descriptors import Descriptors
+
+class Client(ABC):
+    """Common client holding ticket operations and transport."""
+
+    def __init__(
+        self,
+        tickets: Tickets,
+        transport: Transport,
+        descriptors: Descriptors,
+    ):
+        self.tickets = tickets
+        self.transport = transport
+        self.descriptors = descriptors
+
+    def assignees(self) -> list[dict[str, Any]]:
+        """Return assignable users when the provider supports ownership."""
+        return []

tixio-0.1.0/tixio/clients/descriptors.py

@@ -0,0 +1,52 @@
+"""Common descriptor interface."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Descriptors(ABC):
+    """Interface for descriptor CRUD operations."""
+
+    @abstractmethod
+    def get_types(self) -> dict[str, Any]: raise NotImplementedError
+    @abstractmethod
+    def get_components(self) -> dict[str, Any]: raise NotImplementedError
+    @abstractmethod
+    def get_priority(self) -> dict[str, Any]: raise NotImplementedError
+    @abstractmethod
+    def get_status(self) -> dict[str, Any]: raise NotImplementedError
+    @abstractmethod
+    def get_size(self) -> dict[str, Any]: raise NotImplementedError
+
+    @abstractmethod
+    def create_types(self, name: str, description: str, *, color: str) -> dict[str, Any]: raise NotImplementedError
+    @abstractmethod
+    def create_components(self, name: str, description: str, *, color: str) -> dict[str, Any]: raise NotImplementedError
+    @abstractmethod
+    def create_priority(self, name: str, description: str, *, color: str) -> dict[str, Any]: raise NotImplementedError
+    @abstractmethod
+    def create_status(self, name: str, description: str, *, color: str) -> dict[str, Any]: raise NotImplementedError
+    @abstractmethod
+    def create_size(self, name: str, description: str, *, color: str) -> dict[str, Any]: raise NotImplementedError
+
+    @abstractmethod
+    def update_types(self, name: str, *, description: str | None = None, color: str | None = None) -> dict[str, Any]: raise NotImplementedError
+    @abstractmethod
+    def update_components(self, name: str, *, description: str | None = None, color: str | None = None) -> dict[str, Any]: raise NotImplementedError
+    @abstractmethod
+    def update_priority(self, name: str, *, description: str | None = None, color: str | None = None) -> dict[str, Any]: raise NotImplementedError
+    @abstractmethod
+    def update_status(self, name: str, *, description: str | None = None, color: str | None = None) -> dict[str, Any]: raise NotImplementedError
+    @abstractmethod
+    def update_size(self, name: str, *, description: str | None = None, color: str | None = None) -> dict[str, Any]: raise NotImplementedError
+
+    @abstractmethod
+    def delete_types(self, name: str) -> None: raise NotImplementedError
+    @abstractmethod
+    def delete_components(self, name: str) -> None: raise NotImplementedError
+    @abstractmethod
+    def delete_priority(self, name: str) -> None: raise NotImplementedError
+    @abstractmethod
+    def delete_status(self, name: str) -> None: raise NotImplementedError
+    @abstractmethod
+    def delete_size(self, name: str) -> None: raise NotImplementedError

tixio-0.1.0/tixio/clients/errors.py

@@ -0,0 +1,13 @@
+"""Common client errors."""
+
+
+class ClientError(RuntimeError):
+    """Base error for client failures."""
+
+
+class ClientConfigurationError(ClientError):
+    """Raised when client configuration is invalid."""
+
+
+class ClientRequestError(ClientError):
+    """Raised when a remote service rejects or cannot complete a request."""

tixio-0.1.0/tixio/clients/github/__init__.py

@@ -0,0 +1,37 @@
+"""Composable GitHub client for issue triage."""
+
+from typing import Any
+
+from ..client import Client
+from .descriptors import GithubDescriptors
+from .tickets import GithubIssues
+from .transport import GithubTransport
+
+class GithubClient(Client):
+    """Facade over focused GitHub API clients."""
+
+    def __init__(
+        self,
+        token: str,
+        repository: str,
+        *,
+        timeout: float = 30.0,
+        descriptors: GithubDescriptors | None = None,
+    ):
+        transport = GithubTransport(token, repository, timeout=timeout)
+        super().__init__(
+            GithubIssues(transport),
+            transport,
+            descriptors or GithubDescriptors(transport),
+        )
+
+    def assignees(self) -> list[dict[str, Any]]:
+        return self.transport.get("/assignees", params={"per_page": 100})
+
+__all__ = [
+    "GithubClient",
+    "Client",
+    "GithubIssues",
+    "GithubDescriptors",
+    "GithubTransport",
+]