archivebox-api 0.34.0__tar.gz → 2.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- archivebox_api-2.5.0/.pre-commit-config.yaml +165 -0
- archivebox_api-2.5.0/AGENTS.md +294 -0
- archivebox_api-2.5.0/CHANGELOG.md +36 -0
- archivebox_api-2.5.0/CLAUDE.md +9 -0
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/LICENSE +1 -1
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/MANIFEST.in +1 -1
- archivebox_api-2.5.0/PKG-INFO +510 -0
- archivebox_api-2.5.0/README.md +483 -0
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api/__init__.py +34 -22
- archivebox_api-2.5.0/archivebox_api/__main__.py +4 -0
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api/api/api_client_auth.py +1 -3
- archivebox_api-2.5.0/archivebox_api/api/api_client_base.py +82 -0
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api/api/api_client_cli.py +2 -7
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api/api/api_client_core.py +2 -9
- archivebox_api-2.5.0/archivebox_api/auth.py +33 -0
- archivebox_api-2.5.0/archivebox_api/connector_manifest.yml +172 -0
- archivebox_api-2.5.0/archivebox_api/connectors/__init__.py +0 -0
- archivebox_api-2.5.0/archivebox_api/connectors/mcp_source_presets.json +18 -0
- archivebox_api-2.5.0/archivebox_api/connectors/tool_schema_fingerprints.json +8 -0
- archivebox_api-2.5.0/archivebox_api/kg_ingest.py +433 -0
- archivebox_api-2.5.0/archivebox_api/mcp_config.json +28 -0
- archivebox_api-2.5.0/archivebox_api/mcp_server.py +432 -0
- archivebox_api-2.5.0/archivebox_api/ontology/__init__.py +7 -0
- archivebox_api-2.5.0/archivebox_api/ontology/archivebox.ttl +99 -0
- archivebox_api-2.5.0/archivebox_api/ontology/certification.json +36 -0
- archivebox_api-2.5.0/archivebox_api/ontology/fixtures/records.json +21 -0
- archivebox_api-2.5.0/archivebox_api/ontology/mappings/source.yaml +20 -0
- archivebox_api-2.5.0/archivebox_api/ontology/migrations/manifest.json +6 -0
- archivebox_api-2.5.0/archivebox_api/ontology/shapes/connector.shacl.ttl +44 -0
- archivebox_api-2.5.0/archivebox_api/prompts/__init__.py +0 -0
- archivebox_api-2.5.0/archivebox_api/prompts/web_archivist_specialist.json +43 -0
- archivebox_api-2.5.0/archivebox_api/skills/__init__.py +0 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-api-operations/SKILL.md +33 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-api-operations/agents/openai.yaml +4 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-api-operations/references/catalog.md +7 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-kg-ingestion/SKILL.md +91 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-kg-ingestion/WORKFLOW.md +77 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-snapshot-search/SKILL.md +94 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-snapshot-search/WORKFLOW.md +80 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-web-archiving/SKILL.md +96 -0
- archivebox_api-2.5.0/archivebox_api/skills/archivebox-web-archiving/WORKFLOW.md +82 -0
- archivebox_api-2.5.0/archivebox_api/web_source.py +281 -0
- archivebox_api-2.5.0/archivebox_api/web_source_contract.py +199 -0
- archivebox_api-2.5.0/archivebox_api.egg-info/PKG-INFO +510 -0
- archivebox_api-2.5.0/archivebox_api.egg-info/SOURCES.txt +69 -0
- archivebox_api-2.5.0/archivebox_api.egg-info/entry_points.txt +14 -0
- archivebox_api-2.5.0/archivebox_api.egg-info/requires.txt +14 -0
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api.egg-info/top_level.txt +3 -0
- archivebox_api-2.5.0/connector_manifest.yml +172 -0
- archivebox_api-2.5.0/mkdocs.yml +95 -0
- archivebox_api-2.5.0/opencode.json +18 -0
- archivebox_api-2.5.0/pyproject.toml +80 -0
- archivebox_api-2.5.0/release-readiness.json +16811 -0
- archivebox_api-2.5.0/requirements.txt +1 -0
- archivebox_api-2.5.0/scripts/security_sanitizer.py +318 -0
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/scripts/verify_api_integration.py +153 -112
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/tests/conftest.py +2 -2
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/tests/test_action_discovery.py +2 -2
- archivebox_api-2.5.0/tests/test_archivebox_api_brute_force_coverage.py +166 -0
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/tests/test_archivebox_coverage.py +63 -65
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/tests/test_archivebox_coverage_extra.py +75 -187
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/tests/test_basic.py +4 -7
- archivebox_api-2.5.0/tests/test_conformance.py +159 -0
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/tests/test_init_dynamics.py +15 -1
- archivebox_api-2.5.0/tests/test_kg_ingest.py +184 -0
- archivebox_api-2.5.0/tests/test_kg_media.py +111 -0
- archivebox_api-2.5.0/tests/test_web_source.py +242 -0
- archivebox_api-0.34.0/PKG-INFO +0 -307
- archivebox_api-0.34.0/README.md +0 -279
- archivebox_api-0.34.0/archivebox_api/__main__.py +0 -4
- archivebox_api-0.34.0/archivebox_api/agent_server.py +0 -95
- archivebox_api-0.34.0/archivebox_api/api/api_client_base.py +0 -80
- archivebox_api-0.34.0/archivebox_api/auth.py +0 -29
- archivebox_api-0.34.0/archivebox_api/mcp/__init__.py +0 -15
- archivebox_api-0.34.0/archivebox_api/mcp/mcp_authentication.py +0 -58
- archivebox_api-0.34.0/archivebox_api/mcp/mcp_cli.py +0 -57
- archivebox_api-0.34.0/archivebox_api/mcp/mcp_core.py +0 -63
- archivebox_api-0.34.0/archivebox_api/mcp_config.json +0 -23
- archivebox_api-0.34.0/archivebox_api/mcp_server.py +0 -244
- archivebox_api-0.34.0/archivebox_api.egg-info/PKG-INFO +0 -307
- archivebox_api-0.34.0/archivebox_api.egg-info/SOURCES.txt +0 -38
- archivebox_api-0.34.0/archivebox_api.egg-info/entry_points.txt +0 -3
- archivebox_api-0.34.0/archivebox_api.egg-info/requires.txt +0 -16
- archivebox_api-0.34.0/pyproject.toml +0 -59
- archivebox_api-0.34.0/requirements.txt +0 -1
- archivebox_api-0.34.0/scripts/security_sanitizer.py +0 -160
- archivebox_api-0.34.0/tests/test_archivebox_api_brute_force_coverage.py +0 -154
- archivebox_api-0.34.0/tests/test_concept_parity.py +0 -87
- archivebox_api-0.34.0/tests/test_startup.py +0 -12
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api/api/__init__.py +0 -0
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api/api_client.py +0 -0
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api.egg-info/dependency_links.txt +0 -0
- {archivebox_api-0.34.0 → archivebox_api-2.5.0}/setup.cfg +0 -0
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# Without this, `pre-commit install` wires ONLY the pre-commit hook, so `git push`
|
|
2
|
+
# runs nothing and every hook staged pre-push is silently dead code.
|
|
3
|
+
default_install_hook_types: [pre-commit, pre-push]
|
|
4
|
+
default_language_version:
|
|
5
|
+
python: python3
|
|
6
|
+
# Phase 0 dev-velocity contract (arbora-completion-program): a hook with no
|
|
7
|
+
# explicit `stages:` below is commit-only, never both.
|
|
8
|
+
default_stages: [pre-commit]
|
|
9
|
+
exclude: 'dotnet|node_modules'
|
|
10
|
+
ci:
|
|
11
|
+
autofix_prs: true
|
|
12
|
+
autoupdate_commit_msg: '[pre-commit.ci] pre-commit suggestions'
|
|
13
|
+
autoupdate_schedule: 'monthly'
|
|
14
|
+
|
|
15
|
+
repos:
|
|
16
|
+
- repo: https://github.com/pre-commit/pre-commit-hooks
|
|
17
|
+
rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # v6.0.0
|
|
18
|
+
hooks:
|
|
19
|
+
- id: check-added-large-files
|
|
20
|
+
args: ["--maxkb=2000"]
|
|
21
|
+
- id: check-ast
|
|
22
|
+
exclude: ^(tests/|test/|scripts/|script/)
|
|
23
|
+
- id: check-yaml
|
|
24
|
+
args: ["--unsafe"]
|
|
25
|
+
- id: check-toml
|
|
26
|
+
- id: check-json
|
|
27
|
+
- id: fix-byte-order-marker
|
|
28
|
+
exclude: .gitignore
|
|
29
|
+
- id: check-merge-conflict
|
|
30
|
+
- id: detect-private-key
|
|
31
|
+
- id: trailing-whitespace
|
|
32
|
+
- id: end-of-file-fixer
|
|
33
|
+
- id: no-commit-to-branch
|
|
34
|
+
- repo: https://github.com/astral-sh/ruff-pre-commit
|
|
35
|
+
rev: 38bfb07c0c64c304f47eb52090f8288150c77730 # frozen: v0.17.1
|
|
36
|
+
hooks:
|
|
37
|
+
- id: ruff-check
|
|
38
|
+
args: ["--fix", "--ignore=E402,B008,E501"]
|
|
39
|
+
exclude: ^(tests/|test/|scripts/|script/)
|
|
40
|
+
- id: ruff-format
|
|
41
|
+
exclude: ^(tests/|test/|scripts/|script/)
|
|
42
|
+
- repo: https://github.com/pre-commit/mirrors-mypy
|
|
43
|
+
rev: 2834ec6639549dd6796205c8f011dedcd587288b # frozen: v2.4.0
|
|
44
|
+
hooks:
|
|
45
|
+
- id: mypy
|
|
46
|
+
additional_dependencies: [pydantic==2.13.4, types-PyYAML==6.0.12.20260518, types-requests==2.33.0.20260518,
|
|
47
|
+
types-setuptools==83.0.0.20260706]
|
|
48
|
+
args: ["--ignore-missing-imports"]
|
|
49
|
+
- repo: https://github.com/jendrikseipp/vulture
|
|
50
|
+
rev: 258fe6a1974e89a2add9a45519a9e9dd9f46154e # frozen: v2.16
|
|
51
|
+
hooks:
|
|
52
|
+
- id: vulture
|
|
53
|
+
pass_filenames: false
|
|
54
|
+
args: [".", "--min-confidence", "95", "--exclude", "node_modules,dotnet,.venv,venv,node_modules,.git,build,dist"]
|
|
55
|
+
require_serial: true
|
|
56
|
+
- repo: https://github.com/codespell-project/codespell
|
|
57
|
+
rev: 57b21406f092110c18776e39b0bda50d37c945c8 # frozen: v2.4.3
|
|
58
|
+
hooks:
|
|
59
|
+
- id: codespell
|
|
60
|
+
args: ["-L", "ans,linar,nam,tread,ot,", "--ignore-words=.codespellignore"]
|
|
61
|
+
exclude: ^(tests/|test/|scripts/|script/|.*lock.*)
|
|
62
|
+
- repo: https://github.com/PyCQA/bandit
|
|
63
|
+
rev: 92ae8b82fb422a639f0ed8d99e96cea769594e08 # 1.9.4
|
|
64
|
+
hooks:
|
|
65
|
+
- id: bandit
|
|
66
|
+
args: ["--skip", "B101,B404,B603"]
|
|
67
|
+
exclude: ^(tests/|test/|scripts/|script/|__tests__/)
|
|
68
|
+
- repo: https://github.com/nbQA-dev/nbQA
|
|
69
|
+
rev: f96ec7f3b26a32619435686eb5813235f7e3327e # frozen: 1.9.1
|
|
70
|
+
hooks:
|
|
71
|
+
- id: nbqa-ruff
|
|
72
|
+
args: ["--fix"]
|
|
73
|
+
- repo: local
|
|
74
|
+
hooks:
|
|
75
|
+
- id: dependency-readiness
|
|
76
|
+
name: Dependency readiness — every declared intra-fleet constraint is installable
|
|
77
|
+
entry: bash -c 'P=""; d="$PWD"; while [ "$d" != "/" ]; do [ -d "$d/agent-packages/agents/repository-manager" ] && { P="$d/agent-packages/agents/repository-manager"; break; }; d=$(dirname "$d"); done; [ -n "$P" ] || P=repository-manager; uv run --no-project --python 3.12 --prerelease=allow --with "$P" python -m repository_manager.dependency_readiness .'
|
|
78
|
+
language: system
|
|
79
|
+
pass_filenames: false
|
|
80
|
+
always_run: true
|
|
81
|
+
stages: [manual, pre-push]
|
|
82
|
+
- id: uv-lock
|
|
83
|
+
name: uv-lock (verify, never mutate)
|
|
84
|
+
entry: uv lock --check
|
|
85
|
+
language: system
|
|
86
|
+
files: ^(uv\.lock|pyproject\.toml|uv\.toml)$
|
|
87
|
+
pass_filenames: false
|
|
88
|
+
stages: [pre-push, manual]
|
|
89
|
+
- repo: local
|
|
90
|
+
hooks:
|
|
91
|
+
- id: mermaid-validate
|
|
92
|
+
name: mermaid-validate
|
|
93
|
+
entry: mermaid-validate
|
|
94
|
+
language: node
|
|
95
|
+
additional_dependencies: ['@zabaca/mermaid-validate@1.0.1']
|
|
96
|
+
types: [markdown]
|
|
97
|
+
pass_filenames: true
|
|
98
|
+
- id: check-agent-standards
|
|
99
|
+
name: check agent standards
|
|
100
|
+
entry: |-
|
|
101
|
+
bash -c 'for f in $(find . -type f -name "agent_server.py" -not -path "*/\.venv/*" -not -path "*/__pycache__/*"); do grep -q "warnings.filterwarnings" "$f" && grep -q "file=sys.stderr" "$f" || { echo "Missing warnings.filterwarnings or file=sys.stderr in $f"; exit 1; }; done'
|
|
102
|
+
language: system
|
|
103
|
+
pass_filenames: false
|
|
104
|
+
always_run: true
|
|
105
|
+
- id: check-cli-help
|
|
106
|
+
name: check cli help
|
|
107
|
+
entry: |-
|
|
108
|
+
bash -c 'for f in $(find . -type f \( -name "mcp_server.py" -o -name "agent_server.py" \) -not -path "*/\.venv/*" -not -path "*/__pycache__/*"); do mod=$(echo "$f" | sed -e "s/^\.\///" -e "s/\.py$//" -e "s/\//./g"); uv run python -m "$mod" --help >/dev/null || exit 1; done'
|
|
109
|
+
language: system
|
|
110
|
+
pass_filenames: false
|
|
111
|
+
always_run: true
|
|
112
|
+
- id: env-var-drift
|
|
113
|
+
name: check env-var/config drift
|
|
114
|
+
entry: bash -c 'if [ -f uv.lock ]; then uv run python -m agent_connector_sdk.mcp.env_drift --check; else python -m agent_connector_sdk.mcp.env_drift --check; fi'
|
|
115
|
+
language: system
|
|
116
|
+
pass_filenames: false
|
|
117
|
+
files: ^(README\.md|\.env\.example|mcp_config.*\.json|.*/mcp_config.*\.json|docker/.*compose.*\.ya?ml|.*/auth\.py|.*/mcp_server\.py)$
|
|
118
|
+
- id: check-bumpversion
|
|
119
|
+
name: validate bumpversion config
|
|
120
|
+
entry: |-
|
|
121
|
+
bash -c 'if [ -f ".bumpversion.cfg" ]; then bump2version patch --dry-run --allow-dirty; fi'
|
|
122
|
+
language: system
|
|
123
|
+
pass_filenames: false
|
|
124
|
+
always_run: true
|
|
125
|
+
- repo: local
|
|
126
|
+
hooks:
|
|
127
|
+
- id: pytest
|
|
128
|
+
name: pytest
|
|
129
|
+
entry: bash -c 'test_target="tests"; for d in tests/unit test/unit tests test; do if [ -d "$d" ]; then test_target="$d"; break; fi; done; if [ -f uv.lock ]; then uv run --all-extras pytest "$test_target" -q --tb=short -m "not slow" --timeout=60; else pytest "$test_target" -q --tb=short -m "not slow" --timeout=60; fi'
|
|
130
|
+
language: system
|
|
131
|
+
types: [python]
|
|
132
|
+
pass_filenames: false
|
|
133
|
+
always_run: true
|
|
134
|
+
stages: [pre-push, manual]
|
|
135
|
+
- repo: https://github.com/AleksaC/hadolint-py
|
|
136
|
+
rev: 6e7504451511eaeb62a3e7f14d63b0296cbf86eb # frozen: v2.15.1
|
|
137
|
+
hooks:
|
|
138
|
+
- id: hadolint
|
|
139
|
+
args:
|
|
140
|
+
- --ignore=DL3008
|
|
141
|
+
- --ignore=DL3015
|
|
142
|
+
- --ignore=DL3009
|
|
143
|
+
- --ignore=DL4006
|
|
144
|
+
- --ignore=SC2102
|
|
145
|
+
- repo: https://github.com/IamTheFij/docker-pre-commit
|
|
146
|
+
rev: f626253b23de45412865c07fd076ff95d4cd77a7 # v3.0.1
|
|
147
|
+
hooks:
|
|
148
|
+
- id: docker-compose-check
|
|
149
|
+
|
|
150
|
+
- repo: local
|
|
151
|
+
hooks:
|
|
152
|
+
- id: verify-api-integration
|
|
153
|
+
name: Verify API-to-MCP Integration Coverage
|
|
154
|
+
entry: python scripts/verify_api_integration.py --local
|
|
155
|
+
language: system
|
|
156
|
+
pass_filenames: false
|
|
157
|
+
always_run: true
|
|
158
|
+
- repo: local
|
|
159
|
+
hooks:
|
|
160
|
+
- id: security-sanitizer
|
|
161
|
+
name: Security and Garbage Sanitizer
|
|
162
|
+
entry: python scripts/security_sanitizer.py
|
|
163
|
+
language: python
|
|
164
|
+
pass_filenames: false
|
|
165
|
+
always_run: true
|
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
> Claude Code loads this file via `CLAUDE.md` (`@AGENTS.md` import) — the two stay
|
|
4
|
+
> in sync. Edit **this** file, not `CLAUDE.md`.
|
|
5
|
+
|
|
6
|
+
## Tech Stack & Architecture
|
|
7
|
+
- Language/Version: Python 3.10+
|
|
8
|
+
- Core Libraries: `agent-connector-sdk`, `fastmcp`, `pydantic-ai`
|
|
9
|
+
- Key principles: Functional patterns, Pydantic for data validation, asynchronous tool execution.
|
|
10
|
+
- Architecture:
|
|
11
|
+
- `mcp_server.py`: Main MCP server entry point and tool registration.
|
|
12
|
+
- `agent_server.py`: Pydantic AI agent definition and logic.
|
|
13
|
+
- `skills/`: Directory containing modular agent skills (if applicable).
|
|
14
|
+
|
|
15
|
+
### Architecture Diagram
|
|
16
|
+
```mermaid
|
|
17
|
+
graph TD
|
|
18
|
+
User([User/A2A]) --> Server[A2A Server / FastAPI]
|
|
19
|
+
Server --> Agent[Pydantic AI Agent]
|
|
20
|
+
Agent --> Skills[Modular Skills]
|
|
21
|
+
Agent --> MCP[MCP Server / FastMCP]
|
|
22
|
+
MCP --> Client[API Client / Wrapper]
|
|
23
|
+
Client --> ExternalAPI([External Service API])
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
### Workflow Diagram
|
|
27
|
+
```mermaid
|
|
28
|
+
sequenceDiagram
|
|
29
|
+
participant U as User
|
|
30
|
+
participant S as Server
|
|
31
|
+
participant A as Agent
|
|
32
|
+
participant T as MCP Tool
|
|
33
|
+
participant API as External API
|
|
34
|
+
|
|
35
|
+
U->>S: Request
|
|
36
|
+
S->>A: Process Query
|
|
37
|
+
A->>T: Invoke Tool
|
|
38
|
+
T->>API: API Request
|
|
39
|
+
API-->>T: API Response
|
|
40
|
+
T-->>A: Tool Result
|
|
41
|
+
A-->>S: Final Response
|
|
42
|
+
S-->>U: Output
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Commands (run these exactly)
|
|
46
|
+
# Installation
|
|
47
|
+
pip install .[all]
|
|
48
|
+
|
|
49
|
+
# Quality & Linting (run from project root)
|
|
50
|
+
pre-commit run --all-files
|
|
51
|
+
|
|
52
|
+
# Execution Commands
|
|
53
|
+
# archivebox-mcp\narchivebox_api.mcp:mcp_server\n# archivebox-agent\narchivebox_api.agent:agent_server
|
|
54
|
+
|
|
55
|
+
## Project Structure Quick Reference
|
|
56
|
+
- MCP Entry Point → `mcp_server.py`
|
|
57
|
+
- Agent Entry Point → `agent_server.py`
|
|
58
|
+
- Source Code → `archivebox_api/`
|
|
59
|
+
- Skills → `skills/` (if exists)
|
|
60
|
+
|
|
61
|
+
### File Tree
|
|
62
|
+
```text
|
|
63
|
+
├── .bumpversion.cfg\n├── .dockerignore\n├── .env\n├── .gitattributes\n├── .github\n│ └── workflows\n│ └── pipeline.yml\n├── .gitignore\n├── .pre-commit-config.yaml\n├── AGENTS.md\n├── Dockerfile\n├── LICENSE\n├── MANIFEST.in\n├── README.md\n├── archivebox_api\n│ ├── __init__.py\n│ ├── __main__.py\n│ ├── agent_server.py\n│ ├── api_wrapper.py\n│ └── mcp_server.py\n├── compose.yml\n├── debug.Dockerfile\n├── mcp\n│ └── archivebox\n│ ├── crontabs\n│ └── logs\n├── mcp.compose.yml\n├── pyproject.toml\n├── pytest.ini\n└── requirements.txt
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Code Style & Conventions
|
|
67
|
+
**Always:**
|
|
68
|
+
- Use `agent-connector-sdk` for common patterns (e.g., `create_mcp_server`, `create_agent`).
|
|
69
|
+
- Define input/output models using Pydantic.
|
|
70
|
+
- Include descriptive docstrings for all tools (they are used as tool descriptions for LLMs).
|
|
71
|
+
- Check for optional dependencies using `try/except ImportError`.
|
|
72
|
+
|
|
73
|
+
**Good example:**
|
|
74
|
+
```python
|
|
75
|
+
from agent_connector_sdk import create_mcp_server
|
|
76
|
+
from mcp.server.fastmcp import FastMCP
|
|
77
|
+
|
|
78
|
+
mcp = create_mcp_server("my-agent")
|
|
79
|
+
|
|
80
|
+
@mcp.tool()
|
|
81
|
+
async def my_tool(param: str) -> str:
|
|
82
|
+
"""Description for LLM."""
|
|
83
|
+
return f"Result: {param}"
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Dos and Don'ts
|
|
87
|
+
**Do:**
|
|
88
|
+
- Run `pre-commit` before pushing changes.
|
|
89
|
+
- Use existing patterns from `agent-connector-sdk`.
|
|
90
|
+
- Keep tools focused and idempotent where possible.
|
|
91
|
+
|
|
92
|
+
**Don't:**
|
|
93
|
+
- Use `cd` commands in scripts; use absolute paths or relative to project root.
|
|
94
|
+
- Add new dependencies to `dependencies` in `pyproject.toml` without checking `optional-dependencies` first.
|
|
95
|
+
- Hardcode secrets; use environment variables or `.env` files.
|
|
96
|
+
|
|
97
|
+
## Safety & Boundaries
|
|
98
|
+
**Always do:**
|
|
99
|
+
- Run lint/test via `pre-commit`.
|
|
100
|
+
- Use `agent-connector-sdk` base classes.
|
|
101
|
+
|
|
102
|
+
**Ask first:**
|
|
103
|
+
- Major refactors of `mcp_server.py` or `agent_server.py`.
|
|
104
|
+
- Removing or renaming public tool functions.
|
|
105
|
+
|
|
106
|
+
**Never do:**
|
|
107
|
+
- Commit `.env` files or secrets.
|
|
108
|
+
- Modify `agent-connector-sdk` or `universal-skills` files from within this package.
|
|
109
|
+
|
|
110
|
+
## When Stuck
|
|
111
|
+
- Propose a plan first before making large changes.
|
|
112
|
+
- Check `agent-connector-sdk` documentation for existing helpers.
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
## Graph Architecture
|
|
116
|
+
|
|
117
|
+
This agent uses `pydantic-graph` orchestration for intelligent routing and optimal context management.
|
|
118
|
+
|
|
119
|
+
```mermaid
|
|
120
|
+
---
|
|
121
|
+
title: Archivebox API Graph Agent
|
|
122
|
+
---
|
|
123
|
+
stateDiagram-v2
|
|
124
|
+
[*] --> RouterNode: User Query
|
|
125
|
+
RouterNode --> DomainNode: Classified Domain
|
|
126
|
+
RouterNode --> [*]: Low confidence / Error
|
|
127
|
+
DomainNode --> [*]: Domain Result
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
- **RouterNode**: A fast, lightweight LLM (e.g., `nvidia/nemotron-3-super`) that classifies the user's query into one of the specialized domains.
|
|
131
|
+
- **DomainNode**: The executor node. For the selected domain, it dynamically sets environment variables to temporarily enable ONLY the tools relevant to that domain, creating a highly focused sub-agent (e.g., `gpt-4o`) to complete the request. This preserves LLM context and prevents tool hallucination.
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
## Testing with Timeout
|
|
135
|
+
|
|
136
|
+
To run tests with a timeout to prevent hanging, use the `pytest-timeout` plugin. The operator can combine it with the `-k` flag to run specific tests:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
uv run pytest --timeout=60 -k "test_name_pattern"
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## ⛔ No Scratch or Temporary Files in Repository
|
|
143
|
+
|
|
144
|
+
**NEVER write any of the following to this repository:**
|
|
145
|
+
- Temporary test scripts (`test_*.py`, `debug_*.py` outside of `tests/`)
|
|
146
|
+
- Scratch scripts or experimental one-off files
|
|
147
|
+
- Log files (`.log`, `.txt` command output)
|
|
148
|
+
- Random text files with command output or debug dumps
|
|
149
|
+
- Any file that is NOT production source code, tests in `tests/`, or documentation
|
|
150
|
+
|
|
151
|
+
**Why:** These files expose private filesystem paths, credentials, and internal infrastructure details when pushed to GitHub publicly.
|
|
152
|
+
|
|
153
|
+
**Where to put scratch work instead:**
|
|
154
|
+
- Use `~/workspace/scratch/` for temporary scripts and experiments
|
|
155
|
+
- Use `~/workspace/reports/` for command output and reports
|
|
156
|
+
- Keep test scripts in the `tests/` directory following proper pytest conventions
|
|
157
|
+
|
|
158
|
+
## ⛔ Keep the Repository Root Pristine — No Scratch / Temp / Debug Files
|
|
159
|
+
|
|
160
|
+
**The repository ROOT must contain only canonical project files** (packaging,
|
|
161
|
+
config, docs, lockfiles). The only hidden directories allowed at root are
|
|
162
|
+
`.git/`, `.github/`, and `.specify/` (plus a local, git-ignored `.venv/`).
|
|
163
|
+
|
|
164
|
+
**NEVER write any of the following — anywhere in the repo, and ESPECIALLY at the root:**
|
|
165
|
+
- One-off / debug / migration scripts: `fix_*.py`, `migrate_*.py`, `refactor_*.py`,
|
|
166
|
+
`replace_*.py`, `update_*.py`, `debug_*.py`, or `test_*.py` **at the root**
|
|
167
|
+
(real tests live in `tests/` only).
|
|
168
|
+
- Databases / data dumps: `*.db`, `*.db-wal`, `*.sqlite*`, `*.corrupted`.
|
|
169
|
+
- Logs / command output: `*.log`, scratch `*.txt`, `*.orig`, `*.rej`, `*.bak`.
|
|
170
|
+
- Build artifacts: `*.tsbuildinfo`, compiled binaries, coverage files.
|
|
171
|
+
- AI agent scratch directories: `.agent/`, `.agents/`, `.agent_data/`, `.tmp/`,
|
|
172
|
+
`.hypothesis/`, or any per-tool cache committed to git.
|
|
173
|
+
- Any file that is NOT production source, a test in `tests/`, documentation, or
|
|
174
|
+
a recognized config/lockfile.
|
|
175
|
+
|
|
176
|
+
**Why:** scratch at the root leaks private paths/credentials, bloats the tree,
|
|
177
|
+
and erodes a pristine codebase.
|
|
178
|
+
|
|
179
|
+
**Where scratch goes instead:** `~/workspace/scratch/` (experiments),
|
|
180
|
+
`~/workspace/reports/` (command output); tests go in `tests/` (pytest).
|
|
181
|
+
Before finishing a task, run `git status` and confirm no stray root files were added.
|
|
182
|
+
|
|
183
|
+
## Working Discipline — think, simplify, stay surgical, check
|
|
184
|
+
|
|
185
|
+
These four habits cut the most common LLM coding mistakes. For trivial tasks, use
|
|
186
|
+
judgment; the bias here is correctness over speed.
|
|
187
|
+
|
|
188
|
+
- **Think before coding.** State the operator's assumptions explicitly. If a request has more than
|
|
189
|
+
one reasonable reading, surface the options instead of silently picking one. If a
|
|
190
|
+
simpler approach exists, say so and push back when warranted. When something is
|
|
191
|
+
genuinely unclear, stop and name what's confusing — ask, don't guess.
|
|
192
|
+
- **Simplicity first.** Write the minimum code that solves the stated problem — no
|
|
193
|
+
speculative features, no abstraction for single-use code, no configurability that
|
|
194
|
+
wasn't requested, no error handling for impossible states. If the operator wrote 200 lines and
|
|
195
|
+
it can be 50, rewrite it. (Name code from its purpose, never `wave0`/`phase2`/`v2`.)
|
|
196
|
+
- **Stay surgical.** Every changed line should trace directly to the task. Don't refactor,
|
|
197
|
+
reformat, or "improve" working code adjacent to the operator's change; match the existing style
|
|
198
|
+
even where the operator'd do it differently. Remove only the imports/symbols the operator's own change
|
|
199
|
+
orphaned; if the operator spot unrelated dead code, mention it rather than removing it inline.
|
|
200
|
+
*Exception — the Quality Bar below:* lint/format/type errors the pre-commit gate flags
|
|
201
|
+
get fixed in either case of who introduced them. In short: **surgical on behavior, clean on
|
|
202
|
+
lint.**
|
|
203
|
+
- **Check against a goal.** Turn the task into a checkable outcome before the operator start:
|
|
204
|
+
"fix the bug" → "write a failing test that reproduces it, then make it pass"; "add
|
|
205
|
+
validation" → "tests for the invalid inputs pass". For multi-step work, state the short
|
|
206
|
+
plan and the check for each step, then loop until the checks pass.
|
|
207
|
+
|
|
208
|
+
## Quality Bar — Leave the Codebase Clean (REQUIRED)
|
|
209
|
+
|
|
210
|
+
After completing any code change, run the project's pre-commit suite and drive it
|
|
211
|
+
**fully green** before committing:
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
pre-commit run --all-files
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Resolve **every** issue it reports — failures, lint errors, type errors, and
|
|
218
|
+
warnings — **including problems that pre-date the operator's change and were not caused by
|
|
219
|
+
the operator's edits**. The standing goal is a clean, working codebase with **no errors and
|
|
220
|
+
no warnings**. Do not silence checks (`# noqa`, `# type: ignore`, `SKIP=`,
|
|
221
|
+
`--no-verify`) to force green unless the exception is already documented in this
|
|
222
|
+
file as a known, unavoidable limitation. Only commit once `pre-commit run
|
|
223
|
+
--all-files` passes cleanly; if a check legitimately cannot pass, stop and explain
|
|
224
|
+
why rather than bypassing it.
|
|
225
|
+
|
|
226
|
+
## Working with Git Worktrees (multi-session)
|
|
227
|
+
|
|
228
|
+
Multiple agents/sessions work the `agent-packages/*` repos concurrently. **Do not
|
|
229
|
+
edit the canonical checkout** (`${WORKSPACE_ROOT}/agent-packages/<repo>`) — a
|
|
230
|
+
background `repository-manager` sync can reset its working tree and discard
|
|
231
|
+
uncommitted edits. Take the operator's own git worktree on the operator's own branch instead:
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
# preferred — repository-manager MCP:
|
|
235
|
+
rm_worktree add <repo> <your-branch> # -> ${WORKTREE_ROOT}/<repo>/<your-branch>
|
|
236
|
+
|
|
237
|
+
# raw-git fallback:
|
|
238
|
+
git -C agent-packages/<repo> checkout main
|
|
239
|
+
git -C agent-packages/<repo> worktree add ${WORKTREE_ROOT}/<repo>/<branch> -b <branch>
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Work in the worktree and **commit often** (commits survive a working-tree reset).
|
|
243
|
+
Each session must use a **distinct branch** — git allows a branch in only one
|
|
244
|
+
worktree, which is what keeps concurrent sessions from colliding. Worktrees live
|
|
245
|
+
under `${WORKTREE_ROOT}/` (outside the workspace scan, so the sync leaves them
|
|
246
|
+
alone).
|
|
247
|
+
|
|
248
|
+
**Finishing work in a worktree** — run this sequence before calling it done:
|
|
249
|
+
1. **Pre-commit green** — `pre-commit run --all-files`; resolve every issue per the
|
|
250
|
+
Quality Bar above (including pre-existing), no `--no-verify`.
|
|
251
|
+
2. **Commit** in the worktree.
|
|
252
|
+
3. **Merge to main locally** — `rm_worktree merge <repo> <branch> --into main`
|
|
253
|
+
(or `git merge --no-ff`). Push only when the user asks.
|
|
254
|
+
4. **Clean up** — remove the worktree and remove the merged branch:
|
|
255
|
+
`rm_worktree remove <repo> <branch> --delete-branch`; `rm_worktree prune` clears
|
|
256
|
+
stale entries. (Raw-git: `git worktree remove <path> && git branch -d <branch>`.)
|
|
257
|
+
|
|
258
|
+
<!-- BEGIN concept-coordination (generated) -->
|
|
259
|
+
## Concept-ID Coordination (multi-session)
|
|
260
|
+
|
|
261
|
+
Working in parallel with other sessions/worktrees? **Reserve a concept id before you write its `CONCEPT:` marker** so two sessions never collide:
|
|
262
|
+
|
|
263
|
+
```bash
|
|
264
|
+
agent-connector-sdk --json concept reserve --ns EG-KG.compute.backend # or a package prefix, e.g. KEY
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
Full protocol (ledger, merge=union, reconcile, MCP/REST): <https://knuckles-team.github.io/agent-connector-sdk/concept_coordination/>
|
|
268
|
+
<!-- END concept-coordination (generated) -->
|
|
269
|
+
|
|
270
|
+
## Version & lockfile drift edict (keep the version mirrors AND the lock in sync)
|
|
271
|
+
|
|
272
|
+
The two most common release-breakers in this fleet are **version drift** (the version in
|
|
273
|
+
`pyproject.toml`/`.bumpversion.cfg` advancing while `README.md`, `docker/Dockerfile`, and the
|
|
274
|
+
module `__version__`s lag) and a **stale `uv.lock`** (shipping known-vulnerable transitive deps).
|
|
275
|
+
A version mismatch makes the next `bump-my-version` throw `VersionNotFoundException`; a stale lock
|
|
276
|
+
is what Dependabot flags. Rules:
|
|
277
|
+
|
|
278
|
+
1. **Never hand-edit a version string.** Change the version ONLY via
|
|
279
|
+
`bump-my-version bump {patch|minor|major}` (a.k.a. `bump2version`), which rewrites every file
|
|
280
|
+
registered in `.bumpversion.cfg` in one atomic, tagged commit. If the operator edited the version in
|
|
281
|
+
`pyproject.toml` by hand, the operator created drift — revert and use the bumper.
|
|
282
|
+
2. **Every version-bearing file must be registered in `.bumpversion.cfg`** — at minimum
|
|
283
|
+
`pyproject.toml` AND `README.md`, plus `docker/Dockerfile` and any module `__version__`. Never
|
|
284
|
+
add a file that embeds the version without a `[bumpversion:file:...]` entry for it.
|
|
285
|
+
3. **Re-lock on every dependency change.** After editing `pyproject.toml` deps/extras, run
|
|
286
|
+
`uv lock` and commit `uv.lock` in the SAME change. The `uv-lock` pre-commit hook runs with
|
|
287
|
+
`--locked` and fails on drift — never bypass it. The committed `uv.lock` is the
|
|
288
|
+
Dependabot/security surface.
|
|
289
|
+
4. **Patch CVEs with a version floor at the source, then re-lock.** `uv` resolves one version
|
|
290
|
+
graph-wide, so a lower-bound in the extra that pulls a dependency raises it for the whole lock.
|
|
291
|
+
|
|
292
|
+
## Specs: extend first
|
|
293
|
+
|
|
294
|
+
Find the spec row that owns the behavior before any code change. Search with `git grep -n "<term>" -- specs`. Cite the row ID in the commit `Spec:` trailer. Extend the owning spec before any new spec text. Add a child row, a new rollup, or a dated `plan.md` "Amendments" entry. Create a new spec only for a capability that no spec owns. Audits, reviews, and carry-overs land in the owning spec. They never get a spec directory. Reuse an existing function, module, or store before adding one. The rules are the ecosystem [spec standard](https://github.com/Knuckles-Team/pipelines/blob/main/reference/spec-standard.md).
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- None
|
|
12
|
+
|
|
13
|
+
## [0.14.0] - 2026-05-22
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
- Explicit ecosystem **Concept Traceability** decoration across all code, tests, and documentation, covering:
|
|
17
|
+
- `ECO-4.0` (Tool Interface & MCP Factory)
|
|
18
|
+
- `ECO-4.1` (A2A Network & Consensus)
|
|
19
|
+
- `OS-5.1` (Security & Auth)
|
|
20
|
+
- `OS-5.4` (Telemetry & Observability)
|
|
21
|
+
- Brand new `conftest.py` containing reusable fixtures (`mock_client`, `mock_context`, and `temp_env`) to simplify the test suite.
|
|
22
|
+
- Parameterized HTTP response exception mappings using `@pytest.mark.parametrize` for clean data-driven test coverage.
|
|
23
|
+
- Fully documented environment variables and fallbacks (like `ARCHIVEBOX_URL`) in `.env.example` and `README.md`.
|
|
24
|
+
- Interactive Table of Contents and concrete usage examples with markdown code blocks in `README.md`.
|
|
25
|
+
|
|
26
|
+
### Fixed
|
|
27
|
+
- Outdated internal documentation page links in `README.md`.
|
|
28
|
+
- Unregistered concept pytest warnings by explicitly registering the custom marker in `pytest.ini`.
|
|
29
|
+
|
|
30
|
+
### Changed
|
|
31
|
+
- Refactored `tests/test_archivebox_coverage_extra.py` to achieve full compliance with standard repository structures, reaching a Grade Point Average (GPA) of **3.8/4.0+**.
|
|
32
|
+
|
|
33
|
+
## [0.1.54] - 2026-04-29
|
|
34
|
+
|
|
35
|
+
### Added
|
|
36
|
+
- Initial release of the `archivebox-api` package.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
Guidance for Claude Code (claude.ai/code) when working in this repository.
|
|
4
|
+
|
|
5
|
+
To prevent drift, the **canonical agent guidance lives in `AGENTS.md`** and is
|
|
6
|
+
imported below, so `CLAUDE.md` and `AGENTS.md` always stay in sync. Edit
|
|
7
|
+
`AGENTS.md` for any change — never edit the body of this file.
|
|
8
|
+
|
|
9
|
+
@AGENTS.md
|
|
@@ -1 +1 @@
|
|
|
1
|
-
include README.md include requirements.txt recursive-include archivebox_api *.py
|
|
1
|
+
include README.md include requirements.txt recursive-include archivebox_api *.py *.json *.md *.yaml *.yml
|