telchines 1.0.0__tar.gz

telchines-1.0.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 1.0.0 - 2026-04-23
+
+First public CLI-first `v1` release target.
+
+Highlights:
+
+- stabilized the documented `1.x` CLI surface
+- promoted package metadata and versioning for public distribution
+- added `--version` support to `tel` and `telchines`
+- documented install, quickstart, providers, adapters, evaluation, compatibility, and release process
+- added public repo assets: license, contributing guide, security policy, changelog
+- added GitHub Actions for CI and release publishing
+- formalized the external retrieval policy and adapter contribution contract
+
+Workflow surface included in `v1`:
+
+- repair
+- triage
+- retrieval
+- waveform inspection
+- spec-to-SVA generation
+- DUT-to-cocotb generation
+- coverage planning
+- benchmark evaluation

telchines-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+Telchines is a CLI-first verification workflow platform. Contributions should preserve three product properties:
+
+- deterministic or inspectable workflow behavior
+- clear evidence and replay artifacts
+- stable user-facing interfaces in the `1.x` line
+
+## Development Setup
+
+```bash
+python -m venv .venv
+. .venv/Scripts/activate
+pip install -e .[dev]
+pytest
+```
+
+## What To Include In A Change
+
+- code changes for the intended behavior
+- tests for user-visible behavior or schema changes
+- docs for any new command, config field, workflow, or contract change
+
+## Change Guidelines
+
+- keep workflows replayable
+- preserve provenance in retrieval and generation outputs
+- do not silently widen policy or egress behavior
+- prefer additive CLI changes over breaking command renames
+- keep generated artifacts reviewable by a human
+
+## Adapters
+
+If you add or extend an adapter:
+
+- document the tool category and validation mode
+- normalize outputs into structured observations
+- define failure behavior clearly when the external tool is unavailable
+- add isolated tests that cover parsing and command construction
+
+See [docs/adapters.md](docs/adapters.md) for the current support contract.
+
+## Providers
+
+If you add provider behavior:
+
+- preserve policy enforcement for `model_mode` and `no_egress`
+- keep request and response artifacts replayable
+- document new config fields in [docs/providers.md](docs/providers.md)
+
+## Release Expectations
+
+Before merging release-facing changes, verify:
+
+- `pytest` passes
+- CLI help and version still work
+- docs match the implemented command surface
+
+See [docs/release-checklist.md](docs/release-checklist.md) for the full release gate.

telchines-1.0.0/LICENSE

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

telchines-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+include README.md
+graft docs

telchines-1.0.0/PKG-INFO

@@ -0,0 +1,312 @@
+Metadata-Version: 2.4
+Name: telchines
+Version: 1.0.0
+Summary: CLI-first verification workflow platform for grounded AI-assisted hardware validation
+Author: Telchines contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ivanbard/telchines
+Project-URL: Repository, https://github.com/ivanbard/telchines
+Project-URL: Issues, https://github.com/ivanbard/telchines/issues
+Project-URL: Changelog, https://github.com/ivanbard/telchines/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/ivanbard/telchines/tree/main/docs
+Keywords: asic,fpga,rtl,verification,sva,cocotb,cli
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: prompt_toolkit<4.0,>=3.0
+Requires-Dist: rich<15.0,>=14.0
+Requires-Dist: typer<1.0,>=0.17
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0; extra == "dev"
+Dynamic: license-file
+
+# Telchines
+
+<p align="center">
+  <img src="docs/assets/readme-hero.svg" alt="Telchines hero banner" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://github.com/ivanbard/telchines/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ivanbard/telchines/ci.yml?branch=main&style=flat-square&label=CI" alt="CI status"></a>
+  <img src="https://img.shields.io/badge/version-v1.0.0-0f172a?style=flat-square" alt="Version 1.0.0">
+  <img src="https://img.shields.io/badge/python-3.11%2B-0b7285?style=flat-square" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/license-MIT-14532d?style=flat-square" alt="MIT License">
+  <img src="https://img.shields.io/badge/benchmarks-18%20cases-7c2d12?style=flat-square" alt="18 benchmark cases">
+</p>
+
+<p align="center">
+  CLI-first verification workflows for hardware teams that want grounded, replayable AI instead of generic repo chat.
+</p>
+
+<p align="center">
+  <a href="#quick-start"><strong>Quick Start</strong></a> |
+  <a href="#what-you-can-do-with-v1"><strong>v1 Workflows</strong></a> |
+  <a href="#how-it-works"><strong>How It Works</strong></a> |
+  <a href="#documentation"><strong>Documentation</strong></a>
+</p>
+
+## Why Telchines
+
+Generic coding assistants are weak at verification work because the real loop is not just text generation. It is specs, RTL, logs, tool feedback, coverage holes, prior runs, and the ability to replay what happened.
+
+Telchines is built around that loop:
+
+- retrieve evidence from RTL, docs, logs, and run history
+- run verification-native workflows instead of generic chat prompts
+- preserve replay artifacts and citations
+- validate outputs through adapters and deterministic gates
+- keep model routing local-first and policy-aware
+
+> Telchines is not trying to replace simulators or formal tools. It is the orchestration layer that helps engineers move from signal to next action faster.
+
+## What You Can Do With v1
+
+| Workflow | What it does | Primary command |
+| --- | --- | --- |
+| Retrieval | Builds task-aware evidence packs from repo and run history | `tel retrieve "query"` |
+| Repair | Proposes and validates minimal fixes from tool output | `tel repair --tool ... --file ...` |
+| Triage | Clusters repeated regressions with evidence and history | `tel triage --logs logs/regressions` |
+| Spec-to-SVA | Generates first-pass assertions from spec plus RTL | `tel gen-sva --spec docs/uart.md --rtl rtl/uart_rx.sv` |
+| DUT-to-Cocotb | Scaffolds a grounded cocotb starter testbench | `tel gen-cocotb --dut rtl/uart_rx.sv --spec docs/uart.md` |
+| Coverage Planning | Classifies uncovered items and ranks next actions | `tel coverage-plan --report cov/coverage.json ...` |
+| Waveform Debug | Parses VCDs and inspects signals from CLI or shell | `tel waveforms show ...` |
+| Benchmarks | Runs the built-in offline evaluation suite | `tel eval run` |
+
+## What It Looks Like
+
+```text
+$ tel
+
+tel[uart] sample_project> /index
+Index Complete
+indexed 18 chunks
+
+tel[uart] sample_project> /triage --logs logs/regressions
+Triage Summary
+run run_... produced 2 cluster(s)
+
+1. UART receiver start-bit regressions grouped together
+likely cause: missing stimulus or broken start-bit detection path
+suggested action: inspect uart_rx start-bit handling and nearby waveform evidence
+evidence: docs/uart.md#L1, rtl/uart_rx.sv#L1, logs/regressions/run_a.log#L1
+
+tel[uart] sample_project> /gen-sva --spec docs/uart.md --rtl rtl/uart_rx.sv
+Spec-to-SVA Result
+provider: heuristic
+status: validated
+artifact: .tel/artifacts/generated/uart_rx_assertions.sv
+validation: passed
+```
+
+## How It Works
+
+<p align="center">
+  <img src="docs/assets/readme-workflow.svg" alt="Telchines workflow diagram" width="100%">
+</p>
+
+Telchines keeps the loop explicit:
+
+1. Index the project and build retrieval context.
+2. Run a verification workflow such as repair, triage, generation, or coverage planning.
+3. Store evidence, artifacts, validation output, and replay metadata under `.tel/`.
+4. Reuse prior runs and benchmark the behavior over time.
+
+## Architecture Snapshot
+
+<p align="center">
+  <img src="docs/assets/readme-architecture.svg" alt="Telchines architecture diagram" width="100%">
+</p>
+
+## Quick Start
+
+Install from PyPI:
+
+```bash
+pip install telchines
+```
+
+Or from source:
+
+```bash
+python -m venv .venv
+. .venv/Scripts/activate
+pip install -e .[dev]
+```
+
+Validate the install:
+
+```bash
+tel --version
+telchines --help
+```
+
+Initialize and index a project:
+
+```bash
+tel project init .
+tel index
+tel providers list
+```
+
+Run a few common workflows:
+
+```bash
+tel retrieve "uart timeout handling"
+tel triage --logs logs/regressions --format human
+tel gen-sva --spec docs/uart.md --rtl rtl/uart_rx.sv
+tel gen-cocotb --dut rtl/uart_rx.sv --spec docs/uart.md --intent "smoke the start-bit path"
+tel coverage-plan --report cov/coverage.json --rtl rtl/uart_rx.sv --spec docs/uart.md --format human
+```
+
+## Interactive Shell
+
+Running `tel` with no arguments opens the shell. Slash commands and lightweight plain-text intents are both supported.
+
+```text
+tel> /help
+tel> /providers
+tel> /index
+tel> /triage --logs logs/regressions
+tel> /gen-sva --spec docs/uart.md --rtl rtl/uart_rx.sv
+tel> show my providers
+tel> triage the regression logs
+tel> /exit
+```
+
+## Adapter And Provider Model
+
+Built-in adapters in `v1`:
+
+- `verilator`
+- `iverilog`
+- `slang`
+- `verible`
+- `symbiyosys`
+
+Provider kinds in `v1`:
+
+- `heuristic`
+- `openai_compatible`
+- `local_command`
+
+Policy controls:
+
+- `model_mode=local` blocks remote providers
+- `model_mode=remote` blocks local command providers
+- `model_mode=hybrid` allows both
+- `no_egress=true` blocks networked providers
+
+See [docs/adapters.md](docs/adapters.md) and [docs/providers.md](docs/providers.md) for the exact support contract.
+
+## Benchmarks And Release Validation
+
+Telchines ships with an offline benchmark suite covering:
+
+- repair
+- triage
+- retrieval
+- spec-to-SVA
+- DUT-to-cocotb
+- coverage planning
+
+Run it with:
+
+```bash
+tel eval run
+tel eval report
+```
+
+The current default suite contains **18 cases** and is part of the `v1` credibility story, not optional polish.
+
+## v1 Scope
+
+Included:
+
+- interactive shell and one-shot CLI
+- project indexing and retrieval
+- run storage and replay
+- repair, triage, waveform inspection, `gen-sva`, `gen-cocotb`, and `coverage-plan`
+- provider policy controls for `local`, `hybrid`, `remote`, and `no_egress`
+- built-in benchmark suite
+
+Not in `v1`:
+
+- web UI
+- hosted service
+- enterprise-only integrations
+- richer shell affordances like command palettes and `@file` mentions
+- broader regression-manager integrations beyond the current adapter surface
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [Worked Examples](docs/examples.md)
+- [Provider Configuration](docs/providers.md)
+- [Adapter Support And Contribution Contract](docs/adapters.md)
+- [External Retrieval Policy](docs/external-retrieval-policy.md)
+- [Evaluation And Benchmarks](docs/evaluation.md)
+- [Compatibility Promise](docs/compatibility.md)
+- [Release Checklist](docs/release-checklist.md)
+
+## Stability Promise For v1
+
+The `1.x` line treats these interfaces as stable unless explicitly deprecated:
+
+- top-level CLI command names
+- `.tel/config.json` layout
+- run-store replay artifacts
+- JSON output shape for the main workflow commands
+
+See [docs/compatibility.md](docs/compatibility.md) for the exact boundary.
+
+<details>
+<summary><strong>Full CLI Surface</strong></summary>
+
+- `tel`
+- `tel shell`
+- `tel project init`
+- `tel index`
+- `tel retrieve`
+- `tel repair`
+- `tel triage`
+- `tel coverage-plan`
+- `tel gen-sva`
+- `tel gen-cocotb`
+- `tel waveforms list`
+- `tel waveforms show`
+- `tel waveforms signals`
+- `tel waveforms inspect`
+- `tel runs list`
+- `tel runs show`
+- `tel runs replay`
+- `tel adapters list`
+- `tel providers list`
+- `tel eval run`
+- `tel eval report`
+
+</details>
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+Project contribution and disclosure guidance:
+
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [SECURITY.md](SECURITY.md)
+- [CHANGELOG.md](CHANGELOG.md)

telchines-1.0.0/README.md

@@ -0,0 +1,278 @@
+# Telchines
+
+<p align="center">
+  <img src="docs/assets/readme-hero.svg" alt="Telchines hero banner" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://github.com/ivanbard/telchines/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ivanbard/telchines/ci.yml?branch=main&style=flat-square&label=CI" alt="CI status"></a>
+  <img src="https://img.shields.io/badge/version-v1.0.0-0f172a?style=flat-square" alt="Version 1.0.0">
+  <img src="https://img.shields.io/badge/python-3.11%2B-0b7285?style=flat-square" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/license-MIT-14532d?style=flat-square" alt="MIT License">
+  <img src="https://img.shields.io/badge/benchmarks-18%20cases-7c2d12?style=flat-square" alt="18 benchmark cases">
+</p>
+
+<p align="center">
+  CLI-first verification workflows for hardware teams that want grounded, replayable AI instead of generic repo chat.
+</p>
+
+<p align="center">
+  <a href="#quick-start"><strong>Quick Start</strong></a> |
+  <a href="#what-you-can-do-with-v1"><strong>v1 Workflows</strong></a> |
+  <a href="#how-it-works"><strong>How It Works</strong></a> |
+  <a href="#documentation"><strong>Documentation</strong></a>
+</p>
+
+## Why Telchines
+
+Generic coding assistants are weak at verification work because the real loop is not just text generation. It is specs, RTL, logs, tool feedback, coverage holes, prior runs, and the ability to replay what happened.
+
+Telchines is built around that loop:
+
+- retrieve evidence from RTL, docs, logs, and run history
+- run verification-native workflows instead of generic chat prompts
+- preserve replay artifacts and citations
+- validate outputs through adapters and deterministic gates
+- keep model routing local-first and policy-aware
+
+> Telchines is not trying to replace simulators or formal tools. It is the orchestration layer that helps engineers move from signal to next action faster.
+
+## What You Can Do With v1
+
+| Workflow | What it does | Primary command |
+| --- | --- | --- |
+| Retrieval | Builds task-aware evidence packs from repo and run history | `tel retrieve "query"` |
+| Repair | Proposes and validates minimal fixes from tool output | `tel repair --tool ... --file ...` |
+| Triage | Clusters repeated regressions with evidence and history | `tel triage --logs logs/regressions` |
+| Spec-to-SVA | Generates first-pass assertions from spec plus RTL | `tel gen-sva --spec docs/uart.md --rtl rtl/uart_rx.sv` |
+| DUT-to-Cocotb | Scaffolds a grounded cocotb starter testbench | `tel gen-cocotb --dut rtl/uart_rx.sv --spec docs/uart.md` |
+| Coverage Planning | Classifies uncovered items and ranks next actions | `tel coverage-plan --report cov/coverage.json ...` |
+| Waveform Debug | Parses VCDs and inspects signals from CLI or shell | `tel waveforms show ...` |
+| Benchmarks | Runs the built-in offline evaluation suite | `tel eval run` |
+
+## What It Looks Like
+
+```text
+$ tel
+
+tel[uart] sample_project> /index
+Index Complete
+indexed 18 chunks
+
+tel[uart] sample_project> /triage --logs logs/regressions
+Triage Summary
+run run_... produced 2 cluster(s)
+
+1. UART receiver start-bit regressions grouped together
+likely cause: missing stimulus or broken start-bit detection path
+suggested action: inspect uart_rx start-bit handling and nearby waveform evidence
+evidence: docs/uart.md#L1, rtl/uart_rx.sv#L1, logs/regressions/run_a.log#L1
+
+tel[uart] sample_project> /gen-sva --spec docs/uart.md --rtl rtl/uart_rx.sv
+Spec-to-SVA Result
+provider: heuristic
+status: validated
+artifact: .tel/artifacts/generated/uart_rx_assertions.sv
+validation: passed
+```
+
+## How It Works
+
+<p align="center">
+  <img src="docs/assets/readme-workflow.svg" alt="Telchines workflow diagram" width="100%">
+</p>
+
+Telchines keeps the loop explicit:
+
+1. Index the project and build retrieval context.
+2. Run a verification workflow such as repair, triage, generation, or coverage planning.
+3. Store evidence, artifacts, validation output, and replay metadata under `.tel/`.
+4. Reuse prior runs and benchmark the behavior over time.
+
+## Architecture Snapshot
+
+<p align="center">
+  <img src="docs/assets/readme-architecture.svg" alt="Telchines architecture diagram" width="100%">
+</p>
+
+## Quick Start
+
+Install from PyPI:
+
+```bash
+pip install telchines
+```
+
+Or from source:
+
+```bash
+python -m venv .venv
+. .venv/Scripts/activate
+pip install -e .[dev]
+```
+
+Validate the install:
+
+```bash
+tel --version
+telchines --help
+```
+
+Initialize and index a project:
+
+```bash
+tel project init .
+tel index
+tel providers list
+```
+
+Run a few common workflows:
+
+```bash
+tel retrieve "uart timeout handling"
+tel triage --logs logs/regressions --format human
+tel gen-sva --spec docs/uart.md --rtl rtl/uart_rx.sv
+tel gen-cocotb --dut rtl/uart_rx.sv --spec docs/uart.md --intent "smoke the start-bit path"
+tel coverage-plan --report cov/coverage.json --rtl rtl/uart_rx.sv --spec docs/uart.md --format human
+```
+
+## Interactive Shell
+
+Running `tel` with no arguments opens the shell. Slash commands and lightweight plain-text intents are both supported.
+
+```text
+tel> /help
+tel> /providers
+tel> /index
+tel> /triage --logs logs/regressions
+tel> /gen-sva --spec docs/uart.md --rtl rtl/uart_rx.sv
+tel> show my providers
+tel> triage the regression logs
+tel> /exit
+```
+
+## Adapter And Provider Model
+
+Built-in adapters in `v1`:
+
+- `verilator`
+- `iverilog`
+- `slang`
+- `verible`
+- `symbiyosys`
+
+Provider kinds in `v1`:
+
+- `heuristic`
+- `openai_compatible`
+- `local_command`
+
+Policy controls:
+
+- `model_mode=local` blocks remote providers
+- `model_mode=remote` blocks local command providers
+- `model_mode=hybrid` allows both
+- `no_egress=true` blocks networked providers
+
+See [docs/adapters.md](docs/adapters.md) and [docs/providers.md](docs/providers.md) for the exact support contract.
+
+## Benchmarks And Release Validation
+
+Telchines ships with an offline benchmark suite covering:
+
+- repair
+- triage
+- retrieval
+- spec-to-SVA
+- DUT-to-cocotb
+- coverage planning
+
+Run it with:
+
+```bash
+tel eval run
+tel eval report
+```
+
+The current default suite contains **18 cases** and is part of the `v1` credibility story, not optional polish.
+
+## v1 Scope
+
+Included:
+
+- interactive shell and one-shot CLI
+- project indexing and retrieval
+- run storage and replay
+- repair, triage, waveform inspection, `gen-sva`, `gen-cocotb`, and `coverage-plan`
+- provider policy controls for `local`, `hybrid`, `remote`, and `no_egress`
+- built-in benchmark suite
+
+Not in `v1`:
+
+- web UI
+- hosted service
+- enterprise-only integrations
+- richer shell affordances like command palettes and `@file` mentions
+- broader regression-manager integrations beyond the current adapter surface
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [Worked Examples](docs/examples.md)
+- [Provider Configuration](docs/providers.md)
+- [Adapter Support And Contribution Contract](docs/adapters.md)
+- [External Retrieval Policy](docs/external-retrieval-policy.md)
+- [Evaluation And Benchmarks](docs/evaluation.md)
+- [Compatibility Promise](docs/compatibility.md)
+- [Release Checklist](docs/release-checklist.md)
+
+## Stability Promise For v1
+
+The `1.x` line treats these interfaces as stable unless explicitly deprecated:
+
+- top-level CLI command names
+- `.tel/config.json` layout
+- run-store replay artifacts
+- JSON output shape for the main workflow commands
+
+See [docs/compatibility.md](docs/compatibility.md) for the exact boundary.
+
+<details>
+<summary><strong>Full CLI Surface</strong></summary>
+
+- `tel`
+- `tel shell`
+- `tel project init`
+- `tel index`
+- `tel retrieve`
+- `tel repair`
+- `tel triage`
+- `tel coverage-plan`
+- `tel gen-sva`
+- `tel gen-cocotb`
+- `tel waveforms list`
+- `tel waveforms show`
+- `tel waveforms signals`
+- `tel waveforms inspect`
+- `tel runs list`
+- `tel runs show`
+- `tel runs replay`
+- `tel adapters list`
+- `tel providers list`
+- `tel eval run`
+- `tel eval report`
+
+</details>
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+Project contribution and disclosure guidance:
+
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [SECURITY.md](SECURITY.md)
+- [CHANGELOG.md](CHANGELOG.md)