From 868f655d1bea7b471471197985ee7b567c34caf8 Mon Sep 17 00:00:00 2001 From: LarytheLord Date: Wed, 1 Apr 2026 13:31:12 +0530 Subject: [PATCH] Add agent infrastructure documentation --- CLAUDE.md | 3 ++ Infrastructure/README.md | 97 ++++++++++++++++++++++++++++++++++++++++ README.md | 5 +++ 3 files changed, 105 insertions(+) create mode 100644 Infrastructure/README.md diff --git a/CLAUDE.md b/CLAUDE.md index 1420805..514e973 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,6 +9,7 @@ No build step -- this is a pure documentation repo. Browse by topic: - **Vector database (Weaviate):** `Knowledge/README.md` - **Prediction models:** `Predictions/README.md` - **Language models (8B):** `Generation/README.md` +- **Agent infrastructure:** `Infrastructure/README.md` - **n8n workflow automations:** `Automation/README.md` ## Architecture @@ -17,6 +18,7 @@ No build step -- this is a pure documentation repo. Browse by topic: Knowledge/ Weaviate vector-graph database docs (connection, search, RAG, schema) Predictions/ HuggingFace text regression models (performance + preference prediction) Generation/ 8B language models (Llama 3.1 base, continual pre-training + instruct) +Infrastructure/ Clean-room agent runtime, orchestration, and tool-safety patterns Automation/ n8n workflow templates for advocacy automation .github/ Dependabot config + CI workflows ``` @@ -28,6 +30,7 @@ Automation/ n8n workflow templates for advocacy automation | `Knowledge/README.md` | Weaviate connection details, search ops, RAG patterns, Content schema | | `Predictions/README.md` | Prediction model usage, batch processing, score clipping | | `Generation/README.md` | 8B model usage, generation parameters, known limitations | +| `Infrastructure/README.md` | Clean-room agent runtime roadmap across scanner, platform, and tooling repos | | `Automation/README.md` | n8n hosting options, workflow import, activation | | `.gitleaksignore` | Secret scanning exclusions (read-only API keys in docs) | diff --git a/Infrastructure/README.md b/Infrastructure/README.md new file mode 100644 index 0000000..55561cd --- /dev/null +++ b/Infrastructure/README.md @@ -0,0 +1,97 @@ +# Clean-Room Agent Infrastructure + +This guide describes how Open Paws can adopt stronger agent-runtime patterns without copying proprietary implementations. The goal is to reuse the ideas that are broadly useful, then implement them from scratch in our own systems, data models, and interfaces. + +## Core Principles + +1. Build from patterns, not copied code +2. Keep sensitive workflows explicit and reviewable +3. Centralize tool definitions, permissions, and metadata +4. Separate long-running orchestration from user-facing chat +5. Preserve source provenance for scanner findings, quests, and automations + +## Shared Runtime Pattern + +The target shape across Open Paws projects is: + +1. **Scanner and external signal ingestion** +2. **Structured export and normalization** +3. **Platform-side task, quest, and conversation orchestration** +4. **Tool registry with sensitivity-aware UI and routing** +5. **Human review and approval before high-impact actions** + +This keeps research, execution, and user interfaces aligned while still letting each repo own a clear slice of the system. + +## Current Implementation Tracks + +### `Open-Paws/project-compassionate-code` + +The scanner is the best place to normalize repository findings into a stable export format. That export should include: + +- deterministic finding identifiers +- repository provenance +- merge-tier or effort metadata +- stable payloads that downstream systems can ingest without re-parsing scanner output + +This repo should continue to act as the source of truth for machine-readable contribution opportunities. + +### `Open-Paws/open-paws-platform` + +The platform should own guild-facing orchestration and persistent state. Current and near-term responsibilities include: + +- ingesting scanner findings into draft guild quests +- storing quest source provenance +- supporting dry-run previews before import +- acting as the eventual home for cleaner plan, task, and background-session orchestration + +This is the right layer for approval boundaries, operator controls, and durable workflow state. + +### `LarytheLord/Open-Paws-Tools-Platform` + +The tools platform is the right sandbox for experimenting with more agentic UX before it is promoted into production systems. The first clean-room pattern to establish here is a central tool registry that can drive: + +- quick actions +- intent detection +- sensitivity labels +- future approval prompts +- future policy hooks for restricted workflows + +This keeps the UI and runtime metadata from drifting apart as more tools are added. + +## Recommended Next Steps + +### Layer 1: Shared Definitions + +- standardize tool metadata fields across repos +- align sensitivity levels for public, medium-risk, and high-risk workflows +- document a shared scanner export contract + +### Layer 2: Orchestration + +- add explicit background-task lifecycle states +- separate draft generation from action execution +- add review checkpoints before external writes or sensitive research flows + +### Layer 3: Operator Experience + +- show sensitivity cues directly in the UI +- make provenance visible for imported quests and generated tasks +- support dry-run previews wherever automation can create records or tasks + +## Safety Boundaries + +Open Paws should not copy source files, prompts, comments, or proprietary internal naming from third-party leaked codebases. Safe reuse means: + +- extracting product patterns +- rewriting implementations from scratch +- documenting trust boundaries +- validating that sensitive workflows have clear operator review paths + +## Success Criteria + +This infrastructure direction is working when: + +1. scanner findings move into the guild pipeline with stable provenance +2. tooling interfaces share one source of truth for intent and risk metadata +3. higher-sensitivity actions are visible, reviewable, and easier to gate +4. repo-specific experimentation can graduate into the platform without rewriting the architecture each time diff --git a/README.md b/README.md index b3dc22e..e595920 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,11 @@ Documentation for our specialized generative AI models: - [Overview & Quick Start](Generation/README.md) +### 🧠 Agent Infrastructure +Documentation for clean-room agent runtime, orchestration, and tool-safety patterns across Open Paws projects: + +- [Overview & Quick Start](Infrastructure/README.md) + ### 🤖 n8n Workflow Automations Documentation and example workflows using n8n to automate advocacy tasks.