Skip to content

Commit b3b7305

Browse files
HendlerHendler
committed
docs for embedding
1 parent 39c6b0c commit b3b7305

File tree

9 files changed

+1039
-14
lines changed

9 files changed

+1039
-14
lines changed

‎CHANGELOG.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@
5959
- [] github actions builder for linux varieties
6060

6161
### JACS core
62+
- [] a2a integration
6263
- [] ensure if a user wants standard logging they can use that
6364
- [] cli install instructions. a .sh command?
6465
- [] expose logging function to jacspy and jacsnpm
@@ -72,8 +73,8 @@
7273
- [] bucket integration
7374
- [] RBAC integration with header
7475
- [] clean io prepping for config of io
75-
- [] don't store "jacs_private_key_password": in config, don't display
76-
- [] minor feature - no_save = false should save document and still return json string instead of message on create document
76+
- [] don't store "jacs_private_key_password": in config, don't display
77+
- [] minor feature - no_save = false should save document and still return json string instead of message on create document
7778

7879
--------------------
7980

‎jacs/README.md‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,26 @@
11
# JACS: JSON Agent Communication Standard
22

3-
Welcome to **JACS (JSON Agent Communication Standard)**, a comprehensive framework for creating, signing, and verifying JSON documents with cryptographic integrity, designed specifically for AI agent communication and task management.
3+
**JACS (JSON Agent Communication Standard)**, is a framework for creating, signing, and verifying JSON documents with cryptographic integrity, designed specifically for AI agent identity, authentication, authorization, communication, and task management.
44

5-
## What is JACS?
5+
## Use cases
66

7-
JACS provides a standard way for AI agents to:
87
- **Create and sign** JSON documents with cryptographic signatures
9-
- **Verify authenticity** and integrity of documents
8+
- **Verify authenticity** and integrity of documents, requests, identities
109
- **Manage tasks and agreements** between multiple agents
11-
- **Maintain audit trails** of modifications and versioning
12-
- **Ensure trust** in multi-agent systems
10+
- **Maintain audit trails** with modifications and versioning
11+
- **Provide mutual opt-in identity and trust** in multi-agent systems
1312

14-
Perfect for building trustworthy AI systems where agents can securely exchange tasks, agreements, and data with verifiable integrity.
13+
## Features
1514

16-
## Key Features
15+
JACS provides middleware applicable to http, email, mpc (json-rpc), a2a,
1716

1817
- **Cryptographic Security**: RSA, Ed25519, and post-quantum algorithms
1918
- **JSON Schema Validation**: Enforced document structure
20-
- **Multi-Agent Agreements**: Built-in collaboration support
19+
- **Multi-Agent Agreements**: Formats that allow for multiple signatures
2120
- **Full Audit Trail**: Complete versioning and modification history
2221
- **Multiple Languages**: Rust, Node.js, and Python implementations
2322
- **MCP Integration**: Native Model Context Protocol support
24-
- **Production Ready**: Built-in observability and monitoring
23+
- **Observable**: Meta data available as OpenTelemetry
2524

2625
## About
2726

‎jacs/docs/jacsbook/book/print.html‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3188,6 +3188,244 @@ <h2 id="next-steps-5"><a class="header" href="#next-steps-5">Next Steps</a></h2>
31883188
<div style="break-before: page; page-break-before: always;"></div><h1 id="python-examples"><a class="header" href="#python-examples">Python Examples</a></h1>
31893189
<div style="break-before: page; page-break-before: always;"></div><h1 id="integration-examples"><a class="header" href="#integration-examples">Integration Examples</a></h1>
31903190
<div style="break-before: page; page-break-before: always;"></div><h1 id="cli-command-reference"><a class="header" href="#cli-command-reference">CLI Command Reference</a></h1>
3191+
<p>This page provides a comprehensive reference for all JACS command-line interface commands.</p>
3192+
<h2 id="global-commands"><a class="header" href="#global-commands">Global Commands</a></h2>
3193+
<h3 id="jacs-version"><a class="header" href="#jacs-version"><code>jacs version</code></a></h3>
3194+
<p>Prints version and build information for the JACS installation.</p>
3195+
<pre><code class="language-bash">jacs version
3196+
</code></pre>
3197+
<h3 id="jacs-init"><a class="header" href="#jacs-init"><code>jacs init</code></a></h3>
3198+
<p>Initialize JACS by creating both configuration and agent (with cryptographic keys). This is typically the first command run when setting up JACS.</p>
3199+
<pre><code class="language-bash">jacs init
3200+
</code></pre>
3201+
<h3 id="jacs-help"><a class="header" href="#jacs-help"><code>jacs help</code></a></h3>
3202+
<p>Print help information for JACS commands.</p>
3203+
<pre><code class="language-bash">jacs help [COMMAND]
3204+
</code></pre>
3205+
<h2 id="configuration-commands"><a class="header" href="#configuration-commands">Configuration Commands</a></h2>
3206+
<h3 id="jacs-config"><a class="header" href="#jacs-config"><code>jacs config</code></a></h3>
3207+
<p>Work with JACS configuration settings.</p>
3208+
<pre><code class="language-bash">jacs config [SUBCOMMAND]
3209+
</code></pre>
3210+
<p><em>Note: Specific subcommands for config are not detailed in the current help output.</em></p>
3211+
<h2 id="agent-commands"><a class="header" href="#agent-commands">Agent Commands</a></h2>
3212+
<h3 id="jacs-agent"><a class="header" href="#jacs-agent"><code>jacs agent</code></a></h3>
3213+
<p>Work with JACS agents - the cryptographic identities that sign and verify documents.</p>
3214+
<pre><code class="language-bash">jacs agent [SUBCOMMAND]
3215+
</code></pre>
3216+
<p><em>Note: Specific subcommands for agent management are not detailed in the current help output.</em></p>
3217+
<h2 id="task-commands"><a class="header" href="#task-commands">Task Commands</a></h2>
3218+
<h3 id="jacs-task"><a class="header" href="#jacs-task"><code>jacs task</code></a></h3>
3219+
<p>Work with JACS agent tasks - structured workflows between agents.</p>
3220+
<pre><code class="language-bash">jacs task [SUBCOMMAND]
3221+
</code></pre>
3222+
<p><em>Note: Specific subcommands for task management are not detailed in the current help output.</em></p>
3223+
<h2 id="document-commands"><a class="header" href="#document-commands">Document Commands</a></h2>
3224+
<p>The <code>jacs document</code> command provides comprehensive document management capabilities.</p>
3225+
<h3 id="jacs-document-create"><a class="header" href="#jacs-document-create"><code>jacs document create</code></a></h3>
3226+
<p>Create a new JACS document, either by embedding or parsing a document with optional file attachments.</p>
3227+
<p><strong>Usage:</strong></p>
3228+
<pre><code class="language-bash">jacs document create [OPTIONS]
3229+
</code></pre>
3230+
<p><strong>Options:</strong></p>
3231+
<ul>
3232+
<li><code>-a &lt;agent-file&gt;</code> - Path to the agent file. If not specified, uses config <code>jacs_agent_id_and_version</code></li>
3233+
<li><code>-f &lt;filename&gt;</code> - Path to input file. Must be JSON format</li>
3234+
<li><code>-o &lt;output&gt;</code> - Output filename for the created document</li>
3235+
<li><code>-d &lt;directory&gt;</code> - Path to directory of files. Files should end with <code>.json</code></li>
3236+
<li><code>-v, --verbose</code> - Enable verbose output</li>
3237+
<li><code>-n, --no-save</code> - Instead of saving files, print to stdout</li>
3238+
<li><code>-s, --schema &lt;schema&gt;</code> - Path to JSON schema file to use for validation</li>
3239+
<li><code>--attach &lt;attach&gt;</code> - Path to file or directory for file attachments</li>
3240+
<li><code>-e, --embed &lt;embed&gt;</code> - Embed documents or keep them external [possible values: true, false]</li>
3241+
<li><code>-h, --help</code> - Print help information</li>
3242+
</ul>
3243+
<p><strong>Examples:</strong></p>
3244+
<pre><code class="language-bash"># Create document from JSON file
3245+
jacs document create -f my-document.json
3246+
3247+
# Create document with embedded attachment
3248+
jacs document create -f document.json --attach ./image.jpg --embed true
3249+
3250+
# Create document with referenced attachment
3251+
jacs document create -f document.json --attach ./data.csv --embed false
3252+
3253+
# Create from directory of JSON files
3254+
jacs document create -d ./documents/
3255+
3256+
# Create with custom schema validation
3257+
jacs document create -f document.json -s custom-schema.json
3258+
3259+
# Print to stdout instead of saving
3260+
jacs document create -f document.json --no-save
3261+
</code></pre>
3262+
<h3 id="jacs-document-update"><a class="header" href="#jacs-document-update"><code>jacs document update</code></a></h3>
3263+
<p>Create a new version of an existing document. Requires both the original JACS file and the modified JACS metadata.</p>
3264+
<p><strong>Usage:</strong></p>
3265+
<pre><code class="language-bash">jacs document update [OPTIONS]
3266+
</code></pre>
3267+
<p><strong>Options:</strong></p>
3268+
<ul>
3269+
<li><code>-a &lt;agent-file&gt;</code> - Path to the agent file</li>
3270+
<li><code>-f &lt;filename&gt;</code> - Path to original document file</li>
3271+
<li><code>-n &lt;new-file&gt;</code> - Path to new/modified document file</li>
3272+
<li><code>-o &lt;output&gt;</code> - Output filename for updated document</li>
3273+
<li><code>-v, --verbose</code> - Enable verbose output</li>
3274+
<li><code>-n, --no-save</code> - Print to stdout instead of saving</li>
3275+
<li><code>-s, --schema &lt;schema&gt;</code> - Path to JSON schema file for validation</li>
3276+
<li><code>--attach &lt;attach&gt;</code> - Path to file or directory for additional attachments</li>
3277+
<li><code>-e, --embed &lt;embed&gt;</code> - Embed new attachments or keep them external</li>
3278+
<li><code>-h, --help</code> - Print help information</li>
3279+
</ul>
3280+
<p><strong>Example:</strong></p>
3281+
<pre><code class="language-bash"># Update document with new version
3282+
jacs document update -f original.json -n modified.json -o updated.json
3283+
3284+
# Update and add new attachments
3285+
jacs document update -f original.json -n modified.json --attach ./new-file.pdf --embed false
3286+
</code></pre>
3287+
<h3 id="jacs-document-verify"><a class="header" href="#jacs-document-verify"><code>jacs document verify</code></a></h3>
3288+
<p>Verify a document's hash, signatures, and schema compliance.</p>
3289+
<p><strong>Usage:</strong></p>
3290+
<pre><code class="language-bash">jacs document verify [OPTIONS]
3291+
</code></pre>
3292+
<p><strong>Options:</strong></p>
3293+
<ul>
3294+
<li><code>-a &lt;agent-file&gt;</code> - Path to the agent file</li>
3295+
<li><code>-f &lt;filename&gt;</code> - Path to input file. Must be JSON format</li>
3296+
<li><code>-d &lt;directory&gt;</code> - Path to directory of files. Files should end with <code>.json</code></li>
3297+
<li><code>-v, --verbose</code> - Enable verbose output</li>
3298+
<li><code>-s, --schema &lt;schema&gt;</code> - Path to JSON schema file to use for validation</li>
3299+
<li><code>-h, --help</code> - Print help information</li>
3300+
</ul>
3301+
<p><strong>Examples:</strong></p>
3302+
<pre><code class="language-bash"># Verify single document
3303+
jacs document verify -f signed-document.json
3304+
3305+
# Verify all documents in directory
3306+
jacs document verify -d ./documents/
3307+
3308+
# Verify with custom schema
3309+
jacs document verify -f document.json -s custom-schema.json
3310+
</code></pre>
3311+
<p><strong>Verification Process:</strong></p>
3312+
<ol>
3313+
<li><strong>Hash verification</strong> - Confirms document integrity</li>
3314+
<li><strong>Signature verification</strong> - Validates cryptographic signatures</li>
3315+
<li><strong>Schema validation</strong> - Ensures document structure compliance</li>
3316+
<li><strong>File integrity</strong> - Checks SHA256 checksums of attached files</li>
3317+
</ol>
3318+
<h3 id="jacs-document-extract"><a class="header" href="#jacs-document-extract"><code>jacs document extract</code></a></h3>
3319+
<p>Extract embedded file contents from documents back to the filesystem.</p>
3320+
<p><strong>Usage:</strong></p>
3321+
<pre><code class="language-bash">jacs document extract [OPTIONS]
3322+
</code></pre>
3323+
<p><strong>Options:</strong></p>
3324+
<ul>
3325+
<li><code>-a &lt;agent-file&gt;</code> - Path to the agent file</li>
3326+
<li><code>-f &lt;filename&gt;</code> - Path to input file containing embedded files</li>
3327+
<li><code>-d &lt;directory&gt;</code> - Path to directory of files to process</li>
3328+
<li><code>-s, --schema &lt;schema&gt;</code> - Path to JSON schema file for validation</li>
3329+
<li><code>-h, --help</code> - Print help information</li>
3330+
</ul>
3331+
<p><strong>Examples:</strong></p>
3332+
<pre><code class="language-bash"># Extract embedded files from single document
3333+
jacs document extract -f document-with-embedded-files.json
3334+
3335+
# Extract from all documents in directory
3336+
jacs document extract -d ./documents/
3337+
</code></pre>
3338+
<p><strong>Extract Process:</strong></p>
3339+
<ol>
3340+
<li>Reads embedded file contents from document</li>
3341+
<li>Decodes base64-encoded data</li>
3342+
<li>Writes files to their original paths</li>
3343+
<li>Creates backup of existing files (with timestamp)</li>
3344+
</ol>
3345+
<h3 id="agreement-commands"><a class="header" href="#agreement-commands">Agreement Commands</a></h3>
3346+
<p>JACS provides specialized commands for managing multi-agent agreements.</p>
3347+
<h4 id="jacs-document-check-agreement"><a class="header" href="#jacs-document-check-agreement"><code>jacs document check-agreement</code></a></h4>
3348+
<p>Given a document, provide a list of agents that should sign the document.</p>
3349+
<p><strong>Usage:</strong></p>
3350+
<pre><code class="language-bash">jacs document check-agreement [OPTIONS]
3351+
</code></pre>
3352+
<h4 id="jacs-document-create-agreement"><a class="header" href="#jacs-document-create-agreement"><code>jacs document create-agreement</code></a></h4>
3353+
<p>Create an agreement structure for a document that requires multiple agent signatures.</p>
3354+
<p><strong>Usage:</strong></p>
3355+
<pre><code class="language-bash">jacs document create-agreement [OPTIONS]
3356+
</code></pre>
3357+
<h4 id="jacs-document-sign-agreement"><a class="header" href="#jacs-document-sign-agreement"><code>jacs document sign-agreement</code></a></h4>
3358+
<p>Sign the agreement section of a document with the current agent's cryptographic signature.</p>
3359+
<p><strong>Usage:</strong></p>
3360+
<pre><code class="language-bash">jacs document sign-agreement [OPTIONS]
3361+
</code></pre>
3362+
<h2 id="common-patterns-1"><a class="header" href="#common-patterns-1">Common Patterns</a></h2>
3363+
<h3 id="basic-document-lifecycle"><a class="header" href="#basic-document-lifecycle">Basic Document Lifecycle</a></h3>
3364+
<pre><code class="language-bash"># 1. Initialize JACS
3365+
jacs init
3366+
3367+
# 2. Create document with attachments
3368+
jacs document create -f document.json --attach ./files/ --embed true
3369+
3370+
# 3. Verify document integrity
3371+
jacs document verify -f created-document.json
3372+
3373+
# 4. Update document if needed
3374+
jacs document update -f original.json -n modified.json
3375+
3376+
# 5. Extract embedded files when needed
3377+
jacs document extract -f document.json
3378+
</code></pre>
3379+
<h3 id="working-with-attachments"><a class="header" href="#working-with-attachments">Working with Attachments</a></h3>
3380+
<pre><code class="language-bash"># Embed small files for portability
3381+
jacs document create -f doc.json --attach ./small-image.png --embed true
3382+
3383+
# Reference large files to save space
3384+
jacs document create -f doc.json --attach ./large-video.mp4 --embed false
3385+
3386+
# Attach multiple files from directory
3387+
jacs document create -f doc.json --attach ./attachments/ --embed false
3388+
</code></pre>
3389+
<h3 id="schema-validation-workflow"><a class="header" href="#schema-validation-workflow">Schema Validation Workflow</a></h3>
3390+
<pre><code class="language-bash"># Create with schema validation
3391+
jacs document create -f document.json -s schema.json
3392+
3393+
# Verify against specific schema
3394+
jacs document verify -f document.json -s schema.json
3395+
</code></pre>
3396+
<h2 id="global-options"><a class="header" href="#global-options">Global Options</a></h2>
3397+
<p>Most commands support these common options:</p>
3398+
<ul>
3399+
<li><code>-h, --help</code> - Show help information</li>
3400+
<li><code>-v, --verbose</code> - Enable verbose output for debugging</li>
3401+
<li><code>-a &lt;agent-file&gt;</code> - Specify custom agent file (overrides config default)</li>
3402+
</ul>
3403+
<h2 id="exit-codes"><a class="header" href="#exit-codes">Exit Codes</a></h2>
3404+
<ul>
3405+
<li><code>0</code> - Success</li>
3406+
<li><code>1</code> - General error (invalid arguments, file not found, etc.)</li>
3407+
<li><code>2</code> - Verification failure (hash mismatch, invalid signature, etc.)</li>
3408+
<li><code>3</code> - Schema validation failure</li>
3409+
</ul>
3410+
<h2 id="environment-variables-2"><a class="header" href="#environment-variables-2">Environment Variables</a></h2>
3411+
<ul>
3412+
<li><code>JACS_CONFIG_PATH</code> - Override default configuration file location</li>
3413+
<li><code>JACS_DATA_DIR</code> - Override default data directory location</li>
3414+
<li><code>JACS_AGENT_FILE</code> - Default agent file to use (if not specified with <code>-a</code>)</li>
3415+
</ul>
3416+
<h2 id="file-formats"><a class="header" href="#file-formats">File Formats</a></h2>
3417+
<h3 id="input-files"><a class="header" href="#input-files">Input Files</a></h3>
3418+
<ul>
3419+
<li><strong>JSON documents</strong> - Must be valid JSON format</li>
3420+
<li><strong>Schema files</strong> - JSON Schema format (draft-07 compatible)</li>
3421+
<li><strong>Agent files</strong> - JACS agent format with cryptographic keys</li>
3422+
<li><strong>Attachments</strong> - Any file type (automatically detected MIME type)</li>
3423+
</ul>
3424+
<h3 id="output-files"><a class="header" href="#output-files">Output Files</a></h3>
3425+
<ul>
3426+
<li><strong>JACS documents</strong> - JSON format with JACS metadata, signatures, and checksums</li>
3427+
<li><strong>Extracted files</strong> - Original format of embedded attachments</li>
3428+
</ul>
31913429
<div style="break-before: page; page-break-before: always;"></div><h1 id="configuration-reference"><a class="header" href="#configuration-reference">Configuration Reference</a></h1>
31923430
<div style="break-before: page; page-break-before: always;"></div><h1 id="error-codes"><a class="header" href="#error-codes">Error Codes</a></h1>
31933431
<div style="break-before: page; page-break-before: always;"></div><h1 id="migration-guide"><a class="header" href="#migration-guide">Migration Guide</a></h1>

0 commit comments

Comments
 (0)