Artifact¶
artifact
¶
Artifact model — the object of agent collaboration.
An artifact is a versioned shared work product that agents operate on. Artifacts are the source of truth for all shared state in a society — agents don't pass state directly; everything flows through artifacts.
In v0.1, artifacts are in-memory only (StringArtifact, JsonArtifact). External artifacts (GitHubPR, CodeFile) are deferred to v0.2+.
Example::
from claw.artifact import Artifact, StringArtifact, JsonArtifact
# Lightweight reference for edge declarations
spec = Artifact(name="task-spec")
# Concrete in-memory artifacts for runtime
doc = StringArtifact("design-doc")
v1 = doc.write("# Design\nFirst draft.", agent="writer")
print(doc.read(budget=100))
Version
¶
Bases: BaseModel
A specific version of an artifact.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
Unique version identifier. |
required | |
author
|
Name of the agent that created this version. |
required | |
timestamp
|
When this version was created. |
required | |
content_hash
|
Hash of the content at this version. |
required |
ArtifactProtocol
¶
Bases: Protocol
Protocol defining the interface all artifact types must implement.
Artifact types provide versioned read/write access to shared state.
The read(budget) method supports context budget management —
content is truncated or summarized to fit within the token budget.
name
property
¶
Unique identifier for this artifact.
read(budget)
¶
Load content within a token budget.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
budget
|
int
|
Maximum number of tokens to return. |
required |
Returns:
| Type | Description |
|---|---|
str
|
Content truncated or summarized to fit within budget. |
write(content, agent)
¶
Mutate the artifact content.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
content
|
str
|
New content to write. |
required |
agent
|
str
|
Name of the agent performing the write. |
required |
Returns:
| Type | Description |
|---|---|
Version
|
The new Version created by this write. |
diff(v1, v2)
¶
version()
¶
Return the current version, or None if never written.
Artifact
¶
Bases: BaseModel
Metadata for an artifact declaration in a society graph.
This is the lightweight reference used in edge type declarations. Concrete artifact implementations (StringArtifact, JsonArtifact) are created at runtime and registered in the ArtifactStore.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
Unique identifier for the artifact. |
required | |
description
|
Human-readable description of the artifact's purpose. |
required |
Tokenizer
¶
CharApproxTokenizer
¶
Approximate tokenizer: 1 token ~ 4 characters.
Good enough for v0.1 budget management. Swap with a tiktoken-based tokenizer for production accuracy.
StringArtifact(name, *, tokenizer=None)
¶
In-memory string artifact with version history and budget-aware reads.
Satisfies :class:ArtifactProtocol.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Unique artifact identifier. |
required |
tokenizer
|
Tokenizer | None
|
Token counter/truncator. Defaults to CharApproxTokenizer. |
None
|
history
property
¶
All versions in chronological order.
JsonArtifact(name, *, schema=None, tokenizer=None)
¶
In-memory JSON artifact with RFC 7386 merge-patch and version history.
Each write() parses the content as JSON, merges it into the current
state using JSON Merge Patch semantics, and optionally validates the
result against a JSON Schema (basic structural checks in v0.1).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Unique artifact identifier. |
required |
schema
|
dict[str, Any] | None
|
Optional JSON Schema dict for write validation. |
None
|
tokenizer
|
Tokenizer | None
|
Token counter/truncator. Defaults to CharApproxTokenizer. |
None
|
history
property
¶
All versions in chronological order.