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.
Files changed (93) hide show
  1. archivebox_api-2.5.0/.pre-commit-config.yaml +165 -0
  2. archivebox_api-2.5.0/AGENTS.md +294 -0
  3. archivebox_api-2.5.0/CHANGELOG.md +36 -0
  4. archivebox_api-2.5.0/CLAUDE.md +9 -0
  5. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/LICENSE +1 -1
  6. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/MANIFEST.in +1 -1
  7. archivebox_api-2.5.0/PKG-INFO +510 -0
  8. archivebox_api-2.5.0/README.md +483 -0
  9. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api/__init__.py +34 -22
  10. archivebox_api-2.5.0/archivebox_api/__main__.py +4 -0
  11. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api/api/api_client_auth.py +1 -3
  12. archivebox_api-2.5.0/archivebox_api/api/api_client_base.py +82 -0
  13. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api/api/api_client_cli.py +2 -7
  14. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api/api/api_client_core.py +2 -9
  15. archivebox_api-2.5.0/archivebox_api/auth.py +33 -0
  16. archivebox_api-2.5.0/archivebox_api/connector_manifest.yml +172 -0
  17. archivebox_api-2.5.0/archivebox_api/connectors/__init__.py +0 -0
  18. archivebox_api-2.5.0/archivebox_api/connectors/mcp_source_presets.json +18 -0
  19. archivebox_api-2.5.0/archivebox_api/connectors/tool_schema_fingerprints.json +8 -0
  20. archivebox_api-2.5.0/archivebox_api/kg_ingest.py +433 -0
  21. archivebox_api-2.5.0/archivebox_api/mcp_config.json +28 -0
  22. archivebox_api-2.5.0/archivebox_api/mcp_server.py +432 -0
  23. archivebox_api-2.5.0/archivebox_api/ontology/__init__.py +7 -0
  24. archivebox_api-2.5.0/archivebox_api/ontology/archivebox.ttl +99 -0
  25. archivebox_api-2.5.0/archivebox_api/ontology/certification.json +36 -0
  26. archivebox_api-2.5.0/archivebox_api/ontology/fixtures/records.json +21 -0
  27. archivebox_api-2.5.0/archivebox_api/ontology/mappings/source.yaml +20 -0
  28. archivebox_api-2.5.0/archivebox_api/ontology/migrations/manifest.json +6 -0
  29. archivebox_api-2.5.0/archivebox_api/ontology/shapes/connector.shacl.ttl +44 -0
  30. archivebox_api-2.5.0/archivebox_api/prompts/__init__.py +0 -0
  31. archivebox_api-2.5.0/archivebox_api/prompts/web_archivist_specialist.json +43 -0
  32. archivebox_api-2.5.0/archivebox_api/skills/__init__.py +0 -0
  33. archivebox_api-2.5.0/archivebox_api/skills/archivebox-api-operations/SKILL.md +33 -0
  34. archivebox_api-2.5.0/archivebox_api/skills/archivebox-api-operations/agents/openai.yaml +4 -0
  35. archivebox_api-2.5.0/archivebox_api/skills/archivebox-api-operations/references/catalog.md +7 -0
  36. archivebox_api-2.5.0/archivebox_api/skills/archivebox-kg-ingestion/SKILL.md +91 -0
  37. archivebox_api-2.5.0/archivebox_api/skills/archivebox-kg-ingestion/WORKFLOW.md +77 -0
  38. archivebox_api-2.5.0/archivebox_api/skills/archivebox-snapshot-search/SKILL.md +94 -0
  39. archivebox_api-2.5.0/archivebox_api/skills/archivebox-snapshot-search/WORKFLOW.md +80 -0
  40. archivebox_api-2.5.0/archivebox_api/skills/archivebox-web-archiving/SKILL.md +96 -0
  41. archivebox_api-2.5.0/archivebox_api/skills/archivebox-web-archiving/WORKFLOW.md +82 -0
  42. archivebox_api-2.5.0/archivebox_api/web_source.py +281 -0
  43. archivebox_api-2.5.0/archivebox_api/web_source_contract.py +199 -0
  44. archivebox_api-2.5.0/archivebox_api.egg-info/PKG-INFO +510 -0
  45. archivebox_api-2.5.0/archivebox_api.egg-info/SOURCES.txt +69 -0
  46. archivebox_api-2.5.0/archivebox_api.egg-info/entry_points.txt +14 -0
  47. archivebox_api-2.5.0/archivebox_api.egg-info/requires.txt +14 -0
  48. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api.egg-info/top_level.txt +3 -0
  49. archivebox_api-2.5.0/connector_manifest.yml +172 -0
  50. archivebox_api-2.5.0/mkdocs.yml +95 -0
  51. archivebox_api-2.5.0/opencode.json +18 -0
  52. archivebox_api-2.5.0/pyproject.toml +80 -0
  53. archivebox_api-2.5.0/release-readiness.json +16811 -0
  54. archivebox_api-2.5.0/requirements.txt +1 -0
  55. archivebox_api-2.5.0/scripts/security_sanitizer.py +318 -0
  56. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/scripts/verify_api_integration.py +153 -112
  57. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/tests/conftest.py +2 -2
  58. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/tests/test_action_discovery.py +2 -2
  59. archivebox_api-2.5.0/tests/test_archivebox_api_brute_force_coverage.py +166 -0
  60. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/tests/test_archivebox_coverage.py +63 -65
  61. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/tests/test_archivebox_coverage_extra.py +75 -187
  62. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/tests/test_basic.py +4 -7
  63. archivebox_api-2.5.0/tests/test_conformance.py +159 -0
  64. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/tests/test_init_dynamics.py +15 -1
  65. archivebox_api-2.5.0/tests/test_kg_ingest.py +184 -0
  66. archivebox_api-2.5.0/tests/test_kg_media.py +111 -0
  67. archivebox_api-2.5.0/tests/test_web_source.py +242 -0
  68. archivebox_api-0.34.0/PKG-INFO +0 -307
  69. archivebox_api-0.34.0/README.md +0 -279
  70. archivebox_api-0.34.0/archivebox_api/__main__.py +0 -4
  71. archivebox_api-0.34.0/archivebox_api/agent_server.py +0 -95
  72. archivebox_api-0.34.0/archivebox_api/api/api_client_base.py +0 -80
  73. archivebox_api-0.34.0/archivebox_api/auth.py +0 -29
  74. archivebox_api-0.34.0/archivebox_api/mcp/__init__.py +0 -15
  75. archivebox_api-0.34.0/archivebox_api/mcp/mcp_authentication.py +0 -58
  76. archivebox_api-0.34.0/archivebox_api/mcp/mcp_cli.py +0 -57
  77. archivebox_api-0.34.0/archivebox_api/mcp/mcp_core.py +0 -63
  78. archivebox_api-0.34.0/archivebox_api/mcp_config.json +0 -23
  79. archivebox_api-0.34.0/archivebox_api/mcp_server.py +0 -244
  80. archivebox_api-0.34.0/archivebox_api.egg-info/PKG-INFO +0 -307
  81. archivebox_api-0.34.0/archivebox_api.egg-info/SOURCES.txt +0 -38
  82. archivebox_api-0.34.0/archivebox_api.egg-info/entry_points.txt +0 -3
  83. archivebox_api-0.34.0/archivebox_api.egg-info/requires.txt +0 -16
  84. archivebox_api-0.34.0/pyproject.toml +0 -59
  85. archivebox_api-0.34.0/requirements.txt +0 -1
  86. archivebox_api-0.34.0/scripts/security_sanitizer.py +0 -160
  87. archivebox_api-0.34.0/tests/test_archivebox_api_brute_force_coverage.py +0 -154
  88. archivebox_api-0.34.0/tests/test_concept_parity.py +0 -87
  89. archivebox_api-0.34.0/tests/test_startup.py +0 -12
  90. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api/api/__init__.py +0 -0
  91. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api/api_client.py +0 -0
  92. {archivebox_api-0.34.0 → archivebox_api-2.5.0}/archivebox_api.egg-info/dependency_links.txt +0 -0
  93. {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,4 +1,4 @@
1
- Copyright (c) 2012-2023 Audel Rouhi
1
+ Copyright (c) 2012-2023 Project Maintainers
2
2
 
3
3
  Permission is hereby granted, free of charge, to any person obtaining
4
4
  a copy of this software and associated documentation files (the
@@ -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