tenhaw 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tenhaw-1.0.0/.gitignore +21 -0
- tenhaw-1.0.0/LICENSE +21 -0
- tenhaw-1.0.0/LICENSE-CONTENT +15 -0
- tenhaw-1.0.0/PKG-INFO +52 -0
- tenhaw-1.0.0/README.md +36 -0
- tenhaw-1.0.0/pyproject.toml +30 -0
- tenhaw-1.0.0/src/tenhaw/__init__.py +3 -0
- tenhaw-1.0.0/src/tenhaw/__main__.py +3 -0
- tenhaw-1.0.0/src/tenhaw/cli.py +194 -0
- tenhaw-1.0.0/src/tenhaw/py.typed +1 -0
tenhaw-1.0.0/.gitignore
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
node_modules/
|
|
2
|
+
dist/
|
|
3
|
+
.next/
|
|
4
|
+
out/
|
|
5
|
+
.turbo/
|
|
6
|
+
.venv/
|
|
7
|
+
__pycache__/
|
|
8
|
+
.pytest_cache/
|
|
9
|
+
.mypy_cache/
|
|
10
|
+
.ruff_cache/
|
|
11
|
+
coverage/
|
|
12
|
+
.env
|
|
13
|
+
.env.*
|
|
14
|
+
!.env.example
|
|
15
|
+
.vercel/
|
|
16
|
+
.tenhaw/
|
|
17
|
+
artifacts/
|
|
18
|
+
/packages/cli/templates/
|
|
19
|
+
/packages/cli/instructions/
|
|
20
|
+
*.egg-info/
|
|
21
|
+
.DS_Store
|
tenhaw-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Tenhaw
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
Tenhaw AI Readiness Framework and authored framework content in spec/content
|
|
2
|
+
are licensed under the Creative Commons Attribution 4.0 International licence.
|
|
3
|
+
Copyright (c) 2026 Tenhaw.
|
|
4
|
+
|
|
5
|
+
Licence: https://creativecommons.org/licenses/by/4.0/
|
|
6
|
+
Legal code: https://creativecommons.org/licenses/by/4.0/legalcode.en
|
|
7
|
+
|
|
8
|
+
When sharing or adapting this content, provide appropriate credit, a licence
|
|
9
|
+
link, and an indication of changes. A suitable credit is:
|
|
10
|
+
"Tenhaw AI Readiness Framework, CC BY 4.0, https://tenhaw.com."
|
|
11
|
+
|
|
12
|
+
Numerical results and user-supplied evidence remain the user's material.
|
|
13
|
+
The optional audit promotion can be suppressed independently of applicable
|
|
14
|
+
framework-content credits. Code is MIT; third-party sources retain their own
|
|
15
|
+
rights and are summarised with links rather than relicensed here.
|
tenhaw-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: tenhaw
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Agent-friendly CLI for AI readiness, AI ROI and delivery metrics.
|
|
5
|
+
Project-URL: Homepage, https://kit.tenhaw.com
|
|
6
|
+
Project-URL: Repository, https://github.com/Tenhaw/tenhaw-kit
|
|
7
|
+
Author-email: Tenhaw <hello@tenhaw.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: ai-readiness,ai-roi,delivery-metrics,internal-tools,tenhaw
|
|
11
|
+
Requires-Python: >=3.10
|
|
12
|
+
Requires-Dist: tenhaw-ai-readiness==1.0.0
|
|
13
|
+
Requires-Dist: tenhaw-ai-roi==1.0.0
|
|
14
|
+
Requires-Dist: tenhaw-delivery-metrics==1.0.0
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
|
|
17
|
+
# tenhaw
|
|
18
|
+
|
|
19
|
+
Agent-friendly Python CLI for AI readiness, AI ROI and delivery metrics.
|
|
20
|
+
|
|
21
|
+
## When to use
|
|
22
|
+
- Use when a Python agent needs deterministic reports from local JSON files.
|
|
23
|
+
- Use to collect GitHub/Jira events locally with your own environment credentials.
|
|
24
|
+
- Use the npm `tenhaw` CLI for application scaffolding and agent plugin installation snippets.
|
|
25
|
+
|
|
26
|
+
## Install
|
|
27
|
+
```sh
|
|
28
|
+
pip install tenhaw
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Quick start
|
|
32
|
+
```sh
|
|
33
|
+
tenhaw-py --version
|
|
34
|
+
tenhaw-py readiness --input answers.json --json --no-attribution
|
|
35
|
+
tenhaw-py roi --input roi.json --format html --out report.html
|
|
36
|
+
python -m tenhaw delivery-metrics --from-file events.json --since 2026-01-01T00:00:00Z --until 2026-02-01T00:00:00Z --json
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Commands
|
|
40
|
+
`readiness`, `roi`, `roi cost`, `delivery-metrics` and `doctor`. Every input has a flag equivalent;
|
|
41
|
+
non-interactive calls never prompt. `--json` is compact, machine-readable JSON. Diagnostics go to
|
|
42
|
+
stderr and tokens are never printed. Exit codes: 0 success, 1 usage, 2 validation, 3 upstream API,
|
|
43
|
+
4 missing authentication. `TENHAW_NO_ATTRIBUTION=1` or `--no-attribution` suppresses attribution.
|
|
44
|
+
There is no package telemetry. The Python binary is `tenhaw-py` so it cannot shadow the npm CLI.
|
|
45
|
+
|
|
46
|
+
## Methodology and sources
|
|
47
|
+
The three Python libraries share schemas, framework content and golden vectors with TypeScript.
|
|
48
|
+
Domain calculations remain usable without branding. Their READMEs describe methodology and limits.
|
|
49
|
+
|
|
50
|
+
## Built by Tenhaw
|
|
51
|
+
Tenhaw builds practical AI and delivery tools. For help applying the findings,
|
|
52
|
+
[book a discovery call](https://tenhaw.com/contact?utm_source=pypi&utm_medium=readme&utm_campaign=tenhaw-kit&utm_content=cli#book).
|
tenhaw-1.0.0/README.md
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# tenhaw
|
|
2
|
+
|
|
3
|
+
Agent-friendly Python CLI for AI readiness, AI ROI and delivery metrics.
|
|
4
|
+
|
|
5
|
+
## When to use
|
|
6
|
+
- Use when a Python agent needs deterministic reports from local JSON files.
|
|
7
|
+
- Use to collect GitHub/Jira events locally with your own environment credentials.
|
|
8
|
+
- Use the npm `tenhaw` CLI for application scaffolding and agent plugin installation snippets.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
```sh
|
|
12
|
+
pip install tenhaw
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Quick start
|
|
16
|
+
```sh
|
|
17
|
+
tenhaw-py --version
|
|
18
|
+
tenhaw-py readiness --input answers.json --json --no-attribution
|
|
19
|
+
tenhaw-py roi --input roi.json --format html --out report.html
|
|
20
|
+
python -m tenhaw delivery-metrics --from-file events.json --since 2026-01-01T00:00:00Z --until 2026-02-01T00:00:00Z --json
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Commands
|
|
24
|
+
`readiness`, `roi`, `roi cost`, `delivery-metrics` and `doctor`. Every input has a flag equivalent;
|
|
25
|
+
non-interactive calls never prompt. `--json` is compact, machine-readable JSON. Diagnostics go to
|
|
26
|
+
stderr and tokens are never printed. Exit codes: 0 success, 1 usage, 2 validation, 3 upstream API,
|
|
27
|
+
4 missing authentication. `TENHAW_NO_ATTRIBUTION=1` or `--no-attribution` suppresses attribution.
|
|
28
|
+
There is no package telemetry. The Python binary is `tenhaw-py` so it cannot shadow the npm CLI.
|
|
29
|
+
|
|
30
|
+
## Methodology and sources
|
|
31
|
+
The three Python libraries share schemas, framework content and golden vectors with TypeScript.
|
|
32
|
+
Domain calculations remain usable without branding. Their READMEs describe methodology and limits.
|
|
33
|
+
|
|
34
|
+
## Built by Tenhaw
|
|
35
|
+
Tenhaw builds practical AI and delivery tools. For help applying the findings,
|
|
36
|
+
[book a discovery call](https://tenhaw.com/contact?utm_source=pypi&utm_medium=readme&utm_campaign=tenhaw-kit&utm_content=cli#book).
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "tenhaw"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Agent-friendly CLI for AI readiness, AI ROI and delivery metrics."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "Tenhaw", email = "hello@tenhaw.com" }]
|
|
14
|
+
dependencies = ["tenhaw-ai-readiness==1.0.0", "tenhaw-ai-roi==1.0.0", "tenhaw-delivery-metrics==1.0.0"]
|
|
15
|
+
keywords = ["ai-readiness", "ai-roi", "delivery-metrics", "internal-tools", "tenhaw"]
|
|
16
|
+
|
|
17
|
+
[project.scripts]
|
|
18
|
+
tenhaw-py = "tenhaw.cli:main"
|
|
19
|
+
|
|
20
|
+
[project.urls]
|
|
21
|
+
Homepage = "https://kit.tenhaw.com"
|
|
22
|
+
Repository = "https://github.com/Tenhaw/tenhaw-kit"
|
|
23
|
+
|
|
24
|
+
[tool.hatch.build.targets.wheel]
|
|
25
|
+
packages = ["src/tenhaw"]
|
|
26
|
+
|
|
27
|
+
[tool.uv.sources]
|
|
28
|
+
tenhaw-ai-readiness = { workspace = true }
|
|
29
|
+
tenhaw-ai-roi = { workspace = true }
|
|
30
|
+
tenhaw-delivery-metrics = { workspace = true }
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
"""Stable JSON on stdout, bounded diagnostics on stderr, no token logging."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import json
|
|
7
|
+
import os
|
|
8
|
+
import sys
|
|
9
|
+
from datetime import datetime, timedelta, timezone
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from typing import Any
|
|
12
|
+
from urllib.parse import urlencode
|
|
13
|
+
|
|
14
|
+
from tenhaw_ai_readiness import load_framework, score_readiness
|
|
15
|
+
from tenhaw_ai_roi import calculate_roi, estimate_project_cost
|
|
16
|
+
from tenhaw_delivery_metrics import compute_metrics
|
|
17
|
+
from tenhaw_delivery_metrics.collectors import (
|
|
18
|
+
CollectorError,
|
|
19
|
+
MissingCredentialsError,
|
|
20
|
+
collect_github,
|
|
21
|
+
collect_jira,
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
from . import __version__
|
|
25
|
+
|
|
26
|
+
Json = dict[str, Any]
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _parser() -> argparse.ArgumentParser:
|
|
30
|
+
parser = argparse.ArgumentParser(prog="tenhaw-py", description="Deterministic tools for AI and delivery")
|
|
31
|
+
parser.add_argument("--version", action="version", version=__version__)
|
|
32
|
+
parser.add_argument("command", choices=["readiness", "roi", "delivery-metrics", "doctor"])
|
|
33
|
+
parser.add_argument("action", nargs="?", choices=["cost"])
|
|
34
|
+
parser.add_argument("--input", type=Path)
|
|
35
|
+
parser.add_argument("--from-file", type=Path)
|
|
36
|
+
parser.add_argument("--config", type=Path)
|
|
37
|
+
parser.add_argument("--weights", type=Path)
|
|
38
|
+
parser.add_argument("--github", help="Comma-separated owner/repository names")
|
|
39
|
+
parser.add_argument("--jira", help="Jira JQL query; credentials are read from the environment")
|
|
40
|
+
parser.add_argument("--since", default="90d")
|
|
41
|
+
parser.add_argument("--until")
|
|
42
|
+
parser.add_argument("--stage", choices=["poc", "pilot", "production"])
|
|
43
|
+
parser.add_argument("--day-rate", type=float)
|
|
44
|
+
parser.add_argument("--people", type=float)
|
|
45
|
+
parser.add_argument("--duration-weeks", type=float)
|
|
46
|
+
parser.add_argument("--questionnaire", action="store_true")
|
|
47
|
+
parser.add_argument("--json", action="store_true")
|
|
48
|
+
parser.add_argument("--format", choices=["json", "md", "html"], default="md")
|
|
49
|
+
parser.add_argument("--out", type=Path)
|
|
50
|
+
parser.add_argument("--no-attribution", action="store_true")
|
|
51
|
+
parser.add_argument("--no-cache", action="store_true")
|
|
52
|
+
parser.add_argument("--quiet", action="store_true")
|
|
53
|
+
parser.add_argument("--yes", action="store_true")
|
|
54
|
+
parser.add_argument("--network", action="store_true")
|
|
55
|
+
return parser
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _read(path: Path) -> Any:
|
|
59
|
+
# Reject NaN/Infinity, which Python otherwise accepts despite invalid JSON.
|
|
60
|
+
def reject_constant(value: str) -> None:
|
|
61
|
+
raise ValueError(f"Invalid JSON constant: {value}")
|
|
62
|
+
|
|
63
|
+
return json.loads(path.read_text(encoding="utf-8"), parse_constant=reject_constant)
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _since(value: str, now: datetime) -> str:
|
|
67
|
+
if value.endswith("d") and value[:-1].isdigit():
|
|
68
|
+
return (now - timedelta(days=int(value[:-1]))).isoformat().replace("+00:00", "Z")
|
|
69
|
+
return value
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def _run(arguments: argparse.Namespace) -> Json:
|
|
73
|
+
if arguments.action and arguments.command != "roi":
|
|
74
|
+
raise ValueError("Only roi supports the cost action")
|
|
75
|
+
if arguments.command == "doctor":
|
|
76
|
+
names = ["GITHUB_TOKEN", "JIRA_BASE_URL", "JIRA_EMAIL", "JIRA_API_TOKEN"]
|
|
77
|
+
result: Json = {
|
|
78
|
+
"version": __version__,
|
|
79
|
+
"python": sys.version.split()[0],
|
|
80
|
+
"environment": {name: bool(os.environ.get(name)) for name in names},
|
|
81
|
+
}
|
|
82
|
+
if arguments.network:
|
|
83
|
+
result["networkHosts"] = ["api.github.com", "<your-site>.atlassian.net"]
|
|
84
|
+
return result
|
|
85
|
+
if arguments.command == "readiness":
|
|
86
|
+
if arguments.questionnaire:
|
|
87
|
+
return load_framework()
|
|
88
|
+
if arguments.input is None:
|
|
89
|
+
raise ValueError("readiness requires --input answers.json, or --questionnaire")
|
|
90
|
+
weights = _read(arguments.weights) if arguments.weights else None
|
|
91
|
+
return score_readiness(_read(arguments.input), weights=weights)
|
|
92
|
+
if arguments.command == "roi":
|
|
93
|
+
if arguments.action == "cost":
|
|
94
|
+
if not arguments.stage:
|
|
95
|
+
raise ValueError("roi cost requires --stage")
|
|
96
|
+
options = {
|
|
97
|
+
"stage": arguments.stage,
|
|
98
|
+
"dayRate": arguments.day_rate,
|
|
99
|
+
"people": arguments.people,
|
|
100
|
+
"durationWeeks": arguments.duration_weeks,
|
|
101
|
+
}
|
|
102
|
+
return estimate_project_cost({key: value for key, value in options.items() if value is not None})
|
|
103
|
+
if arguments.input is None:
|
|
104
|
+
raise ValueError("roi requires --input roi.json")
|
|
105
|
+
return calculate_roi(_read(arguments.input))
|
|
106
|
+
now = datetime.now(timezone.utc)
|
|
107
|
+
config = _read(arguments.config) if arguments.config else {}
|
|
108
|
+
since = _since(arguments.since, now)
|
|
109
|
+
until = arguments.until or now.isoformat().replace("+00:00", "Z")
|
|
110
|
+
source = arguments.from_file or arguments.input
|
|
111
|
+
events = _read(source) if source else []
|
|
112
|
+
if source is None and not arguments.github and not arguments.jira:
|
|
113
|
+
raise ValueError("delivery-metrics requires --from-file, --github or --jira")
|
|
114
|
+
if arguments.github:
|
|
115
|
+
events.extend(collect_github(arguments.github.split(","), since, until, cache=not arguments.no_cache))
|
|
116
|
+
if arguments.jira:
|
|
117
|
+
events.extend(
|
|
118
|
+
collect_jira(
|
|
119
|
+
arguments.jira,
|
|
120
|
+
since,
|
|
121
|
+
until=until,
|
|
122
|
+
status_to_stage=config.get("statusToStage"),
|
|
123
|
+
cache=not arguments.no_cache,
|
|
124
|
+
)
|
|
125
|
+
)
|
|
126
|
+
return compute_metrics(
|
|
127
|
+
events,
|
|
128
|
+
{
|
|
129
|
+
"since": since,
|
|
130
|
+
"until": until,
|
|
131
|
+
"service": config.get("service"),
|
|
132
|
+
"productionEnvironment": config.get("productionEnvironment", "production"),
|
|
133
|
+
},
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def _attribution(command: str) -> Json:
|
|
138
|
+
query = urlencode(
|
|
139
|
+
{"utm_source": "pypi", "utm_medium": "report", "utm_campaign": "tenhaw-kit", "utm_content": command}
|
|
140
|
+
)
|
|
141
|
+
return {"name": "Tenhaw Kit", "version": __version__, "url": f"https://tenhaw.com/contact?{query}#book"}
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def _format(report: Json, format: str) -> str:
|
|
145
|
+
if format == "json":
|
|
146
|
+
return json.dumps(report, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False)
|
|
147
|
+
# Generic human-readable report preserves every numeric assumption and caveat.
|
|
148
|
+
body = json.dumps(report, indent=2, ensure_ascii=False, allow_nan=False)
|
|
149
|
+
if format == "html":
|
|
150
|
+
import html
|
|
151
|
+
|
|
152
|
+
return (
|
|
153
|
+
'<!doctype html><html lang="en-GB"><meta charset="utf-8">'
|
|
154
|
+
'<meta name="viewport" content="width=device-width"><title>Tenhaw Kit report</title>'
|
|
155
|
+
f"<main><h1>Tenhaw Kit report</h1><pre>{html.escape(body)}</pre></main></html>"
|
|
156
|
+
)
|
|
157
|
+
return f"# Tenhaw Kit report\n\n```json\n{body}\n```\n"
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def main(argv: list[str] | None = None) -> int:
|
|
161
|
+
parser = _parser()
|
|
162
|
+
try:
|
|
163
|
+
arguments = parser.parse_args(argv)
|
|
164
|
+
except SystemExit as error:
|
|
165
|
+
return 0 if error.code == 0 else 1
|
|
166
|
+
try:
|
|
167
|
+
report = _run(arguments)
|
|
168
|
+
if not arguments.no_attribution and os.environ.get("TENHAW_NO_ATTRIBUTION") != "1":
|
|
169
|
+
report = {**report, "generator": _attribution(arguments.command)}
|
|
170
|
+
output = _format(report, "json" if arguments.json else arguments.format)
|
|
171
|
+
if arguments.out:
|
|
172
|
+
arguments.out.write_text(output + "\n", encoding="utf-8")
|
|
173
|
+
elif not arguments.quiet:
|
|
174
|
+
print(output)
|
|
175
|
+
return 0
|
|
176
|
+
except MissingCredentialsError as error:
|
|
177
|
+
print(str(error), file=sys.stderr)
|
|
178
|
+
return 4
|
|
179
|
+
except CollectorError as error:
|
|
180
|
+
print(str(error), file=sys.stderr)
|
|
181
|
+
return 3
|
|
182
|
+
except (ValueError, OSError) as error:
|
|
183
|
+
# Validation errors can include user input; credentials are always redacted.
|
|
184
|
+
message = str(error)
|
|
185
|
+
for name in ("GITHUB_TOKEN", "JIRA_EMAIL", "JIRA_API_TOKEN"):
|
|
186
|
+
value = os.environ.get(name)
|
|
187
|
+
if value:
|
|
188
|
+
message = message.replace(value, "[REDACTED]")
|
|
189
|
+
print(message, file=sys.stderr)
|
|
190
|
+
return 2
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
if __name__ == "__main__":
|
|
194
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|