aictx 0.3.0__tar.gz

aictx-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santi Santamaria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aictx-0.3.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: aictx
+Version: 0.3.0
+Summary: Repo-native runtime contract and context bootstrapper for coding agents
+Author: Santi Santamaria
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/oldskultxo/aictx
+Project-URL: Repository, https://github.com/oldskultxo/aictx
+Project-URL: Issues, https://github.com/oldskultxo/aictx/issues
+Keywords: ai,llm,coding-agents,developer-tools,context-engine,codex,claude
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# aictx
+
+**Install once. Initialize a repo. Give coding agents a real runtime contract.**
+
+`aictx` turns a normal repository into a repository that is prepared for coding agents.
+
+## Product surface
+
+The sellable user flow stays intentionally small:
+
+1. `aictx install`
+2. `aictx init`
+3. use Codex, Claude Code, or your normal automation
+
+Everything else exists to support that runtime, not to expand the primary UX.
+
+## What it really does today
+
+After `install + init`, `aictx` can provide:
+
+- repo-local bootstrap memory under `.ai_context_engine/`
+- packet-oriented context for non-trivial work
+- task memory, failure memory, and memory graph scaffolds
+- repo-native instruction integration for Codex and Claude Code
+- wrapped middleware for generic automation via `aictx internal run-execution`
+- local/global telemetry and health artifacts
+
+## Honest limits
+
+This is still a **0.x beta** product.
+
+- final behavior depends on each runner honoring its instruction and hook system
+- telemetry quality is best-effort unless confidence is explicitly high
+- advanced/internal commands are supported, but not the main thing being sold
+- some deeper capabilities are still being extracted from the canonical engine
+
+See [docs/LIMITATIONS.md](docs/LIMITATIONS.md).
+
+## Install from PyPI
+
+```bash
+pip install aictx
+```
+
+Then:
+
+```bash
+aictx install
+aictx init --repo .
+```
+
+## Install once
+
+```bash
+aictx install
+```
+
+Non-interactive:
+
+```bash
+aictx install --yes --workspace-root ~/projects
+```
+
+This creates the global runtime under `~/.ai_context_engine/` and provisions:
+
+- global configuration
+- workspace registry
+- adapters and wrappers
+- global telemetry storage
+- global Codex instructions
+
+## Initialize a repo
+
+```bash
+aictx init
+```
+
+Non-interactive:
+
+```bash
+aictx init --repo . --yes
+```
+
+`init` creates:
+
+- `.ai_context_engine/memory/`
+- `.ai_context_engine/cost/`
+- `.ai_context_engine/task_memory/`
+- `.ai_context_engine/failure_memory/`
+- `.ai_context_engine/memory_graph/`
+- `.ai_context_engine/library/`
+- `.ai_context_engine/metrics/`
+- `.ai_context_engine/adapters/`
+- `.ai_context_engine/state.json`
+- `.ai_context_engine/agent_runtime.md`
+
+And native repo integration files:
+
+- `AGENTS.md`
+- `AGENTS.override.md`
+- `CLAUDE.md`
+- `.claude/settings.json`
+- `.claude/hooks/...`
+- `.gitignore`
+
+## Runtime consistency
+
+`aictx boot --repo <path>` and `aictx execution prepare ...` now expose:
+
+- effective communication policy
+- communication source precedence
+- runtime consistency checks between repo preferences and repo state
+
+Precedence is:
+
+`explicit user instruction > repo prefs > global defaults > hardcoded fallback`
+
+## Public beta posture
+
+`aictx` is now distributed publicly as a **beta 0.x** package.
+
+- installation is supported through PyPI and GitHub releases
+- the core user flow is `pip install aictx` -> `aictx install` -> `aictx init`
+- compatibility is still best-effort, not a long-term 1.0 stability promise
+
+## Development quickstart
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install --upgrade pip
+.venv/bin/pip install -e . pytest build
+make test
+make smoke
+make package-check
+```
+
+You can also call the installed script directly:
+
+```bash
+.venv/bin/aictx --help
+```
+
+Public release validation also checks clean wheel installation, not just editable installs.
+
+## Read next
+
+- [Usage guide](docs/USAGE.md)
+- [Technical overview](docs/TECHNICAL_OVERVIEW.md)
+- [5-minute demo](docs/DEMO.md)
+- [Current limitations](docs/LIMITATIONS.md)
+- [Phase 2 notes](docs/PHASE2_NOTES.md)
+- [Release checklist](docs/RELEASE_CHECKLIST.md)

aictx-0.3.0/README.md

@@ -0,0 +1,152 @@
+# aictx
+
+**Install once. Initialize a repo. Give coding agents a real runtime contract.**
+
+`aictx` turns a normal repository into a repository that is prepared for coding agents.
+
+## Product surface
+
+The sellable user flow stays intentionally small:
+
+1. `aictx install`
+2. `aictx init`
+3. use Codex, Claude Code, or your normal automation
+
+Everything else exists to support that runtime, not to expand the primary UX.
+
+## What it really does today
+
+After `install + init`, `aictx` can provide:
+
+- repo-local bootstrap memory under `.ai_context_engine/`
+- packet-oriented context for non-trivial work
+- task memory, failure memory, and memory graph scaffolds
+- repo-native instruction integration for Codex and Claude Code
+- wrapped middleware for generic automation via `aictx internal run-execution`
+- local/global telemetry and health artifacts
+
+## Honest limits
+
+This is still a **0.x beta** product.
+
+- final behavior depends on each runner honoring its instruction and hook system
+- telemetry quality is best-effort unless confidence is explicitly high
+- advanced/internal commands are supported, but not the main thing being sold
+- some deeper capabilities are still being extracted from the canonical engine
+
+See [docs/LIMITATIONS.md](docs/LIMITATIONS.md).
+
+## Install from PyPI
+
+```bash
+pip install aictx
+```
+
+Then:
+
+```bash
+aictx install
+aictx init --repo .
+```
+
+## Install once
+
+```bash
+aictx install
+```
+
+Non-interactive:
+
+```bash
+aictx install --yes --workspace-root ~/projects
+```
+
+This creates the global runtime under `~/.ai_context_engine/` and provisions:
+
+- global configuration
+- workspace registry
+- adapters and wrappers
+- global telemetry storage
+- global Codex instructions
+
+## Initialize a repo
+
+```bash
+aictx init
+```
+
+Non-interactive:
+
+```bash
+aictx init --repo . --yes
+```
+
+`init` creates:
+
+- `.ai_context_engine/memory/`
+- `.ai_context_engine/cost/`
+- `.ai_context_engine/task_memory/`
+- `.ai_context_engine/failure_memory/`
+- `.ai_context_engine/memory_graph/`
+- `.ai_context_engine/library/`
+- `.ai_context_engine/metrics/`
+- `.ai_context_engine/adapters/`
+- `.ai_context_engine/state.json`
+- `.ai_context_engine/agent_runtime.md`
+
+And native repo integration files:
+
+- `AGENTS.md`
+- `AGENTS.override.md`
+- `CLAUDE.md`
+- `.claude/settings.json`
+- `.claude/hooks/...`
+- `.gitignore`
+
+## Runtime consistency
+
+`aictx boot --repo <path>` and `aictx execution prepare ...` now expose:
+
+- effective communication policy
+- communication source precedence
+- runtime consistency checks between repo preferences and repo state
+
+Precedence is:
+
+`explicit user instruction > repo prefs > global defaults > hardcoded fallback`
+
+## Public beta posture
+
+`aictx` is now distributed publicly as a **beta 0.x** package.
+
+- installation is supported through PyPI and GitHub releases
+- the core user flow is `pip install aictx` -> `aictx install` -> `aictx init`
+- compatibility is still best-effort, not a long-term 1.0 stability promise
+
+## Development quickstart
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install --upgrade pip
+.venv/bin/pip install -e . pytest build
+make test
+make smoke
+make package-check
+```
+
+You can also call the installed script directly:
+
+```bash
+.venv/bin/aictx --help
+```
+
+Public release validation also checks clean wheel installation, not just editable installs.
+
+## Read next
+
+- [Usage guide](docs/USAGE.md)
+- [Technical overview](docs/TECHNICAL_OVERVIEW.md)
+- [5-minute demo](docs/DEMO.md)
+- [Current limitations](docs/LIMITATIONS.md)
+- [Phase 2 notes](docs/PHASE2_NOTES.md)
+- [Release checklist](docs/RELEASE_CHECKLIST.md)

aictx-0.3.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aictx"
+version = "0.3.0"
+description = "Repo-native runtime contract and context bootstrapper for coding agents"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+  { name = "Santi Santamaria" }
+]
+license = "MIT"
+keywords = ["ai", "llm", "coding-agents", "developer-tools", "context-engine", "codex", "claude"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Development Status :: 4 - Beta"
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/oldskultxo/aictx"
+Repository = "https://github.com/oldskultxo/aictx"
+Issues = "https://github.com/oldskultxo/aictx/issues"
+
+[project.scripts]
+aictx = "aictx.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"aictx" = ["templates/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

aictx-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aictx-0.3.0/src/aictx/__init__.py

@@ -0,0 +1,4 @@
+from ._version import __version__
+from .middleware import finalize_execution, prepare_execution
+
+__all__ = ["__version__", "prepare_execution", "finalize_execution"]

aictx-0.3.0/src/aictx/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

aictx-0.3.0/src/aictx/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

aictx-0.3.0/src/aictx/adapters.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import stat
+from pathlib import Path
+from typing import Any
+
+from .state import ENGINE_HOME, REPO_ADAPTERS_DIR, write_json, read_json
+
+GLOBAL_ADAPTERS_DIR = ENGINE_HOME / "adapters"
+GLOBAL_ADAPTERS_REGISTRY_PATH = GLOBAL_ADAPTERS_DIR / "registry.json"
+GLOBAL_ADAPTERS_BIN_DIR = GLOBAL_ADAPTERS_DIR / "bin"
+GLOBAL_ADAPTERS_INSTALL_STATUS_PATH = GLOBAL_ADAPTERS_DIR / "install_status.json"
+
+
+def adapter_runtime_contract(adapter_id: str) -> dict[str, Any]:
+    return {
+        "runtime_entrypoint": "aictx internal run-execution",
+        "integration_mode": "wrapper",
+        "auto_prepare_finalize": True,
+        "requires_request_context": True,
+        "wrapper_env": [
+            "AICTX_REQUEST",
+            "AICTX_REPO",
+            "AICTX_EXECUTION_ID",
+            "AICTX_AGENT_ID",
+            "AICTX_TASK_TYPE",
+            "AICTX_EXECUTION_MODE",
+            "AICTX_VALIDATED_LEARNING",
+        ],
+        "wrapper_script_name": f"aictx-{adapter_id}-auto",
+    }
+
+
+def adapter_profiles() -> dict[str, dict[str, Any]]:
+    return {
+        "generic": {
+            "adapter_id": "generic",
+            "display_name": "Generic multi-LLM runner",
+            "family": "multi_llm",
+            "middleware_always_on": True,
+            "explicit_skill_metadata": False,
+            "structured_skill_metadata": True,
+            "heuristic_skill_fallback": True,
+            "auto_installed": True,
+            "runtime_contract": adapter_runtime_contract("generic"),
+        },
+        "codex": {
+            "adapter_id": "codex",
+            "display_name": "OpenAI Codex",
+            "family": "openai_codex",
+            "middleware_always_on": True,
+            "explicit_skill_metadata": True,
+            "structured_skill_metadata": True,
+            "heuristic_skill_fallback": True,
+            "expected_skill_metadata_fields": ["skill_id", "skill_name", "skill_path", "source"],
+            "auto_installed": True,
+            "runtime_contract": adapter_runtime_contract("codex"),
+        },
+        "claude": {
+            "adapter_id": "claude",
+            "display_name": "Anthropic Claude",
+            "family": "anthropic_claude",
+            "middleware_always_on": True,
+            "explicit_skill_metadata": True,
+            "structured_skill_metadata": True,
+            "heuristic_skill_fallback": True,
+            "expected_skill_metadata_fields": ["skill_id", "skill_name", "skill_path", "source"],
+            "auto_installed": True,
+            "runtime_contract": adapter_runtime_contract("claude"),
+        },
+    }
+
+
+def adapter_registry_payload(scope: str) -> dict[str, Any]:
+    profiles = adapter_profiles()
+    return {
+        "version": 1,
+        "scope": scope,
+        "default_adapter_id": "generic",
+        "supported_adapters": sorted(profiles.keys()),
+        "middleware_mode": "always_on",
+        "skill_detection_contract": {
+            "authoritative_signal": "explicit_runner_metadata",
+            "structured_fallback": True,
+            "heuristic_fallback": True,
+        },
+        "runtime_contract": {
+            "entrypoint": "aictx internal run-execution",
+            "integration_mode": "wrapper",
+            "supported_runners": sorted(profiles.keys()),
+        },
+    }
+
+
+def write_executable(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def render_wrapper_script(adapter_id: str) -> str:
+    return f"""#!/bin/sh
+set -eu
+REQUEST="${{AICTX_REQUEST:-}}"
+if [ -z "$REQUEST" ]; then
+  echo "AICTX_REQUEST must be set for {adapter_id} auto wrapper." >&2
+  exit 64
+fi
+REPO="${{AICTX_REPO:-.}}"
+EXEC_ID="${{AICTX_EXECUTION_ID:-auto}}"
+AGENT_ID="${{AICTX_AGENT_ID:-{adapter_id}}}"
+TASK_TYPE="${{AICTX_TASK_TYPE:-}}"
+EXEC_MODE="${{AICTX_EXECUTION_MODE:-plain}}"
+VALIDATED="${{AICTX_VALIDATED_LEARNING:-0}}"
+if [ "$VALIDATED" = "1" ] || [ "$VALIDATED" = "true" ]; then
+  VALIDATED_FLAG="--validated-learning"
+else
+  VALIDATED_FLAG=""
+fi
+if [ -n "$TASK_TYPE" ]; then
+  exec aictx internal run-execution --repo "$REPO" --request "$REQUEST" --agent-id "$AGENT_ID" --adapter-id "{adapter_id}" --execution-id "$EXEC_ID" --execution-mode "$EXEC_MODE" $VALIDATED_FLAG --task-type "$TASK_TYPE" -- "$@"
+fi
+exec aictx internal run-execution --repo "$REPO" --request "$REQUEST" --agent-id "$AGENT_ID" --adapter-id "{adapter_id}" --execution-id "$EXEC_ID" --execution-mode "$EXEC_MODE" $VALIDATED_FLAG -- "$@"
+"""
+
+
+def install_adapter_wrappers() -> list[Path]:
+    created: list[Path] = []
+    GLOBAL_ADAPTERS_BIN_DIR.mkdir(parents=True, exist_ok=True)
+    for adapter_id in sorted(adapter_profiles().keys()):
+        wrapper_name = adapter_runtime_contract(adapter_id)["wrapper_script_name"]
+        path = GLOBAL_ADAPTERS_BIN_DIR / wrapper_name
+        write_executable(path, render_wrapper_script(adapter_id))
+        created.append(path)
+    return created
+
+
+def adapter_install_status_payload(wrapper_paths: list[Path]) -> dict[str, Any]:
+    profiles = adapter_profiles()
+    wrappers = {
+        adapter_id: str(GLOBAL_ADAPTERS_BIN_DIR / profiles[adapter_id]["runtime_contract"]["wrapper_script_name"])
+        for adapter_id in sorted(profiles.keys())
+    }
+    return {
+        "version": 1,
+        "engine_home": str(ENGINE_HOME),
+        "integration_mode": "wrapper",
+        "runtime_entrypoint": "aictx internal run-execution",
+        "supported_runners": sorted(profiles.keys()),
+        "wrappers": wrappers,
+        "artifacts": [str(path) for path in wrapper_paths],
+        "status": "wrapper_ready",
+    }
+
+
+def install_global_adapters() -> list[Path]:
+    GLOBAL_ADAPTERS_DIR.mkdir(parents=True, exist_ok=True)
+    write_json(GLOBAL_ADAPTERS_REGISTRY_PATH, adapter_registry_payload("global"))
+    created = [GLOBAL_ADAPTERS_REGISTRY_PATH]
+    for adapter_id, payload in adapter_profiles().items():
+        path = GLOBAL_ADAPTERS_DIR / f"{adapter_id}.json"
+        write_json(path, payload)
+        created.append(path)
+    wrapper_paths = install_adapter_wrappers()
+    created.extend(wrapper_paths)
+    write_json(GLOBAL_ADAPTERS_INSTALL_STATUS_PATH, adapter_install_status_payload(wrapper_paths))
+    created.append(GLOBAL_ADAPTERS_INSTALL_STATUS_PATH)
+    return created
+
+
+def install_repo_adapters(repo: Path) -> list[Path]:
+    adapters_dir = repo / REPO_ADAPTERS_DIR
+    adapters_dir.mkdir(parents=True, exist_ok=True)
+    registry_path = adapters_dir / "registry.json"
+    write_json(registry_path, adapter_registry_payload("repo"))
+    created = [registry_path]
+    for adapter_id, payload in adapter_profiles().items():
+        path = adapters_dir / f"{adapter_id}.json"
+        write_json(path, payload)
+        created.append(path)
+    return created
+
+
+def resolve_adapter_profile(adapter_id: str | None, agent_id: str | None = None, repo_root: Path | None = None) -> dict[str, Any]:
+    requested = str(adapter_id or "").strip().lower()
+    agent = str(agent_id or "").strip().lower()
+    profiles = adapter_profiles()
+    resolved_id = requested if requested in profiles else "generic"
+    if resolved_id == "generic":
+        if "codex" in requested or "codex" in agent:
+            resolved_id = "codex"
+        elif "claude" in requested or "claude" in agent:
+            resolved_id = "claude"
+    if repo_root:
+        repo_path = repo_root / REPO_ADAPTERS_DIR / f"{resolved_id}.json"
+        if repo_path.exists():
+            payload = read_json(repo_path, {})
+            if payload:
+                return payload
+    return dict(profiles[resolved_id])