architec 0.2.11__tar.gz

architec-0.2.11/LICENSE

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

architec-0.2.11/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.md
+include README.zh-CN.md
+recursive-include config *.yaml *.json
+recursive-include prompts *.md
+recursive-include tools *.py *.sh

architec-0.2.11/PKG-INFO

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: architec
+Version: 0.2.11
+Summary: Architecture analysis CLI powered by Hippos bundles and backend LLMs.
+Author: SeemSeam
+Maintainer: SeemSeam
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SeemSeam/architec
+Project-URL: Repository, https://github.com/SeemSeam/architec
+Project-URL: Issues, https://github.com/SeemSeam/architec/issues
+Keywords: architecture,architecture-review,cli,code-analysis,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: certifi>=2024.0.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: seemseam_llmgateway>=0.1.2
+Requires-Dist: seemseam_hippos>=0.1.7
+Requires-Dist: cryptography>=43
+Dynamic: license-file
+
+# Architec
+
+**Incremental architecture review for AI-assisted codebases.**
+
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![CLI](https://img.shields.io/badge/CLI-archi-222222)](#quick-start)
+[![Login](https://img.shields.io/badge/login-not_required-green)](#no-login-required)
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+Architec is an advisory architecture analysis CLI. It helps answer one
+practical question:
+
+> Will this change make the codebase harder to maintain?
+
+It reviews current changes by default, asks an LLM to interpret compact
+selected-scope evidence, and reports architecture risks such as duplicated
+logic, shadow implementations, unclear boundaries, stale structure, topology
+pressure, and risky hotspots.
+
+Architec does not make merge decisions and does not edit code. It gives
+structured advice for humans and coding agents to review.
+
+## Why Architec
+
+LLM-assisted development can move quickly, but architecture can drift quietly.
+Architec is designed to catch the kinds of issues that accumulate over time:
+
+- repeated implementations and "same idea twice" code;
+- compatibility paths that blur into canonical implementations;
+- changed files crossing intended module boundaries;
+- stale cleanup/archive candidates;
+- high-risk work landing in churn-heavy areas;
+- full-project topology pressure that is easy to miss during local edits.
+
+The default workflow is incremental-first:
+
+```bash
+archi
+```
+
+Use full review when you want the whole-project baseline:
+
+```bash
+archi --full
+```
+
+## How It Fits Together
+
+Architec is the review layer. It uses two companion components:
+
+| Component | Command / package | Role |
+| --- | --- | --- |
+| **Architec** | `archi` / `architec` | Runs architecture review, calls the LLM through llmgateway, writes advisory results under `.architec/`. |
+| **Hippos** | `hippos` / `seemseam-hippos` | Builds structural project snapshots under `.hippos/`: file manifests, code signatures, repository indexes, structure prompts, and metrics. |
+| **llmgateway** | `llmgateway` | Owns provider credentials, base URLs, API style, model names, and strong/weak model routing. |
+
+```text
+source tree + git changes
+        |
+        v
+Hippos structural snapshot  ->  .hippos/
+        |
+        v
+Architec evidence builder  ->  selected-scope or full-project context
+        |
+        v
+llmgateway LLM call        ->  strong / weak model tiers
+        |
+        v
+Architec review output     ->  .architec/
+```
+
+Day-to-day `archi` runs still use the LLM, but they avoid refreshing the whole
+Hippos snapshot unless requested. `archi --full` uses the Hippos snapshot more
+heavily, and `archi --refresh-from-hippos --full` refreshes it before review.
+
+## How It Works
+
+Architec combines deterministic code signals with LLM interpretation. The
+deterministic layer keeps the review grounded in concrete evidence; the LLM
+layer turns that evidence into readable architecture advice.
+
+1. **Select scope**
+   - `archi` reads the current git changes and focuses on changed files.
+   - `archi --full` reviews the whole project.
+
+2. **Read structural context**
+   - Hippos produces `.hippos/` snapshots: file manifests, code signatures,
+     repository indexes, metrics, and structure prompts.
+   - Architec checks whether that snapshot is present, stale, or unknown.
+
+3. **Build architecture evidence**
+   - Architec runs static scanners for duplicated logic, shadow
+     implementations, import-boundary pressure, cleanup/archive candidates,
+     hotspots, topology pressure, and snapshot freshness.
+   - Incremental review keeps selected-change concerns separate from broader
+     project context so small diffs are not drowned by global noise.
+
+4. **Ask the LLM for interpretation**
+   - Architec sends compact evidence to llmgateway.
+   - llmgateway chooses the configured strong or weak model tier and owns all
+     provider credentials.
+
+5. **Write advisory output**
+   - Architec ranks concerns, keeps raw artifacts for inspection, and writes
+     human-readable plus machine-readable output under `.architec/`.
+   - The result is advice, not an automatic merge decision or proof of runtime
+     correctness.
+
+## Install
+
+Architec requires Python 3.11+.
+
+Recommended install from PyPI:
+
+```bash
+python3 -m pip install --user architec
+```
+
+This installs:
+
+- `archi`, the Architec CLI;
+- `seemseam-llmgateway`, the package that provides the LLM provider gateway;
+- `seemseam-hippos`, the package that provides Hippos structural snapshots.
+
+The runtime imports remain `llmgateway` and `hippos`; no separate package index
+setup is required.
+
+Local development from this repository:
+
+```bash
+python3 -m pip install -e .
+```
+
+## Configure LLM Access
+
+Architec gets all LLM access through **llmgateway**. Configure provider
+credentials and model tiers in:
+
+```text
+~/.llmgateway/config.yaml
+```
+
+Minimal example:
+
+```yaml
+version: 1
+provider:
+  provider_type: openai
+  api_style: openai_responses
+  base_url: https://your-llm-endpoint/v1
+  api_key: sk-...
+settings:
+  strong_model: your-strong-model
+  weak_model: your-fast-model
+```
+
+Architec consumes the configured `strong_model` and `weak_model` tiers. It does
+not store model-provider credentials itself.
+
+Check the installation and LLM route:
+
+```bash
+archi --check .
+```
+
+If the check reports missing LLM configuration, update
+`~/.llmgateway/config.yaml`.
+
+## Quick Start
+
+Review the current selected changes:
+
+```bash
+archi
+```
+
+Run whole-project architecture review:
+
+```bash
+archi --full
+```
+
+Save JSON output:
+
+```bash
+archi --out review.json
+archi --full --out full-review.json
+```
+
+Refresh Hippos inputs before full review:
+
+```bash
+archi --refresh-from-hippos --full
+```
+
+## Command Summary
+
+| Command | Purpose |
+| --- | --- |
+| `archi` | Incremental LLM architecture review for current selected changes. |
+| `archi --full` | Full-project LLM architecture review. |
+| `archi --out review.json` | Save incremental review JSON. |
+| `archi --full --out full-review.json` | Save full-review JSON. |
+| `archi --refresh-from-hippos --full` | Refresh Hippos structural inputs, then run full review. |
+| `archi --check .` | Validate Hippos bundle state and llmgateway configuration. |
+
+Advanced compatibility flags and older subcommands may still be accepted for
+existing automation, but new usage should prefer the commands above.
+
+## What Architec Reports
+
+Architec reports advisory concerns and signals, including:
+
+- **Duplication**: repeated logic and suspicious near-duplicates.
+- **Shadow implementations**: second implementations of similar behavior.
+- **Architecture contracts**: import-boundary or dependency-direction pressure.
+- **Cleanup/archive candidates**: stale or legacy-looking code and docs.
+- **Hotspots**: churn-heavy or structurally risky areas.
+- **Topology pressure**: flat or confusing project structure.
+- **Snapshot freshness**: missing, stale, or unknown Hippos context.
+- **Risk context**: optional external facts attached to existing concerns.
+
+The output is advisory. It is not a pass/fail result and is not proof of
+runtime correctness.
+
+## Outputs
+
+Architec writes generated files under `.architec/`:
+
+```text
+.architec/
+  architec-analysis.json
+  architec-summary.md
+  architec-viz.html
+  code-review-concerns.json
+  code-review-discovery.json
+  review-events.jsonl
+  cache/
+```
+
+Hippos writes structural inputs under `.hippos/`.
+
+Start with `.architec/architec-summary.md` for the human-readable report, then
+open `.architec/architec-analysis.json` for exact scores, concerns, signals,
+and artifact paths.
+
+## Agent Command Compatibility
+
+The commands above describe the current public workflow. Some older installed
+`archi` binaries may still show the previous command shape, where full review
+is `archi .` and incremental review is `archi --diff .`.
+
+Agents and automation should inspect the local binary before choosing commands:
+
+```bash
+archi --help
+```
+
+| Help output | Incremental review | Full review |
+| --- | --- | --- |
+| Includes `--full` | `archi` | `archi --full` |
+| Lacks `--full` but includes `--diff` | `archi --diff .` | `archi .` |
+
+## No Login Required
+
+Architecture analysis does not require `archi login`.
+
+Account commands such as `archi login`, `archi whoami --json`, and
+`archi devices --json` may exist for diagnostics, but they are not part of
+normal Architec analysis.
+
+## Development
+
+Run tests:
+
+```bash
+PYTHONPATH=src python3 -m pytest -q
+```
+
+Run Architec from this checkout:
+
+```bash
+PYTHONPATH=src python3 -m architec
+PYTHONPATH=src python3 -m architec --full
+```
+
+## More Documentation
+
+- [Usage manual](docs/usage-manual.md)
+- [Architecture stability notes](docs/advisory-review/topics/architecture-stability.md)
+- [Evidence model](docs/advisory-review/topics/evidence-model.md)

architec-0.2.11/README.md

@@ -0,0 +1,293 @@
+# Architec
+
+**Incremental architecture review for AI-assisted codebases.**
+
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![CLI](https://img.shields.io/badge/CLI-archi-222222)](#quick-start)
+[![Login](https://img.shields.io/badge/login-not_required-green)](#no-login-required)
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+Architec is an advisory architecture analysis CLI. It helps answer one
+practical question:
+
+> Will this change make the codebase harder to maintain?
+
+It reviews current changes by default, asks an LLM to interpret compact
+selected-scope evidence, and reports architecture risks such as duplicated
+logic, shadow implementations, unclear boundaries, stale structure, topology
+pressure, and risky hotspots.
+
+Architec does not make merge decisions and does not edit code. It gives
+structured advice for humans and coding agents to review.
+
+## Why Architec
+
+LLM-assisted development can move quickly, but architecture can drift quietly.
+Architec is designed to catch the kinds of issues that accumulate over time:
+
+- repeated implementations and "same idea twice" code;
+- compatibility paths that blur into canonical implementations;
+- changed files crossing intended module boundaries;
+- stale cleanup/archive candidates;
+- high-risk work landing in churn-heavy areas;
+- full-project topology pressure that is easy to miss during local edits.
+
+The default workflow is incremental-first:
+
+```bash
+archi
+```
+
+Use full review when you want the whole-project baseline:
+
+```bash
+archi --full
+```
+
+## How It Fits Together
+
+Architec is the review layer. It uses two companion components:
+
+| Component | Command / package | Role |
+| --- | --- | --- |
+| **Architec** | `archi` / `architec` | Runs architecture review, calls the LLM through llmgateway, writes advisory results under `.architec/`. |
+| **Hippos** | `hippos` / `seemseam-hippos` | Builds structural project snapshots under `.hippos/`: file manifests, code signatures, repository indexes, structure prompts, and metrics. |
+| **llmgateway** | `llmgateway` | Owns provider credentials, base URLs, API style, model names, and strong/weak model routing. |
+
+```text
+source tree + git changes
+        |
+        v
+Hippos structural snapshot  ->  .hippos/
+        |
+        v
+Architec evidence builder  ->  selected-scope or full-project context
+        |
+        v
+llmgateway LLM call        ->  strong / weak model tiers
+        |
+        v
+Architec review output     ->  .architec/
+```
+
+Day-to-day `archi` runs still use the LLM, but they avoid refreshing the whole
+Hippos snapshot unless requested. `archi --full` uses the Hippos snapshot more
+heavily, and `archi --refresh-from-hippos --full` refreshes it before review.
+
+## How It Works
+
+Architec combines deterministic code signals with LLM interpretation. The
+deterministic layer keeps the review grounded in concrete evidence; the LLM
+layer turns that evidence into readable architecture advice.
+
+1. **Select scope**
+   - `archi` reads the current git changes and focuses on changed files.
+   - `archi --full` reviews the whole project.
+
+2. **Read structural context**
+   - Hippos produces `.hippos/` snapshots: file manifests, code signatures,
+     repository indexes, metrics, and structure prompts.
+   - Architec checks whether that snapshot is present, stale, or unknown.
+
+3. **Build architecture evidence**
+   - Architec runs static scanners for duplicated logic, shadow
+     implementations, import-boundary pressure, cleanup/archive candidates,
+     hotspots, topology pressure, and snapshot freshness.
+   - Incremental review keeps selected-change concerns separate from broader
+     project context so small diffs are not drowned by global noise.
+
+4. **Ask the LLM for interpretation**
+   - Architec sends compact evidence to llmgateway.
+   - llmgateway chooses the configured strong or weak model tier and owns all
+     provider credentials.
+
+5. **Write advisory output**
+   - Architec ranks concerns, keeps raw artifacts for inspection, and writes
+     human-readable plus machine-readable output under `.architec/`.
+   - The result is advice, not an automatic merge decision or proof of runtime
+     correctness.
+
+## Install
+
+Architec requires Python 3.11+.
+
+Recommended install from PyPI:
+
+```bash
+python3 -m pip install --user architec
+```
+
+This installs:
+
+- `archi`, the Architec CLI;
+- `seemseam-llmgateway`, the package that provides the LLM provider gateway;
+- `seemseam-hippos`, the package that provides Hippos structural snapshots.
+
+The runtime imports remain `llmgateway` and `hippos`; no separate package index
+setup is required.
+
+Local development from this repository:
+
+```bash
+python3 -m pip install -e .
+```
+
+## Configure LLM Access
+
+Architec gets all LLM access through **llmgateway**. Configure provider
+credentials and model tiers in:
+
+```text
+~/.llmgateway/config.yaml
+```
+
+Minimal example:
+
+```yaml
+version: 1
+provider:
+  provider_type: openai
+  api_style: openai_responses
+  base_url: https://your-llm-endpoint/v1
+  api_key: sk-...
+settings:
+  strong_model: your-strong-model
+  weak_model: your-fast-model
+```
+
+Architec consumes the configured `strong_model` and `weak_model` tiers. It does
+not store model-provider credentials itself.
+
+Check the installation and LLM route:
+
+```bash
+archi --check .
+```
+
+If the check reports missing LLM configuration, update
+`~/.llmgateway/config.yaml`.
+
+## Quick Start
+
+Review the current selected changes:
+
+```bash
+archi
+```
+
+Run whole-project architecture review:
+
+```bash
+archi --full
+```
+
+Save JSON output:
+
+```bash
+archi --out review.json
+archi --full --out full-review.json
+```
+
+Refresh Hippos inputs before full review:
+
+```bash
+archi --refresh-from-hippos --full
+```
+
+## Command Summary
+
+| Command | Purpose |
+| --- | --- |
+| `archi` | Incremental LLM architecture review for current selected changes. |
+| `archi --full` | Full-project LLM architecture review. |
+| `archi --out review.json` | Save incremental review JSON. |
+| `archi --full --out full-review.json` | Save full-review JSON. |
+| `archi --refresh-from-hippos --full` | Refresh Hippos structural inputs, then run full review. |
+| `archi --check .` | Validate Hippos bundle state and llmgateway configuration. |
+
+Advanced compatibility flags and older subcommands may still be accepted for
+existing automation, but new usage should prefer the commands above.
+
+## What Architec Reports
+
+Architec reports advisory concerns and signals, including:
+
+- **Duplication**: repeated logic and suspicious near-duplicates.
+- **Shadow implementations**: second implementations of similar behavior.
+- **Architecture contracts**: import-boundary or dependency-direction pressure.
+- **Cleanup/archive candidates**: stale or legacy-looking code and docs.
+- **Hotspots**: churn-heavy or structurally risky areas.
+- **Topology pressure**: flat or confusing project structure.
+- **Snapshot freshness**: missing, stale, or unknown Hippos context.
+- **Risk context**: optional external facts attached to existing concerns.
+
+The output is advisory. It is not a pass/fail result and is not proof of
+runtime correctness.
+
+## Outputs
+
+Architec writes generated files under `.architec/`:
+
+```text
+.architec/
+  architec-analysis.json
+  architec-summary.md
+  architec-viz.html
+  code-review-concerns.json
+  code-review-discovery.json
+  review-events.jsonl
+  cache/
+```
+
+Hippos writes structural inputs under `.hippos/`.
+
+Start with `.architec/architec-summary.md` for the human-readable report, then
+open `.architec/architec-analysis.json` for exact scores, concerns, signals,
+and artifact paths.
+
+## Agent Command Compatibility
+
+The commands above describe the current public workflow. Some older installed
+`archi` binaries may still show the previous command shape, where full review
+is `archi .` and incremental review is `archi --diff .`.
+
+Agents and automation should inspect the local binary before choosing commands:
+
+```bash
+archi --help
+```
+
+| Help output | Incremental review | Full review |
+| --- | --- | --- |
+| Includes `--full` | `archi` | `archi --full` |
+| Lacks `--full` but includes `--diff` | `archi --diff .` | `archi .` |
+
+## No Login Required
+
+Architecture analysis does not require `archi login`.
+
+Account commands such as `archi login`, `archi whoami --json`, and
+`archi devices --json` may exist for diagnostics, but they are not part of
+normal Architec analysis.
+
+## Development
+
+Run tests:
+
+```bash
+PYTHONPATH=src python3 -m pytest -q
+```
+
+Run Architec from this checkout:
+
+```bash
+PYTHONPATH=src python3 -m architec
+PYTHONPATH=src python3 -m architec --full
+```
+
+## More Documentation
+
+- [Usage manual](docs/usage-manual.md)
+- [Architecture stability notes](docs/advisory-review/topics/architecture-stability.md)
+- [Evidence model](docs/advisory-review/topics/evidence-model.md)