Primitive

A small, evidence-aware prototype for representing open-source software as reusable capabilities and implementation primitives.

The goal is not to build a giant crawler. It is to test whether a compact ontology can help an agent answer:

• What can this repository do?
• Which concrete portions expose reusable boundaries?
• What license and provenance evidence applies to each scope?
• Which capabilities, primitives, and patterns does it realize?
• Which other components provide the same reviewed capability?
• Which combinations are explicitly evidenced?
• Can a component be invoked, adapted, or extracted under a stated context?

V0 decision

The initial chain

PROJECT -> CAPABILITY -> PRIMITIVE / PATTERN -> REUSABLE COMPONENT

was challenged and rejected as a mandatory lifecycle. V0 instead separates:

1. software identity: project, repository, revision, component;
2. provider-neutral capability contracts;
3. implementation primitives and higher-order patterns;
4. evidence-backed claims;
5. contextual extraction assessments.

REUSABLE COMPONENT is a query projection, not an entity or boolean. Alternatives are derived from components realizing the same versioned capability. Tests are evidence artifacts, not capability entities. Licensing is always scoped and never treated as legal advice.

See docs/ontology-v0.md for the complete model and rationale.

Quick start

Requirements: Python 3, SQLite, and Git; no third-party Python packages.

# Build the generated example database from curated JSON bundles
python3 scripts/build_db.py

# Verify every source hash, line range, and exact excerpt against local Git clones
python3 scripts/audit_sources.py --output research/source-audit.json

# Run validation tests
python3 -m unittest discover -s tests -v

# Ask named agent-style questions
python3 scripts/query.py schema
python3 scripts/query.py capabilities --project github.com/duckdb/duckdb
python3 scripts/query.py alternatives --capability serve.openai-compatible-chat-api
python3 scripts/query.py primitives --project github.com/charmbracelet/bubbletea
python3 scripts/query.py licenses --project github.com/FFmpeg/FFmpeg
python3 scripts/query.py components --project github.com/BurntSushi/ripgrep
python3 scripts/query.py combinations --component component:openai-chat-adapter@1d66f63d5980204b7dcf8af8264fa9fbe373fea1
python3 scripts/query.py provenance --component COMPONENT_ID

Every response is JSON and includes claim basis, confidence, qualifiers, and immutable evidence links where applicable.

Corpus

The pilot uses ten blobless partial Git clones pinned to full commits. The corpus intentionally spans agent frameworks, local inference, UI, analytics, workflow orchestration, developer tools, multimedia, and browser 3D.

Category	Repository	Primary language	Pinned commit	Why it is useful
Agents	openai/swarm	Python	6af0b4caf37d	Small agent/tool/handoff implementation; useful educational contrast
Agents	pydantic/pydantic-ai	Python	1d66f63d5980	Typed tools, model adapters, and graph-based agent execution
Inference	ggml-org/llama.cpp	C/C++	6e60f35608ec	Library/server split, GGUF, quantized local inference, compatibility API
Inference	ollama/ollama	Go/C	b9cd4b1efbbf	Local model lifecycle, server process, compatibility surface
UI	charmbracelet/bubbletea	Go	657aaae216e3	Clear model/update/view boundary, event loop, commands, tests
Data	duckdb/duckdb	C++	94d7b6407250	Embedded SQL engine plus loadable extension ABI
Orchestration	PrefectHQ/prefect	Python	148e99781fb0	Durable flows, tasks, retries, work pools, workers
Developer tools	BurntSushi/ripgrep	Rust	3fce3b5bb023	Executable assembled from independently consumable crates
Multimedia	FFmpeg/FFmpeg	C	741ad687196d	Library/CLI boundaries and conditional LGPL/GPL build scope
3D	mrdoob/three.js	JavaScript	eac578d04f74	Browser renderer, scene graph, asset loaders, independent asset licenses

The pilot database currently contains 10 projects/repositories/revisions, 48 concrete components, 46 versioned concepts, 215 immutable source artifacts, 231 claims, and 720 evidence links. The source audit verifies every stored excerpt against Git.

The clones under .cache/ are ignored. The deliverable is the pinned source metadata, exact excerpts, claims, and generated database—not a vendored copy of the repositories.

What is stored

Identity

• logical project;
• hosted repository;
• immutable Git revision;
• revision-scoped source region, package module, service, executable, or distribution.

Normalized concepts

• versioned capability contract;
• small reusable primitive;
• higher-order architectural/integration pattern;
• SPDX license reference.

Claims

Eleven controlled, evidence-backed predicates answer capability, primitive/pattern, dependency, packaging, license, interoperability, lineage, entry-point, and extraction questions. Claims are typed and qualified rather than arbitrary key-value tags.

Evidence

A source is pinned by:

full commit + path + Git blob OID + complete-file SHA-256

An evidence link adds an exact line range and short verbatim excerpt. scripts/audit_sources.py verifies these against Git. A cited test_definition proves the test source exists; V0 does not claim that the test ran or passed.

Capability vocabulary

The catalog in schema/vocabulary.json uses composable action/object contracts rather than product names. Initial examples include:

• execute.tool-calling-agent-loop
• route.tasks-between-agents
• compose.agent-execution-graphs
• generate.text-from-local-llm
• serve.openai-compatible-chat-api
• load.gguf-model-files
• provision.local-model-runtime
• render.event-driven-terminal-ui
• execute.sql-over-local-analytics-data
• extend.query-engine-with-loadable-modules
• orchestrate.durable-python-workflows
• execute.tasks-on-configurable-workers
• search.file-content-from-command-line
• compose.regex-search-pipeline
• decode.audio-video-media
• transcode.media-with-command-line
• render.webgl-3d-scene
• load.3d-assets-in-browser

A capability is not merged because two README headings or embeddings look similar. Matching follows action, inputs/outputs, effects, hard qualifiers, and guarantees.

Worked combination

The corpus contains one explicit cross-repository composition:

Pydantic AI OpenAI chat adapter
  -> OpenAI Chat Completions subset
  -> Ollama local HTTP service

Both sides are independently evidenced at pinned commits. The combined claim is inferred, medium confidence, and conditional on endpoint/model configuration. Ollama documents partial OpenAI API support, and V0 did not run an end-to-end cross-repository test. Query it with:

python3 scripts/query.py combinations \
  --component component:openai-chat-adapter@1d66f63d5980204b7dcf8af8264fa9fbe373fea1

Reuse and extraction answers

V0 does not return safe: true. It returns a contextual assessment with:

• reuse mode (invoke, import, embed, wrap_service, adapt, extract_source, copy_and_adapt);
• target context;
• verdict (direct, adapt, reference_only, blocked, unknown);
• interface, coupling, dependency, build, state, side-effect, test, compatibility, license, provenance, and security dimensions;
• effort, risk, conditions, and unknowns.

Confidence, technical risk, license scope, and policy/legal review remain independent.

Storage layout

schema/
  ontology.json              controlled model rules
  vocabulary.json            capability/primitive/pattern/license catalog
  ingestion.schema.json      JSON bundle schema
  schema.sql                 SQLite DDL and agent-facing views
data/imports/                one curated bundle per repository
scripts/
  build_db.py                strict JSON -> SQLite compiler
  query.py                   named JSON query CLI
  source_record.py           create/verify one source record
  normalize_source_regions.py expand cited source-region locators safely
  normalize_identities.py    normalize repository/revision canonical keys
  audit_sources.py           verify all cited Git objects and excerpts
examples/queries.sql         transparent SQL examples
research/reader-protocol.md  corpus-reader rules
research/source-audit.json    generated Git hash/excerpt audit
research/source-region-migration.json  locator normalization record
research/identity-migration.json       canonical identity normalization record
docs/primitive-v0-report.html  self-contained visual field report
build/knowledge.sqlite       generated example database

Method and limitations

• This is a manually curated V0, not automated repository comprehension.
• No embeddings, vector database, SBOM, transitive resolver, or full component graph is included.
• Source inspection is not runtime verification.
• A shared capability does not imply drop-in interchangeability.
• A root license does not automatically cover dependencies, generated files, vendored code, examples, fonts, models, or media.
• Extraction assessments are research triage, not legal advice.
• Coverage means “an indexed claim exists,” not “the repository cannot do something else.”
• Mutable HEAD, branches, tags, popularity, and project-health scores are not timeless knowledge.

Further reading

• docs/ontology-v0.md — concepts, claims, alternatives, combinations, extraction
• docs/mission-traceability.md — each mission question mapped to its answer path
• docs/design-process.md — independent schema teams, disagreements, and critic corrections
• docs/concept-decisions.md — what was merged, removed, or kept distinct
• docs/provenance-and-dedup.md — source/assertion provenance and normalization
• docs/evidence-example.md — a real reported-vs-observed capability claim with pinned citations
• docs/database-design.md — SQLite tables, constraints, indexes, and answer views
• docs/ingestion.md — bundle format and validation rules
• docs/agent-queries.md — worked agent question shapes
• docs/primitive-v0-report.html — self-contained visual field report
• examples/queries.sql — SQL answer paths
• research/reader-protocol.md — evidence and curation protocol