# @reneza/ats-core

> **Agent-side retrieval that fans out every available retriever in parallel and votes on the result.** Core always provides ranked keyword search, adds adapter-native search when available, and adds dense+sparse hybrid retrieval when the adapter supplies embeddings. The merged top-K includes `sources: [...]` provenance.

The adapter-agnostic core of [Agentic Task System](https://github.com/renezander030/agentic-task-system) — an agent-native context layer over the task app you already use, with pluggable storage adapters.

## Why this exists

Pure semantic search (nomic-embed via qdrant) underweights short titles — a doc titled simply `ffmpeg` doesn't surface for "ffmpeg commands". Pure keyword search misses paraphrased queries. **Hybrid retrieval fused via Reciprocal Rank Fusion gets you 60% top-1 / 80% recall@5 on agent-issued queries** versus 20% / 40% for dense alone (n=5 micro-bench, see repo).

Built for agents that read top-K, not humans that read top-1.

## Install

```bash
npm install @reneza/ats-core
```

You'll typically pair it with a storage adapter — see [`@reneza/ats-adapter-ticktick`](https://npmjs.com/package/@reneza/ats-adapter-ticktick) for the reference implementation, or write your own adapter against the [6-method interface](https://github.com/renezander030/agentic-task-system/blob/main/docs/adapter-interface.md).

## What you get

- **Parallel retrieval** — fan-out + RRF fusion, deadline-bounded, provenance-tagged results
- **Corpus cache** — disk-backed, 5-min TTL; warm calls avoid remote corpus fetches
- **Usage logger** — instrumented retrieval calls write JSONL for later analysis
- **Bench harness** — Q/A pairs you author, scored by hit@1 / recall@5 / MRR per tag bucket
- **Adapter interface + validator** — JSDoc types for the contract every storage adapter implements
- **Portable execution context** — intent, exploration promotion, hierarchy/conflict evaluation, lifecycle validity, typed relationships, graph traversal, and context assembly in task bodies
- **Action ledger** — append-only JSONL records of agent actions, sources, approvals, output, and advancement
- **Scoped security decisions** — default-deny trust/action/resource policy with approval checks and mandatory allow/deny auditing
- **Task event stream** — deterministic corpus diffs with stable IDs, atomic content-free checkpoints, and no autonomous execution
- **Workflow-progress benchmark** — separate advancement, context waste, blocker, completion, reopen, and correction metrics over disclosure-safe episode records

## Quick example

```js
import { validateAdapter } from '@reneza/ats-core';
import adapter from '@reneza/ats-adapter-ticktick';

validateAdapter(adapter);
// adapter is now ready to plug into core.find / core.get / core.url
```

See the [agent execution layer](https://github.com/renezander030/agentic-task-system/blob/main/docs/agent-layer.md). Run `npm run prove:intent`, `npm run prove:beads`, and `npm run prove:progress` in the repository for synthetic end-to-end proofs.

## Adapter contract (six methods, three optional)

```ts
interface KnowledgeAdapter {
  listProjects(): Promise<Project[]>
  listTasksInProject(projectId: string): Promise<Task[]>
  getTask(projectId: string, taskId: string): Promise<Task>
  createTask(input: TaskInput): Promise<Task>
  updateTask(projectId: string, taskId: string, patch: TaskPatch): Promise<Task>
  urlFor(ref: { projectId: string, taskId: string }): string

  // Optional — core uses if present, falls back if not:
  searchByQuery?(query: string): Promise<Task[]>
  bulkFetch?(): Promise<Task[]>
  embeddings?(texts: string[]): Promise<number[][]>
}
```

Full spec at [docs/adapter-interface.md](https://github.com/renezander030/agentic-task-system/blob/main/docs/adapter-interface.md).

## Repo + docs

- **Repo**: https://github.com/renezander030/agentic-task-system
- **Adapter interface**: https://github.com/renezander030/agentic-task-system/blob/main/docs/adapter-interface.md

## License

MIT
