kentaro 0.1.0__tar.gz

kentaro-0.1.0/LICENSE

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

kentaro-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: kentaro
+Version: 0.1.0
+Summary: Read-only Agentic Maysano Harness for sourced portfolio context and local governance validation
+Author: Maysano
+License-Expression: MIT
+Project-URL: Homepage, https://maysano.com/kentaro
+Project-URL: Documentation, https://github.com/Maysano/Kentaro/tree/main/docs
+Project-URL: Repository, https://github.com/Maysano/Kentaro
+Project-URL: Issues, https://github.com/Maysano/Kentaro/issues
+Project-URL: ODPS Specifications, https://opendataproducts.org/
+Keywords: agents,governance,maysano,odps,portfolio,read-only
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: odps
+Requires-Dist: open-data-products<0.5,>=0.3.4; extra == "odps"
+Dynamic: license-file
+
+# Kentaro
+
+Kentaro is the open-source, read-only Agentic Maysano Harness. It gives you a
+working local portfolio briefing and sourced dashboard immediately, then lets you
+opt in to a bounded read-only Maysano source without turning Kentaro into a system
+that acts on your behalf.
+
+Learn more at [maysano.com/kentaro](https://maysano.com/kentaro).
+
+## Install
+
+Kentaro requires Python 3.11 or later.
+
+```shell
+python -m pip install kentaro
+```
+
+## Run the demo
+
+Run the complete synthetic demonstration with no account, configuration file,
+repository checkout, API key, or network request:
+
+```shell
+kentaro demo
+```
+
+It prints a sourced portfolio briefing and writes a dashboard to a new timestamped
+file under `.kentaro/workspace/`. Kentaro creates that directory automatically and
+prints the complete local path.
+
+## Use Kentaro locally
+
+The normal local commands use the packaged synthetic portfolio context:
+
+```shell
+kentaro portfolio brief
+kentaro dashboard
+```
+
+`kentaro dashboard` always creates a fresh timestamped HTML file in
+`.kentaro/workspace/`; it never overwrites an existing dashboard.
+
+## Connect a read-only Maysano source
+
+Live access is explicit and opt-in. Configure a Maysano-issued read-only key through
+the guided local setup, then select the source for an individual read:
+
+```shell
+kentaro configure maysano
+kentaro portfolio brief --source maysano
+```
+
+The key is stored only in Kentaro's ignored local workspace and is never printed.
+The pilot source is GET-only. It does not currently provide owners, decisions,
+risks, evidence, approval history, or milestones; Kentaro labels those fields as
+unavailable rather than inventing them.
+
+## Safety boundary
+
+Kentaro v0.1 retrieves bounded sourced context, validates local versioned governance
+and delivery objects, generates drafts and reports, classifies proposed requests, and
+exports local evidence. It does not create external records, write to Maysano or a
+business-context graph, execute business actions, request or process approvals, or
+claim immutable or compliance-grade audit. The optional local draft commands create
+local artifacts only; a hosted provider requires explicit acknowledgement before it
+receives source content.
+
+Maysano remains the system of record for portfolio state, approvals, graph updates,
+tenant controls, authoritative revocation, retention, and platform audit. An
+`allowed` classification means only that a request is structurally in scope; it is
+not permission to execute.
+
+## Advanced configuration and governance
+
+TOML profiles are an advanced team configuration mechanism for named environments,
+custom API endpoints or workspace paths, model declarations, organisation policies,
+and non-default profiles. They are never needed for the normal local experience.
+
+To create proposed local data-product, use-case, or objective drafts from Markdown or
+text, install the optional SDK integration. These local artifacts align with the
+[Open Data Products (ODPS) family of specifications](https://opendataproducts.org/):
+
+```shell
+python -m pip install "kentaro[odps]"
+kentaro data-product draft ./business-context.md
+kentaro use-case draft ./business-context.md
+kentaro objective draft ./business-context.md
+```
+
+Validate a saved local draft without generating anything:
+
+```shell
+kentaro data-product validate ./data-product.yaml
+kentaro use-case validate ./use-case.yaml
+kentaro objective validate ./objective.yaml
+```
+
+The default provider is local Ollama. A hosted provider requires an explicit provider
+configuration and `--allow-hosted-content`, because it may receive the source document.
+Each result remains a local draft; it never creates a Maysano record or grants authority.
+
+Detailed material is kept out of onboarding:
+
+- [Getting started](https://github.com/Maysano/Kentaro/blob/main/docs/getting-started.md)
+- [Advanced configuration](https://github.com/Maysano/Kentaro/blob/main/docs/configuration.md)
+- [Local draft artifacts](https://github.com/Maysano/Kentaro/blob/main/docs/data-product-drafts.md)
+- [Governance and delivery object model](https://github.com/Maysano/Kentaro/blob/main/docs/governance-and-delivery-object-model.md)
+- [Architecture](https://github.com/Maysano/Kentaro/blob/main/docs/architecture.md)
+- [Security and data boundaries](https://github.com/Maysano/Kentaro/blob/main/docs/security-and-data-boundaries.md)
+- [Developer guide](https://github.com/Maysano/Kentaro/blob/main/docs/developer-guide.md)
+
+[MIT License](LICENSE) © 2026 Maysano.

kentaro-0.1.0/README.md

@@ -0,0 +1,112 @@
+# Kentaro
+
+Kentaro is the open-source, read-only Agentic Maysano Harness. It gives you a
+working local portfolio briefing and sourced dashboard immediately, then lets you
+opt in to a bounded read-only Maysano source without turning Kentaro into a system
+that acts on your behalf.
+
+Learn more at [maysano.com/kentaro](https://maysano.com/kentaro).
+
+## Install
+
+Kentaro requires Python 3.11 or later.
+
+```shell
+python -m pip install kentaro
+```
+
+## Run the demo
+
+Run the complete synthetic demonstration with no account, configuration file,
+repository checkout, API key, or network request:
+
+```shell
+kentaro demo
+```
+
+It prints a sourced portfolio briefing and writes a dashboard to a new timestamped
+file under `.kentaro/workspace/`. Kentaro creates that directory automatically and
+prints the complete local path.
+
+## Use Kentaro locally
+
+The normal local commands use the packaged synthetic portfolio context:
+
+```shell
+kentaro portfolio brief
+kentaro dashboard
+```
+
+`kentaro dashboard` always creates a fresh timestamped HTML file in
+`.kentaro/workspace/`; it never overwrites an existing dashboard.
+
+## Connect a read-only Maysano source
+
+Live access is explicit and opt-in. Configure a Maysano-issued read-only key through
+the guided local setup, then select the source for an individual read:
+
+```shell
+kentaro configure maysano
+kentaro portfolio brief --source maysano
+```
+
+The key is stored only in Kentaro's ignored local workspace and is never printed.
+The pilot source is GET-only. It does not currently provide owners, decisions,
+risks, evidence, approval history, or milestones; Kentaro labels those fields as
+unavailable rather than inventing them.
+
+## Safety boundary
+
+Kentaro v0.1 retrieves bounded sourced context, validates local versioned governance
+and delivery objects, generates drafts and reports, classifies proposed requests, and
+exports local evidence. It does not create external records, write to Maysano or a
+business-context graph, execute business actions, request or process approvals, or
+claim immutable or compliance-grade audit. The optional local draft commands create
+local artifacts only; a hosted provider requires explicit acknowledgement before it
+receives source content.
+
+Maysano remains the system of record for portfolio state, approvals, graph updates,
+tenant controls, authoritative revocation, retention, and platform audit. An
+`allowed` classification means only that a request is structurally in scope; it is
+not permission to execute.
+
+## Advanced configuration and governance
+
+TOML profiles are an advanced team configuration mechanism for named environments,
+custom API endpoints or workspace paths, model declarations, organisation policies,
+and non-default profiles. They are never needed for the normal local experience.
+
+To create proposed local data-product, use-case, or objective drafts from Markdown or
+text, install the optional SDK integration. These local artifacts align with the
+[Open Data Products (ODPS) family of specifications](https://opendataproducts.org/):
+
+```shell
+python -m pip install "kentaro[odps]"
+kentaro data-product draft ./business-context.md
+kentaro use-case draft ./business-context.md
+kentaro objective draft ./business-context.md
+```
+
+Validate a saved local draft without generating anything:
+
+```shell
+kentaro data-product validate ./data-product.yaml
+kentaro use-case validate ./use-case.yaml
+kentaro objective validate ./objective.yaml
+```
+
+The default provider is local Ollama. A hosted provider requires an explicit provider
+configuration and `--allow-hosted-content`, because it may receive the source document.
+Each result remains a local draft; it never creates a Maysano record or grants authority.
+
+Detailed material is kept out of onboarding:
+
+- [Getting started](https://github.com/Maysano/Kentaro/blob/main/docs/getting-started.md)
+- [Advanced configuration](https://github.com/Maysano/Kentaro/blob/main/docs/configuration.md)
+- [Local draft artifacts](https://github.com/Maysano/Kentaro/blob/main/docs/data-product-drafts.md)
+- [Governance and delivery object model](https://github.com/Maysano/Kentaro/blob/main/docs/governance-and-delivery-object-model.md)
+- [Architecture](https://github.com/Maysano/Kentaro/blob/main/docs/architecture.md)
+- [Security and data boundaries](https://github.com/Maysano/Kentaro/blob/main/docs/security-and-data-boundaries.md)
+- [Developer guide](https://github.com/Maysano/Kentaro/blob/main/docs/developer-guide.md)
+
+[MIT License](LICENSE) © 2026 Maysano.

kentaro-0.1.0/kentaro/__main__.py

@@ -0,0 +1,3 @@
+from kentaro.cli import main
+
+raise SystemExit(main())

kentaro-0.1.0/kentaro/api/demo.py

@@ -0,0 +1,48 @@
+"""Local fixture contract. This module contains no network transport."""
+import json
+from datetime import datetime, timezone
+from importlib.resources import as_file, files
+
+
+DEMO_SCOPE = "portfolio-demo"
+
+
+def read_packaged_demo() -> dict:
+    """Read the synthetic demo packaged with Kentaro; no configuration or network is used."""
+    resource = files("kentaro.resources").joinpath("demo-portfolio.json")
+    with as_file(resource) as fixture:
+        return DemoClient(fixture, DEMO_SCOPE).read_portfolio()
+
+
+class DemoClient:
+    def __init__(self, fixture, scope):
+        self._fixture = fixture
+        self._scope = scope
+
+    def request(self, method):
+        if method != "GET":
+            raise ValueError("Only GET is permitted in Kentaro v0.1")
+        return self.read_portfolio()
+
+    def read_portfolio(self):
+        with open(self._fixture, encoding="utf-8") as stream:
+            data = json.load(stream)
+        if data.get("schema_version") != 1 or data.get("synthetic") is not True:
+            raise ValueError("Expected a version 1 synthetic fixture")
+        records = [r for r in data["records"] if r["scope"] == self._scope]
+        if not records:
+            raise ValueError("No demo records available in the selected scope")
+        ids = {r["id"] for r in records}
+        if len(ids) != len(records):
+            raise ValueError("Duplicate source IDs")
+        for record in records:
+            for key in ("id", "kind", "title", "owner", "state", "version", "updated_at", "source_ref"):
+                if key not in record:
+                    raise ValueError("Incomplete source metadata: " + key)
+        relationships = [r for r in data["relationships"] if r["scope"] == self._scope
+                         and r["source"] in ids and r["target"] in ids]
+        return {"scope": self._scope, "records": records, "relationships": relationships,
+                "retrieved_at": datetime.now(timezone.utc).isoformat(),
+                "limitations": ["Synthetic fixture; live Maysano API capabilities unverified.",
+                                "Fixture load time is not platform freshness; use record timestamps.",
+                                "Acceptance criteria, delivery milestones and approval history unavailable."]}

kentaro-0.1.0/kentaro/api/live.py

@@ -0,0 +1,214 @@
+"""Read-only client for the documented Maysano external pilot API."""
+from __future__ import annotations
+
+import json
+import ssl
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode, urlsplit
+from urllib.request import Request, urlopen
+
+
+RESOURCE_SPECS = (
+    ("products", "data_product", "name"),
+    ("business-objectives", "objective", "title"),
+    ("business-use-cases", "use_case", "name"),
+)
+LINK_KINDS = {
+    "products": "data_product",
+    "objectives": "objective",
+    "useCases": "use_case",
+    "kpis": "kpi",
+}
+
+
+def _trusted_tls_context():
+    """Keep TLS verification enabled, preferring certifi when the runtime supplies it."""
+    try:
+        import certifi
+    except ModuleNotFoundError:
+        return ssl.create_default_context()
+    return ssl.create_default_context(cafile=certifi.where())
+
+
+class RequestBudgetExhausted(Exception):
+    """Raised before exceeding the documented per-key request allowance."""
+
+
+def load_live_environment(path):
+    """Read only the expected key/value pairs without executing a dotenv file."""
+    values = {}
+    try:
+        lines = Path(path).read_text(encoding="utf-8").splitlines()
+    except OSError as error:
+        raise ValueError("Unable to read live environment file") from error
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        key, marker, value = line.partition("=")
+        if not marker or key not in {"API_BASE_URL", "API_KEY"}:
+            raise ValueError("Live environment file contains an unsupported setting")
+        if key in values:
+            raise ValueError("Live environment file contains a duplicate setting")
+        values[key] = value.strip()
+    if not values.get("API_BASE_URL") or not values.get("API_KEY"):
+        raise ValueError("Live environment requires API_BASE_URL and API_KEY")
+    parsed = urlsplit(values["API_BASE_URL"])
+    if parsed.scheme != "https" or not parsed.netloc or parsed.username or parsed.password:
+        raise ValueError("API_BASE_URL must be an HTTPS URL without user credentials")
+    if parsed.query or parsed.fragment:
+        raise ValueError("API_BASE_URL must not contain query or fragment components")
+    values["API_BASE_URL"] = values["API_BASE_URL"].rstrip("/")
+    return values
+
+
+class LiveClient:
+    """Retrieves read-only portfolio metadata without persisting API responses."""
+
+    def __init__(self, environment_file, scope, *, timeout=30, request_budget=40):
+        self._settings = load_live_environment(environment_file)
+        self._scope = scope
+        self._timeout = timeout
+        self._request_budget = request_budget
+        self._attempts = 0
+        self._tls_context = _trusted_tls_context()
+
+    def request(self, method):
+        if method != "GET":
+            raise ValueError("Only GET is permitted in Kentaro v0.1")
+        return self.read_portfolio()
+
+    def _get_json(self, path, parameters=None):
+        if self._attempts >= self._request_budget:
+            raise RequestBudgetExhausted
+        query = urlencode(parameters or {})
+        url = self._settings["API_BASE_URL"] + path + ("?" + query if query else "")
+        request = Request(url, headers={"Authorization": "Bearer " + self._settings["API_KEY"]}, method="GET")
+        self._attempts += 1
+        try:
+            with urlopen(request, timeout=self._timeout, context=self._tls_context) as response:
+                return json.load(response)
+        except HTTPError as error:
+            raise ValueError(f"Maysano API request failed with HTTP status {error.code}") from error
+        except URLError as error:
+            raise ValueError("Maysano API connection failed") from error
+        except (json.JSONDecodeError, UnicodeDecodeError) as error:
+            raise ValueError("Maysano API returned invalid JSON") from error
+
+    def _list_resource(self, resource):
+        rows = []
+        offset = 0
+        total = None
+        complete = False
+        while True:
+            try:
+                payload = self._get_json("/" + resource, {"limit": 100, "offset": offset})
+            except RequestBudgetExhausted:
+                return rows, False, total
+            if not isinstance(payload, dict) or not isinstance(payload.get("data"), list):
+                raise ValueError(f"Maysano API returned an invalid {resource} list response")
+            pagination = payload.get("pagination")
+            if not isinstance(pagination, dict) or not isinstance(pagination.get("total"), int):
+                raise ValueError(f"Maysano API returned invalid {resource} pagination")
+            rows.extend(payload["data"])
+            total = pagination["total"]
+            if not payload["data"] or offset + 100 >= total:
+                complete = True
+                break
+            offset += 100
+        return rows, complete, total
+
+    @staticmethod
+    def _normalise_record(row, resource, kind, title_key):
+        if not isinstance(row, dict) or not isinstance(row.get("id"), str) or not row["id"]:
+            raise ValueError(f"Maysano API returned a {resource} record without an ID")
+        record_id = row["id"]
+        title = row.get(title_key)
+        return {
+            "id": record_id,
+            "kind": kind,
+            "title": title if isinstance(title, str) and title else "not supplied",
+            "owner": None,
+            "state": row.get("status") if isinstance(row.get("status"), str) else "not supplied",
+            "version": str(row["version"]) if row.get("version") is not None else "not supplied",
+            "updated_at": row.get("updatedAt") if isinstance(row.get("updatedAt"), str) else "not supplied",
+            "source_ref": f"maysano:/{resource}/{quote(record_id, safe='')}",
+            "resource": resource,
+        }
+
+    def _links_for_record(self, record, known_ids, limitations):
+        try:
+            detail = self._get_json("/" + record["resource"] + "/" + quote(record["id"], safe=""))
+        except RequestBudgetExhausted:
+            limitations.append("Relationship retrieval stopped before the documented request budget was exceeded.")
+            return [], False
+        if not isinstance(detail, dict) or detail.get("id") != record["id"]:
+            raise ValueError(f"Maysano API returned an invalid detail response for {record['id']}")
+        links = detail.get("links", {})
+        truncated = detail.get("linksTruncated", {})
+        if not isinstance(links, dict) or not isinstance(truncated, dict):
+            raise ValueError(f"Maysano API returned invalid link metadata for {record['id']}")
+        relationships = []
+        for collection, target_kind in LINK_KINDS.items():
+            values = links.get(collection)
+            if values is None:
+                continue
+            if not isinstance(values, list) or any(not isinstance(value, str) for value in values):
+                raise ValueError(f"Maysano API returned invalid {collection} links for {record['id']}")
+            if truncated.get(collection) is True:
+                limitations.append(f"Links from {record['id']} to {collection} are truncated by the source API.")
+            for target in values:
+                if target not in known_ids:
+                    limitations.append(f"A documented link from {record['id']} to {target} could not be represented in the retrieved record set.")
+                    continue
+                relationships.append({
+                    "id": f"client-link:{record['id']}:{collection}:{target}",
+                    "source": record["id"],
+                    "target": target,
+                    "type": "related_" + target_kind,
+                    "version": "not supplied",
+                    "updated_at": "not supplied",
+                    "source_ref": record["source_ref"] + "#links." + collection,
+                })
+        return relationships, True
+
+    def read_portfolio(self):
+        records = []
+        limitations = [
+            "Live Maysano pilot API snapshot; the key is organization-bound and permissions are independent.",
+            "The external API does not provide owner fields; ownership is unknown unless another approved source is added.",
+            "The external API does not provide relationship IDs, versions, or timestamps; displayed link references are client-derived from detail responses.",
+            "List pagination is not a consistent snapshot; records may change while pages are read.",
+            "Responses are not cached because the API specifies Cache-Control: no-store.",
+            "Decisions, risks, evidence, approval history, and delivery milestones are not available through the documented external endpoints.",
+        ]
+        for resource, kind, title_key in RESOURCE_SPECS:
+            rows, complete, total = self._list_resource(resource)
+            if not complete:
+                limitations.append(f"{resource} retrieval is incomplete after {len(rows)} of {total if total is not None else 'unknown'} listed records.")
+            records.extend(self._normalise_record(row, resource, kind, title_key) for row in rows)
+        ids = {record["id"] for record in records}
+        if len(ids) != len(records):
+            raise ValueError("Maysano API returned duplicate record IDs across retrieved resources")
+        relationships = []
+        links_complete = True
+        for record in records:
+            record_links, complete = self._links_for_record(record, ids, limitations)
+            relationships.extend(record_links)
+            links_complete = links_complete and complete
+            if not complete:
+                break
+        if not links_complete:
+            limitations.append("Relationship coverage is incomplete because detail retrieval stopped at the client request budget.")
+        return {
+            "scope": self._scope,
+            "records": records,
+            "relationships": relationships,
+            "retrieved_at": datetime.now(timezone.utc).isoformat(),
+            "source_label": "Live Maysano pilot API",
+            "cache_label": "Cache disabled (API no-store)",
+            "owner_fields_available": False,
+            "limitations": list(dict.fromkeys(limitations)),
+        }