From 7e85456d9984483b29211bff1dd98820409e9635 Mon Sep 17 00:00:00 2001 From: Eigenwise Date: Sat, 18 Jul 2026 10:17:11 +0200 Subject: [PATCH 1/2] Fix stale AI-facing docs: AGENTS.md v2 API, version drift, file casing AGENTS.md was teaching a v1-style API that no longer exists: the AtomicAgent(system_prompt=..., input_schema=...) constructor, a context_providers list kwarg, and imports from atomic_agents.base. Any coding agent reading the repo got a constructor signature that won't run. Examples rewritten to the real v2 API (AgentConfig, AtomicAgent[In, Out] generics, Instructor-wrapped client, register_context_provider) and verified against the installed framework. Stale component list (lib/, memory/, prompting/, services/) replaced with the actual package layout, hardcoded version removed. The file was also tracked as lowercase agents.md, so @AGENTS.md in CLAUDE.md and tools probing for AGENTS.md missed it on case-sensitive checkouts. Renamed in the index. docs/conf.py now reads the version from the root pyproject.toml directly (was hardcoded at 2.0.4, actual 2.9.1), which retires scripts/sync_version.py and its CI step. Plugin CHANGELOG gains the missing 2.1.0 entry (create-* skills, reviewer model-name fix) plus an Unreleased section for the rebrand, MiniMax M3 default, and the Copilot CLI argument-hint fix. Also drops a duplicated Star History heading in README. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/docs.yml | 4 -- agents.md => AGENTS.md | 72 +++++++++++++++--------- README.md | 2 - claude-plugin/atomic-agents/CHANGELOG.md | 21 +++++++ docs/conf.py | 8 ++- scripts/sync_version.py | 63 --------------------- 6 files changed, 73 insertions(+), 97 deletions(-) rename agents.md => AGENTS.md (85%) delete mode 100644 scripts/sync_version.py diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 01261df8..5b7f0816 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -38,10 +38,6 @@ jobs: run: | uv sync - - name: Sync version from pyproject.toml - run: | - uv run python scripts/sync_version.py - - name: Build singlehtml for documentation extraction run: | cd docs diff --git a/agents.md b/AGENTS.md similarity index 85% rename from agents.md rename to AGENTS.md index e925db17..d9e4b7ca 100644 --- a/agents.md +++ b/AGENTS.md @@ -40,19 +40,15 @@ atomic-monorepo/ ### 1. atomic-agents/ - Core Framework -**Published as:** `atomic-agents` on PyPI -**Current Version:** 2.2.2 +**Published as:** `atomic-agents` on PyPI (version lives in the root `pyproject.toml`) **Purpose:** Main Python package containing all core framework components **Key Components:** - `agents/` - AtomicAgent class and agent configuration -- `base/` - Base abstractions (BaseIOSchema, BaseTool, BasePrompt, BaseResource) -- `context/` - Chat history and system prompt generation +- `base/` - Base abstractions (BaseIOSchema, BaseTool, BaseToolConfig) +- `context/` - ChatHistory, SystemPromptGenerator, dynamic context providers - `connectors/` - External integrations (MCP support) -- `lib/` - Extended library components (components, factories, utils) -- `memory/` - Memory management systems -- `prompting/` - Prompt engineering utilities -- `services/` - Service integrations +- `utils/` - Shared utilities (token counting, formatting) **Installation:** ```bash @@ -138,14 +134,18 @@ Every Atomic Agent consists of: All data flows through typed Pydantic schemas: ```python -from atomic_agents.base import BaseIOSchema +from atomic_agents import BaseIOSchema from pydantic import Field class CustomOutputSchema(BaseIOSchema): + """Response with follow-up suggestions.""" + chat_message: str = Field(..., description="The response message") suggested_questions: list[str] = Field(..., description="Follow-up questions") ``` +Every `BaseIOSchema` subclass requires a non-empty docstring — the framework enforces this at class-definition time, and the docstring plus field descriptions flow into the LLM prompt via Instructor. + ### Composability Pattern Agents can be chained by connecting output schemas to input schemas: @@ -161,15 +161,21 @@ This creates predictable data flow pipelines with type safety at each step. Dynamic context injection pattern allows runtime enhancement of prompts without modifying agent code: ```python -context_provider = CustomContextProvider() -agent = AtomicAgent( - system_prompt=prompt, - input_schema=InputSchema, - output_schema=OutputSchema, - context_providers=[context_provider] # Inject runtime context -) +from atomic_agents.context import BaseDynamicContextProvider + +class SearchResultsProvider(BaseDynamicContextProvider): + def __init__(self, title: str): + super().__init__(title=title) + self.results: list[str] = [] + + def get_info(self) -> str: + return "\n".join(self.results) + +agent.register_context_provider("search_results", SearchResultsProvider("Search Results")) ``` +Providers can also be passed up front via `SystemPromptGenerator(context_providers={...})`. `get_info()` runs on every `agent.run()`, so keep it free of blocking I/O. + ### Model Context Protocol (MCP) Full support for MCP enables connection to external tools and resources through standardized interfaces: @@ -324,32 +330,46 @@ Recent improvements include: ## Quick Start ```python -from atomic_agents import AtomicAgent -from atomic_agents.base import BaseIOSchema +import os + +import instructor +import openai from pydantic import Field -# Define schemas +from atomic_agents import AgentConfig, AtomicAgent, BaseIOSchema +from atomic_agents.context import ChatHistory, SystemPromptGenerator + class InputSchema(BaseIOSchema): + """User's question for the agent.""" + query: str = Field(..., description="User's question") class OutputSchema(BaseIOSchema): + """Agent's answer with a confidence estimate.""" + answer: str = Field(..., description="Agent's response") confidence: float = Field(..., description="Confidence score 0-1") -# Create agent -agent = AtomicAgent( - system_prompt="You are a helpful assistant. Provide accurate answers.", - input_schema=InputSchema, - output_schema=OutputSchema, - model="gpt-5-mini", +client = instructor.from_openai(openai.OpenAI(api_key=os.environ["OPENAI_API_KEY"])) + +agent = AtomicAgent[InputSchema, OutputSchema]( + config=AgentConfig( + client=client, + model="gpt-5-mini", + history=ChatHistory(), + system_prompt_generator=SystemPromptGenerator( + background=["You are a helpful assistant. Provide accurate answers."], + ), + ) ) -# Run agent result = agent.run(InputSchema(query="What is atomic computing?")) print(result.answer) print(f"Confidence: {result.confidence}") ``` +The type parameters on `AtomicAgent[In, Out]` carry runtime information (they drive Instructor's `response_model`), so write them explicitly and keep them accurate. The client must always be wrapped with Instructor — a raw provider SDK client will not enforce output schemas. + --- ## Philosophy Summary diff --git a/README.md b/README.md index fb2b8bf6..094ed797 100644 --- a/README.md +++ b/README.md @@ -410,8 +410,6 @@ If you want to learn more about the motivation and philosophy behind Atomic Agen ## Star History -## Star History - diff --git a/claude-plugin/atomic-agents/CHANGELOG.md b/claude-plugin/atomic-agents/CHANGELOG.md index 57f84dfd..2819cf65 100644 --- a/claude-plugin/atomic-agents/CHANGELOG.md +++ b/claude-plugin/atomic-agents/CHANGELOG.md @@ -5,6 +5,27 @@ All notable changes to the Atomic Agents Claude Code Plugin will be documented i The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Changed + +- Rebranded BrainBlend → Eigenwise: marketplace name, URLs, and install docs now point at the `eigenwise` GitHub home. Install via `/plugin marketplace add eigenwise/atomic-agents`. +- `new-app` MiniMax default model updated to MiniMax M3. + +### Fixed + +- Quoted `argument-hint` YAML values in skill frontmatter so GitHub Copilot CLI ≥1.0.65 loads all skills ([#265](https://github.com/eigenwise/atomic-agents/pull/265)). + +## [2.1.0] - 2026-04-29 + +### Added + +- Four action-oriented creation skills: `create-atomic-schema`, `create-atomic-agent`, `create-atomic-tool`, `create-atomic-context-provider`. Each walks a clarify → write → verify → hand-off workflow for its component type, auto-triggering on the matching phrasing ("create a schema", "add a tool", ...). The `framework` skill and `new-app` scaffolder route to them instead of duplicating the material. + +### Fixed + +- `atomic-reviewer` no longer flags current-generation model names as errors. + ## [2.0.1] - 2026-04-16 Bug-fix release addressing two recurring false positives from `atomic-reviewer` reported in [issue #238](https://github.com/eigenwise/atomic-agents/issues/238). diff --git a/docs/conf.py b/docs/conf.py index 9a19ac09..7eded9d4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,13 +1,17 @@ import os import sys +import tomllib +from pathlib import Path sys.path.insert(0, os.path.abspath("..")) project = "Atomic Agents" copyright = "2026, Kenny Vaneetvelde" author = "Kenny Vaneetvelde" -version = "2.0.4" -release = "2.0.4" + +with open(Path(__file__).resolve().parent.parent / "pyproject.toml", "rb") as f: + version = tomllib.load(f)["project"]["version"] +release = version extensions = [ "sphinx.ext.autodoc", diff --git a/scripts/sync_version.py b/scripts/sync_version.py deleted file mode 100644 index adbd325b..00000000 --- a/scripts/sync_version.py +++ /dev/null @@ -1,63 +0,0 @@ -#!/usr/bin/env python3 -""" -Sync version from pyproject.toml to docs/conf.py -""" - -import re -from pathlib import Path - -# Define paths -PROJECT_ROOT = Path(__file__).parent.parent -PYPROJECT_FILE = PROJECT_ROOT / "pyproject.toml" -DOCS_CONF_FILE = PROJECT_ROOT / "docs" / "conf.py" - -def get_version_from_pyproject(): - """Extract version from pyproject.toml using regex""" - with open(PYPROJECT_FILE, 'r') as f: - content = f.read() - - # Look for version line in [project] section - match = re.search(r'^version = ["\'](.*?)["\']', content, re.MULTILINE) - if match: - return match.group(1) - else: - raise ValueError("Could not find version in pyproject.toml") - -def update_docs_conf(version): - """Update version in docs/conf.py""" - with open(DOCS_CONF_FILE, 'r') as f: - content = f.read() - - # Replace version line - content = re.sub( - r'^version = "[^"]*"$', - f'version = "{version}"', - content, - flags=re.MULTILINE - ) - - # Replace release line - content = re.sub( - r'^release = "[^"]*"$', - f'release = "{version}"', - content, - flags=re.MULTILINE - ) - - with open(DOCS_CONF_FILE, 'w') as f: - f.write(content) - - print(f"Updated docs/conf.py to version {version}") - -def main(): - """Main function""" - try: - version = get_version_from_pyproject() - print(f"Found version {version} in pyproject.toml") - update_docs_conf(version) - except Exception as e: - print(f"Error: {e}") - exit(1) - -if __name__ == "__main__": - main() \ No newline at end of file From 58cb042292620333655ddefb68963b584f195136 Mon Sep 17 00:00:00 2001 From: Eigenwise Date: Sat, 18 Jul 2026 10:18:45 +0200 Subject: [PATCH 2/2] Update codebase map: retire sync_version.py, bump version refs, add hash manifest Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/.codebase-info/.map-state.json | 21 +++++++++++++++---- .claude/.codebase-info/INDEX.md | 4 ++-- .claude/.codebase-info/directory-structure.md | 4 ++-- .claude/.codebase-info/tech-landscape.md | 6 ++++-- 4 files changed, 25 insertions(+), 10 deletions(-) diff --git a/.claude/.codebase-info/.map-state.json b/.claude/.codebase-info/.map-state.json index 2d058f09..4d85b422 100644 --- a/.claude/.codebase-info/.map-state.json +++ b/.claude/.codebase-info/.map-state.json @@ -1,8 +1,8 @@ { "tool": "codebase-mapper", - "version": "2.0.0", - "mappedAt": "2026-07-05", - "gitCommit": "28099f5aa6eccb491c66be4bcd22532f15bb407f", + "version": "2.8.0", + "mappedAt": "2026-07-18", + "gitCommit": "7e85456d9984483b29211bff1dd98820409e9635", "documents": [ "architecture.md", "tech-landscape.md", @@ -14,5 +14,18 @@ "patterns.md", "coding-style.md", "onboarding.md" - ] + ], + "hashes": { + "INDEX.md": "17eaa0ba82f159465e126597aac349c6e4429330887b58742636734e15854313", + "architecture.md": "7c908f047e6b0f08824ccd7c3f674ad47bd547dde234d0bd424a6d2784c0cbb6", + "tech-landscape.md": "a9052f4bba3742e79556a49c888424e6d9de424970e9def440c7124f45ec6a41", + "directory-structure.md": "ecf7e3357b41a83e7f31e760db41ef0bcb4fdbc6f1d61bbb4daf896f425d6657", + "entry-points.md": "6bd4ccae3d975196e03fc2c4e86007eba89f1f6427232fd8adce78ec97d6b432", + "modules.md": "1238c76664edb1c1667fda23f39507bcab5b760b57a3a3728d7104b2cf8032e7", + "communication.md": "49741a7455b0f162881e1cfb2d797dc8e3832cc8782796bbcb8a10529f2c5a0b", + "dependencies.md": "b445a920c121e27006fec824add6865d01cf71212a517e5ff8b2058d3999037a", + "patterns.md": "12b96c2d4f8bc7507bcae39b2b385b9db4d0dec95ef6a2049958663aff021705", + "coding-style.md": "2f939544333b927cf8731f5bb906ce03cb3a46afa50c9735011ff8f7e4caca9e", + "onboarding.md": "3d28c671dc095a2aadb297bd7ab200c677779a99c7534e03e55a3d64c935f07e" + } } diff --git a/.claude/.codebase-info/INDEX.md b/.claude/.codebase-info/INDEX.md index 7274c311..b99e8ac1 100644 --- a/.claude/.codebase-info/INDEX.md +++ b/.claude/.codebase-info/INDEX.md @@ -1,6 +1,6 @@ # Codebase Map — Atomic Agents -*Last Updated: 2026-06-13* +*Last Updated: 2026-07-18* Atomic Agents is a lightweight, modular Python framework for building agentic AI applications as composable, schema-driven building blocks (built on Instructor + Pydantic). This repository is a @@ -8,7 +8,7 @@ composable, schema-driven building blocks (built on Instructor + Pydantic). This **Stack:** Python ≥3.12 · Instructor · Pydantic v2 · LiteLLM · MCP · Textual · uv + Hatchling **Shape:** Monorepo — `atomic-agents/` (core lib) · `atomic-assembler/` (CLI) · `atomic-forge/` (tools) · `atomic-examples/` (examples) -**Package:** `atomic-agents` v2.8.1 on PyPI · core import package is `atomic_agents` +**Package:** `atomic-agents` v2.9.1 on PyPI · core import package is `atomic_agents` ## Documents diff --git a/.claude/.codebase-info/directory-structure.md b/.claude/.codebase-info/directory-structure.md index 6a82c412..592fc545 100644 --- a/.claude/.codebase-info/directory-structure.md +++ b/.claude/.codebase-info/directory-structure.md @@ -1,6 +1,6 @@ # Directory Structure -*Last Updated: 2026-07-05* +*Last Updated: 2026-07-18* ## Root Layout @@ -22,7 +22,7 @@ atomic-agents/ # repo root (uv workspace) ├── atomic-examples/ # 16 runnable example apps (each its own project) ├── docs/ # Sphinx + MyST documentation (api/, guides/, examples/) ├── guides/ # DEV_GUIDE.md and contributor guides -├── scripts/ # sync_version.py, generate_llms_files.py +├── scripts/ # generate_llms_files.py (llms-*.txt bundles for the docs site) ├── pyproject.toml # package metadata, deps, [tool.black], uv workspace ├── build_and_deploy.ps1 # version bump + uv build/publish ├── AGENTS.md # the project's own design philosophy (imported by CLAUDE.md) diff --git a/.claude/.codebase-info/tech-landscape.md b/.claude/.codebase-info/tech-landscape.md index ae9bdddb..ecd868d0 100644 --- a/.claude/.codebase-info/tech-landscape.md +++ b/.claude/.codebase-info/tech-landscape.md @@ -1,6 +1,6 @@ # Technology Landscape -*Last Updated: 2026-06-13* +*Last Updated: 2026-07-18* ## Source-of-Truth Files @@ -38,8 +38,10 @@ - `code-quality.yml` — on push/PR to `main`/`v2.0`: `uv sync`, `black --check`, `flake8`, then `pytest --cov=atomic_agents` across `atomic-agents`, `atomic-assembler`, `atomic-examples`, `atomic-forge`. - - `docs.yml` — on push to `main`: build Sphinx docs, run `scripts/sync_version.py` and + - `docs.yml` — on push to `main`: build Sphinx docs, run `scripts/generate_llms_files.py` (produces `llms-*.txt`), deploy to GitHub Pages. + The docs version needs no sync step — `docs/conf.py` reads it from the root + `pyproject.toml` via `tomllib`. - **Release:** `build_and_deploy.ps1 [--dry]` bumps the version in `pyproject.toml`, then `uv sync` → `uv build` → `uv publish` (requires a `PYPI_TOKEN`). - **Distribution:** PyPI package `atomic-agents`; the `atomic` console script ships with it.