diff --git a/.claude/.codebase-info/.map-state.json b/.claude/.codebase-info/.map-state.json index 4d85b422..268e8a2f 100644 --- a/.claude/.codebase-info/.map-state.json +++ b/.claude/.codebase-info/.map-state.json @@ -2,7 +2,7 @@ "tool": "codebase-mapper", "version": "2.8.0", "mappedAt": "2026-07-18", - "gitCommit": "7e85456d9984483b29211bff1dd98820409e9635", + "gitCommit": "ffcdca567bd460af080734598762112a9af6857e", "documents": [ "architecture.md", "tech-landscape.md", @@ -18,8 +18,8 @@ "hashes": { "INDEX.md": "17eaa0ba82f159465e126597aac349c6e4429330887b58742636734e15854313", "architecture.md": "7c908f047e6b0f08824ccd7c3f674ad47bd547dde234d0bd424a6d2784c0cbb6", - "tech-landscape.md": "a9052f4bba3742e79556a49c888424e6d9de424970e9def440c7124f45ec6a41", - "directory-structure.md": "ecf7e3357b41a83e7f31e760db41ef0bcb4fdbc6f1d61bbb4daf896f425d6657", + "tech-landscape.md": "cad1a11e5e63013a10cf07657d248196d0e3e4e14203eba7b777c1c123628198", + "directory-structure.md": "7d04bf29e9005508af316e29ded0c2f082a8dca561a279faecbc682f3bf5db6f", "entry-points.md": "6bd4ccae3d975196e03fc2c4e86007eba89f1f6427232fd8adce78ec97d6b432", "modules.md": "1238c76664edb1c1667fda23f39507bcab5b760b57a3a3728d7104b2cf8032e7", "communication.md": "49741a7455b0f162881e1cfb2d797dc8e3832cc8782796bbcb8a10529f2c5a0b", diff --git a/.claude/.codebase-info/directory-structure.md b/.claude/.codebase-info/directory-structure.md index 592fc545..31ad83d7 100644 --- a/.claude/.codebase-info/directory-structure.md +++ b/.claude/.codebase-info/directory-structure.md @@ -22,8 +22,9 @@ 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/ # generate_llms_files.py (llms-*.txt bundles for the docs site) +├── scripts/ # generate_llms_files.py (llms.txt index + llms-*.txt bundles) ├── pyproject.toml # package metadata, deps, [tool.black], uv workspace +├── context7.json # Context7 indexing config + v2 API rules for AI assistants ├── build_and_deploy.ps1 # version bump + uv build/publish ├── AGENTS.md # the project's own design philosophy (imported by CLAUDE.md) └── README.md diff --git a/.claude/.codebase-info/tech-landscape.md b/.claude/.codebase-info/tech-landscape.md index ecd868d0..7b7d928b 100644 --- a/.claude/.codebase-info/tech-landscape.md +++ b/.claude/.codebase-info/tech-landscape.md @@ -39,9 +39,9 @@ `pytest --cov=atomic_agents` across `atomic-agents`, `atomic-assembler`, `atomic-examples`, `atomic-forge`. - `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`. + `scripts/generate_llms_files.py` (spec-compliant `llms.txt` index + `llms-*.txt` + bundles, copied to the site root), 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. diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index 655ac179..1b625da2 100644 --- a/.claude/skills/release/SKILL.md +++ b/.claude/skills/release/SKILL.md @@ -2,6 +2,8 @@ name: release description: Release a new version of atomic-agents to PyPI and GitHub. Use when the user asks to "release", "publish", "deploy", or "bump version" for atomic-agents. allowed-tools: Read, Bash, Grep, Glob +metadata: + internal: true --- # Release Process for atomic-agents diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 5b7f0816..89e8df09 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -57,11 +57,16 @@ jobs: cd docs uv run make html + - name: Place llms files at site root + run: | + cp docs/llms.txt docs/llms-*.txt docs/_build/html/ + - name: Verify llms files in build run: | - echo "Checking for llms files in build directory:" + echo "Checking for llms files at site root:" + ls -lh docs/_build/html/llms*.txt + echo "Checking for llms files in _static (download links):" ls -lh docs/_build/html/_static/llms-*.txt || echo "Files not in _static" - ls -lh docs/_build/html/_downloads/*/llms-*.txt || echo "Files not in _downloads" - name: Upload artifact uses: actions/upload-pages-artifact@v3 diff --git a/README.md b/README.md index 094ed797..d0fed80d 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,9 @@ Built on [Instructor](https://github.com/jxnl/instructor) and [Pydantic](https:/ - [Examples \& Documentation](#examples--documentation) - [Quickstart Examples](#quickstart-examples) - [Complete Examples](#complete-examples) + - [AI-Assisted Development](#ai-assisted-development) + - [Agent skills (Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, ...)](#agent-skills-claude-code-cursor-copilot-codex-windsurf-gemini-cli-) + - [Docs for LLMs](#docs-for-llms) - [🚀 Version 2.0 Released!](#-version-20-released) - [Key Changes in v2.0:](#key-changes-in-v20) - [⚠️ Upgrading from v1.x](#️-upgrading-from-v1x) @@ -293,6 +296,35 @@ In addition to the quickstart examples, we have more complex examples demonstrat For a complete list of examples, see the [examples directory](/atomic-examples/). +## AI-Assisted Development + +Building with an AI coding assistant? Atomic Agents ships first-class support so your assistant knows the framework's current API and conventions instead of guessing. + +### Agent skills (Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, ...) + +Six [agent skills](https://agents.md/) cover the framework: an auto-triggering `framework` guide with progressive-disclosure references, four creation workflows (`create-atomic-schema`, `create-atomic-agent`, `create-atomic-tool`, `create-atomic-context-provider`), and a `new-app` project scaffolder. + +**Claude Code** (also gets the `atomic-explorer` and `atomic-reviewer` subagents): + +``` +/plugin marketplace add eigenwise/atomic-agents +/plugin install atomic-agents@eigenwise +``` + +**Any other skills-compatible assistant:** + +```bash +npx skills add eigenwise/atomic-agents +``` + +See [claude-plugin/atomic-agents](./claude-plugin/atomic-agents/README.md) for details. + +### Docs for LLMs + +The [documentation site](https://eigenwise.github.io/atomic-agents/) publishes LLM-ready bundles: [llms-full.txt](https://eigenwise.github.io/atomic-agents/llms-full.txt) (docs + source + examples), plus separate [docs](https://eigenwise.github.io/atomic-agents/llms-docs.txt), [source](https://eigenwise.github.io/atomic-agents/llms-source.txt), and [examples](https://eigenwise.github.io/atomic-agents/llms-examples.txt) bundles. Point your assistant at one of these when it needs the full picture. + +Atomic Agents is also indexed on [Context7](https://context7.com/eigenwise/atomic-agents) for assistants with the Context7 MCP server. + ## Atomic Forge & CLI Atomic Forge is a collection of tools that can be used with Atomic Agents to extend its functionality. Current tools include: diff --git a/claude-plugin/atomic-agents/README.md b/claude-plugin/atomic-agents/README.md index c41e0886..24eabc33 100644 --- a/claude-plugin/atomic-agents/README.md +++ b/claude-plugin/atomic-agents/README.md @@ -54,6 +54,16 @@ To require this plugin for everyone who opens a given repo, add it to the projec Claude Code prompts each teammate to install on first trust of the folder. +### Other coding assistants (Cursor, Copilot, Codex, Windsurf, Gemini CLI, ...) + +The skills follow the cross-tool [agent skills](https://agents.md/) format, so any skills-compatible assistant can install them without the Claude Code plugin system: + +```bash +npx skills add eigenwise/atomic-agents +``` + +This installs the six skills (framework guide, four create-* workflows, new-app scaffolder). The `atomic-explorer` and `atomic-reviewer` subagents are Claude Code plugin features and don't travel this path. + ### Local dev ```bash diff --git a/context7.json b/context7.json new file mode 100644 index 00000000..12a1fda4 --- /dev/null +++ b/context7.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://context7.com/schema/context7.json", + "projectTitle": "Atomic Agents", + "description": "Lightweight, modular Python framework for building agentic AI applications with typed Pydantic schemas and Instructor", + "branch": "main", + "excludeFolders": [".claude", ".github", "docs/_build", "**/__pycache__"], + "excludeFiles": ["CHANGELOG.md"], + "rules": [ + "Import from the top-level package: from atomic_agents import AtomicAgent, AgentConfig, BaseIOSchema, BaseTool. Legacy paths like atomic_agents.lib.* were removed in v2.", + "Construct agents as AtomicAgent[InputSchema, OutputSchema](config=AgentConfig(...)). The type parameters carry runtime information, so write them explicitly.", + "Always wrap the provider SDK client with Instructor (instructor.from_openai, instructor.from_anthropic, ...) before passing it as AgentConfig.client.", + "Every BaseIOSchema subclass requires a non-empty docstring; the docstring and Field descriptions flow into the LLM prompt.", + "Provider parameters (temperature, max_tokens, reasoning_effort) go in AgentConfig.model_api_parameters, not on the agent.", + "For Gemini set assistant_role='model' and match AgentConfig.mode to the Instructor factory mode; Anthropic requires max_tokens in model_api_parameters." + ] +} diff --git a/scripts/generate_llms_files.py b/scripts/generate_llms_files.py index 6fb22945..c497de70 100644 --- a/scripts/generate_llms_files.py +++ b/scripts/generate_llms_files.py @@ -22,11 +22,14 @@ SINGLEHTML_DIR = DOCS_DIR / "_build" / "singlehtml" # Output files +OUTPUT_INDEX = DOCS_DIR / "llms.txt" OUTPUT_DOCS = DOCS_DIR / "llms-docs.txt" OUTPUT_SOURCE = DOCS_DIR / "llms-source.txt" OUTPUT_EXAMPLES = DOCS_DIR / "llms-examples.txt" OUTPUT_FULL = DOCS_DIR / "llms-full.txt" +SITE_URL = "https://eigenwise.github.io/atomic-agents" + # File extensions to include in source code SOURCE_CODE_EXTENSIONS = {'.py', '.md', '.txt', '.yml', '.yaml', '.toml', '.cfg', '.ini', '.json'} @@ -240,6 +243,46 @@ def generate_full_content() -> str: return content +def generate_index() -> str: + """Generate the llms.txt index per the llmstxt.org spec: a small Markdown + navigation file at the site root pointing to the full bundles and key pages.""" + return f"""# Atomic Agents + +> Atomic Agents is a lightweight, modular Python framework for building agentic AI applications +> as composable, schema-driven building blocks. Built on Instructor and Pydantic: every agent is +> a typed transformer from an input schema to an output schema, with full developer control and +> no hidden abstractions. Provider-agnostic (OpenAI, Anthropic, Groq, Gemini, Ollama, and more). + +Key API facts: import from the top-level `atomic_agents` package (`AtomicAgent`, `AgentConfig`, +`BaseIOSchema`, `BaseTool`) and from `atomic_agents.context` (`ChatHistory`, +`SystemPromptGenerator`, `BaseDynamicContextProvider`). Agents are constructed as +`AtomicAgent[InputSchema, OutputSchema](config=AgentConfig(...))` with an Instructor-wrapped +client. Every `BaseIOSchema` subclass requires a docstring. Python 3.12+. + +## Documentation + +- [Quickstart guide]({SITE_URL}/guides/quickstart.html): first agent, providers, streaming +- [Tools guide]({SITE_URL}/guides/tools.html): BaseTool, Atomic Forge, MCP interop +- [Orchestration guide]({SITE_URL}/guides/orchestration.html): multi-agent patterns +- [Memory guide]({SITE_URL}/guides/memory.html): ChatHistory, persistence, custom backends +- [Hooks guide]({SITE_URL}/guides/hooks.html): telemetry, retries, error handling +- [API reference]({SITE_URL}/api/index.html): full API documentation + +## Bundles + +- [llms-full.txt]({SITE_URL}/llms-full.txt): complete documentation, framework source code, and all examples in one file +- [llms-docs.txt]({SITE_URL}/llms-docs.txt): documentation only +- [llms-source.txt]({SITE_URL}/llms-source.txt): framework source code only +- [llms-examples.txt]({SITE_URL}/llms-examples.txt): runnable example projects only + +## Optional + +- [GitHub repository](https://github.com/eigenwise/atomic-agents): source, issues, discussions +- [Agent skills](https://github.com/eigenwise/atomic-agents/tree/main/claude-plugin/atomic-agents): installable skills for coding assistants (`npx skills add eigenwise/atomic-agents`) +- [PyPI package](https://pypi.org/project/atomic-agents/): `pip install atomic-agents` +""" + + def write_to_file_and_copy(output_file: Path, content: str): """Write content to file and copy to HTML build directory if it exists.""" with open(output_file, "w", encoding="utf-8") as f: @@ -277,6 +320,10 @@ def main(): print("\nGenerating llms-full.txt...") full_content = generate_full_content() write_to_file_and_copy(OUTPUT_FULL, full_content) + + # Generate the spec-compliant index + print("\nGenerating llms.txt index...") + write_to_file_and_copy(OUTPUT_INDEX, generate_index()) print("\n" + "=" * 40) print("Successfully generated all llms.txt files!")