Metadata-Version: 2.4
Name: xrefkit
Version: 0.6.2
Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
Author: synthaicode
License: MIT License
        
        Copyright (c) 2026 Ritu
        
        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.
        
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML<7,>=6.0.2
Requires-Dist: pydantic<3,>=2.0
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0.0; extra == "mcp"
Requires-Dist: uvicorn>=0.30; extra == "mcp"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Dynamic: license-file

# XRefKit

XRefKit is a framework for making AI-assisted work repeatable, reviewable, and
handoff-ready.

It helps teams structure domain procedures and knowledge so that work can
record evidence, preserve human judgment, and apply explicit completion checks.

## Why XRefKit?

Experimental local tool: [Attention Pet](projects/attention-pet/README.en.md) helps
people assess capability sufficiency and lower inference-cost candidates separately.
Its Model Fit / Cost Fit estimates use uncalibrated profiles; it does not measure internal
attention or switch models automatically.

### Codex-only preview: Attention Pet

Attention Pet is a small local companion for Codex work. It reads the current
Codex chat's local session record, estimates whether the selected model meets
the visible work requirements, and shows the result through a compact animated
pet. It also shows lower inference-cost comparison candidates when the
experimental profiles support one. The estimate is observational and does not
change the Codex model, reasoning level, or chat.

It does not measure token usage. It estimates the structural complexity of the
work context the AI must handle, including retained items, dependencies,
constraints, decision depth, conflicts, and dispersed evidence. It does not
read model-internal attention or remaining context-window capacity.

Run it from a Codex terminal in this repository so `CODEX_THREAD_ID` identifies
the current chat:

```powershell
python -m xrefkit.attention_pet serve --port 8769
```

Open the printed `http://127.0.0.1:8769/` address in the Codex browser panel.
The display follows the browser's preferred language: Japanese is used for a
Japanese preference, with English as the fallback. Stop the process with
Ctrl+C.

This Codex preview is bound to the chat that launched it. Selecting another
chat does not move the Pet automatically; launch it again from that chat when
you want a separate view. The model and reasoning dropdowns only compare
estimates and do not change the active Codex settings. See the
[Attention Pet guide](projects/attention-pet/README.en.md) for interpretation,
limitations, client integration, and API details.

Using AI for real work creates recurring operating problems:

![Why XRefKit is needed](human-docs/en/assets/why_xrefkit_needed/whatis_xrefkit.png)

- the AI can act from incomplete context or unsupported guesses
- procedures, domain facts, and judgment criteria get mixed together in prompts
- execution, checking, and handoff collapse into one opaque step
- work becomes hard to continue across agents, humans, or sessions
- outputs may lack evidence, closure discipline, or auditability

XRefKit provides a repository and runtime model for addressing these problems.

## What it provides

- **Skills** — reusable procedures expressed as SkillDefinitions
- **Knowledge** — source-backed domain facts and local rules resolved by XID
  when a Skill run needs them
- **Workflow protocol** — recorded progress, deterministic workflow-record
  verification, and closure checks
- **Evidence and handoffs** — outputs, judgments, concerns, and decisions that
  remain reviewable after the work is done
- **Skill Run Dashboard** — inspect recorded Skill execution state, definition
  identity, runtime binding, referenced XIDs, evidence, judgments, concerns,
  and handoffs
- **XIDs** — stable references for connecting procedures, knowledge, and
  supporting documents

The package includes the resolver, Skill runtime, workflow controls, client
tools, and an optional MCP adapter.

Current Skill authoring targets the one-document `skill_definition_v1` format.
Existing `legacy_split_v1` Skills and unversioned historical run logs remain
readable during migration. The [Workflow Runtime Binding](docs/core/contracts/111_workflow_runtime_binding.md#xid-8D50A972BA9F)
defines how instruction-derived `capability`, `tuning`, `responsibility`, and
`execution_mode` are captured; these are not fixed SkillDefinition properties.
Knowledge used by a Skill remains separate and is resolved from the XID catalog
when needed.

The [Skill Run Dashboard](docs/guides/086_skill_run_observation_dashboard_usage.md#xid-4A4763A2DE63)
helps people inspect recorded XID retrieval and use together with the run's
evidence before a human accepts or hands off the result. The Dashboard reports
recorded state and missing observations; it does not accept output quality.

## Quick start

XRefKit requires Python 3.11 or later.

```powershell
python -m pip install xrefkit
xrefkit init
xrefkit --help
```

For local development:

```powershell
python -m pip install -e .
xrefkit init
```

For the optional MCP server:

```powershell
python -m pip install "xrefkit[mcp]"
xrefkit mcp serve --repo . --transport stdio
```

This command starts the optional catalog and runtime MCP adapter. This checkout
does not implement management upload, staging, sealing, review, or adoption of
uploaded SkillDefinition bytes into the active catalog.

To connect VS Code/Copilot, run from your target workspace:

```powershell
python -m pip install "xrefkit[mcp]"
python -m xrefkit mcp setup --repo . --output .xrefkit/setup-review
python -m xrefkit mcp setup apply --repo . --source .xrefkit/setup-review
```

Review the generated files before applying them, open the workspace in VS Code,
and start the `xrefkit` MCP server. In Copilot chat, ask: "Call XRefKit's
get_startup_context and help me get started." The AI receives any needed legacy
migration guidance; you can describe your goal without specifying Skill names.
Opening VS Code alone does not guarantee an AI conversation starts.

## Where to go next

- [Install XRefKit and register Skill Packages](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90)
- [Understand the workflow protocol](docs/guides/087_workflow_protocol_sequence_for_humans.md#xid-E8B4D2F19A63)
- [Use an instruction-backed workflow](docs/guides/088_instruction_workflow_protocol.md#xid-9F4C2A7D1B60)
- [Understand Skills and Knowledge](docs/core/models/052_flow_capability_skill_knowledge_model.md#xid-91C4B7E2D5A8)
- [Read the SkillDefinition v1 contract](docs/core/contracts/096_skill_definition_contract.md#xid-E6A19D4B72C3)
- [Author a Skill with xref](docs/guides/013_skill_authoring_with_xref.md#xid-3DB05A0F5F5B)
- [Browse the complete documentation index](docs/000_index.md#xid-56DD6EB68343)

## Security

XRefKit does not require provider API keys to explore or install the package.
Do not commit secrets, API keys, access tokens, `.env` files, or provider
credentials. Authenticate external AI tools through their official provider
mechanisms.

## Repository Skill adoption and scoped source-analysis knowledge

This repository uses the audited canonical Skill sources listed in
`skills/repository_adoption.json`. Legacy source identities remain aliases;
external legacy split Skills and YAML Skill Packages remain supported. See
[SkillDefinition adoption](docs/core/contracts/096_skill_definition_contract.md#xid-E6A19D4B72C3).
The source-analysis common XID remains stable and routes coherent criteria
fragments on demand. Narrow tasks avoid unrelated bodies; full reviews retain
every required axis. No similarity-based knowledge merge or deletion occurs.
