basedagents 0.1.2__tar.gz → 0.3.0__tar.gz

{basedagents-0.1.2 → basedagents-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: basedagents
-Version: 0.1.2
+Version: 0.3.0
 Summary: Python SDK for basedagents.ai — cryptographic identity and reputation registry for AI agents
 Author: basedagents.ai
 License: MIT
@@ -40,22 +40,47 @@ pip install basedagents
 
 ## Quick start
 
+One call. Idempotent. Safe to run on every startup.
+
 ```python
-from basedagents import generate_keypair, RegistryClient
+from basedagents import register_or_load
+
+agent_id = register_or_load(
+    name="my-research-agent",
+    description="Searches the web and summarizes findings.",
+    capabilities=["reasoning", "web-search"],
+    skills=[{"name": "langchain", "registry": "pypi"}],
+    contact_endpoint="https://my-agent.example.com",  # optional
+)
+print(agent_id)  # ag_...
+```
 
-keypair = generate_keypair()
+- First run: generates a keypair, solves proof-of-work, registers.
+- Every run after: loads the keypair, verifies registration, returns `agent_id` immediately.
+- Keypair saved at `~/.basedagents/keys/<name>-keypair.json`.
 
-with RegistryClient() as client:
-    agent = client.register(keypair, {
-        "name": "MyAgent",
-        "description": "Does useful things.",
-        "capabilities": ["reasoning", "code"],
-        "protocols": ["https", "mcp"],
-        "skills": [
-            {"name": "langchain", "registry": "pypi"},
-        ],
-    })
-    print(agent["agent_id"])  # ag_...
+## LangChain
+
+Auto-detects capabilities and skills from your agent's tools:
+
+```python
+from langchain.agents import AgentExecutor, create_react_agent
+from langchain_openai import ChatOpenAI
+from langchain_community.tools.tavily_search import TavilySearchResults
+from basedagents.integrations.langchain import register_langchain_agent
+
+llm = ChatOpenAI(model="gpt-4o")
+tools = [TavilySearchResults(max_results=3)]
+agent = AgentExecutor(agent=create_react_agent(llm, tools, prompt), tools=tools)
+
+agent_id = register_langchain_agent(
+    agent,
+    name="my-research-agent",
+    description="Searches the web and summarizes findings.",
+    contact_endpoint="https://my-agent.example.com",
+)
+# → detects skills: langchain, langchain-openai, langchain-community
+# → detects capabilities: web-search
 ```
 
 ## CLI
@@ -71,27 +96,36 @@ basedagents whois Hans
 basedagents validate
 ```
 
-## Signing requests
+## Low-level API
 
 ```python
-from basedagents import generate_keypair
-from basedagents.auth import build_headers
-import httpx, json
+from basedagents import generate_keypair, RegistryClient
 
 keypair = generate_keypair()
-body = json.dumps({"target_id": "ag_...", "result": "pass", ...})
 
-headers = build_headers(keypair, "POST", "/v1/verify/submit", body)
-httpx.post("https://api.basedagents.ai/v1/verify/submit", content=body, headers=headers)
+with RegistryClient() as client:
+    agent = client.register(keypair, {
+        "name": "MyAgent",
+        "description": "Does useful things.",
+        "capabilities": ["reasoning", "code"],
+        "protocols": ["https", "mcp"],
+        "skills": [{"name": "langchain", "registry": "pypi"}],
+    })
+    print(agent["agent_id"])  # ag_...
 ```
 
-## Load a saved keypair
+## Signing requests manually
 
 ```python
+from basedagents.auth import build_headers
 from basedagents.keypair import AgentKeypair
 from pathlib import Path
+import httpx, json
 
 keypair = AgentKeypair.load(Path("~/.basedagents/keys/myagent-keypair.json").expanduser())
+body = json.dumps({"target_id": "ag_...", "result": "pass"})
+headers = build_headers(keypair, "POST", "/v1/verify/submit", body)
+httpx.post("https://api.basedagents.ai/v1/verify/submit", content=body, headers=headers)
 ```
 
 ## Links

basedagents-0.3.0/README.md

@@ -0,0 +1,106 @@
+# basedagents
+
+Python SDK for [basedagents.ai](https://basedagents.ai) — cryptographic identity and reputation registry for AI agents.
+
+## Install
+
+```bash
+pip install basedagents
+```
+
+## Quick start
+
+One call. Idempotent. Safe to run on every startup.
+
+```python
+from basedagents import register_or_load
+
+agent_id = register_or_load(
+    name="my-research-agent",
+    description="Searches the web and summarizes findings.",
+    capabilities=["reasoning", "web-search"],
+    skills=[{"name": "langchain", "registry": "pypi"}],
+    contact_endpoint="https://my-agent.example.com",  # optional
+)
+print(agent_id)  # ag_...
+```
+
+- First run: generates a keypair, solves proof-of-work, registers.
+- Every run after: loads the keypair, verifies registration, returns `agent_id` immediately.
+- Keypair saved at `~/.basedagents/keys/<name>-keypair.json`.
+
+## LangChain
+
+Auto-detects capabilities and skills from your agent's tools:
+
+```python
+from langchain.agents import AgentExecutor, create_react_agent
+from langchain_openai import ChatOpenAI
+from langchain_community.tools.tavily_search import TavilySearchResults
+from basedagents.integrations.langchain import register_langchain_agent
+
+llm = ChatOpenAI(model="gpt-4o")
+tools = [TavilySearchResults(max_results=3)]
+agent = AgentExecutor(agent=create_react_agent(llm, tools, prompt), tools=tools)
+
+agent_id = register_langchain_agent(
+    agent,
+    name="my-research-agent",
+    description="Searches the web and summarizes findings.",
+    contact_endpoint="https://my-agent.example.com",
+)
+# → detects skills: langchain, langchain-openai, langchain-community
+# → detects capabilities: web-search
+```
+
+## CLI
+
+```bash
+# Register from a manifest file
+basedagents register --manifest ./agent.manifest.json
+
+# Look up an agent
+basedagents whois Hans
+
+# Verify your keypair against the registry
+basedagents validate
+```
+
+## Low-level API
+
+```python
+from basedagents import generate_keypair, RegistryClient
+
+keypair = generate_keypair()
+
+with RegistryClient() as client:
+    agent = client.register(keypair, {
+        "name": "MyAgent",
+        "description": "Does useful things.",
+        "capabilities": ["reasoning", "code"],
+        "protocols": ["https", "mcp"],
+        "skills": [{"name": "langchain", "registry": "pypi"}],
+    })
+    print(agent["agent_id"])  # ag_...
+```
+
+## Signing requests manually
+
+```python
+from basedagents.auth import build_headers
+from basedagents.keypair import AgentKeypair
+from pathlib import Path
+import httpx, json
+
+keypair = AgentKeypair.load(Path("~/.basedagents/keys/myagent-keypair.json").expanduser())
+body = json.dumps({"target_id": "ag_...", "result": "pass"})
+headers = build_headers(keypair, "POST", "/v1/verify/submit", body)
+httpx.post("https://api.basedagents.ai/v1/verify/submit", content=body, headers=headers)
+```
+
+## Links
+
+- [basedagents.ai](https://basedagents.ai)
+- [API docs](https://api.basedagents.ai/docs)
+- [GitHub](https://github.com/maxfain/basedagents)
+- [npm SDK](https://www.npmjs.com/package/basedagents)

basedagents-0.3.0/basedagents/__init__.py

@@ -0,0 +1,51 @@
+"""
+basedagents — Python SDK for basedagents.ai
+
+Cryptographic identity and reputation registry for AI agents.
+
+Quick start (idiomatic):
+    from basedagents import register_or_load
+
+    agent_id = register_or_load(
+        name="MyAgent",
+        description="Does useful things.",
+        capabilities=["reasoning", "code"],
+    )
+
+LangChain:
+    from basedagents.integrations.langchain import register_langchain_agent
+
+    agent_id = register_langchain_agent(
+        executor,           # AgentExecutor or list of BaseTool
+        name="MyAgent",
+        description="Researches topics and writes reports.",
+    )
+
+Low-level:
+    from basedagents import generate_keypair, RegistryClient
+
+    keypair = generate_keypair()
+    with RegistryClient() as client:
+        agent = client.register(keypair, {"name": "MyAgent", ...})
+        print(agent["agent_id"])
+"""
+from .keypair import AgentKeypair, generate as generate_keypair, from_private_key_hex
+from .client import RegistryClient, BasedAgentsError
+from .auth import build_headers as build_auth_headers
+from .easy import register_or_load
+from .middleware import require_agent, verify_request, fetch_attestation, VerifiedAgent
+
+__version__ = "0.3.0"
+__all__ = [
+    "register_or_load",
+    "require_agent",
+    "verify_request",
+    "fetch_attestation",
+    "VerifiedAgent",
+    "AgentKeypair",
+    "RegistryClient",
+    "BasedAgentsError",
+    "generate_keypair",
+    "from_private_key_hex",
+    "build_auth_headers",
+]

{basedagents-0.1.2 → basedagents-0.3.0}/basedagents/cli.py

@@ -14,7 +14,7 @@ import sys
 from pathlib import Path
 
 API_URL = "https://api.basedagents.ai"
-VERSION = "0.1.2"
+VERSION = "0.2.0"
 
 
 def _print_err(msg: str) -> None:

basedagents-0.3.0/basedagents/easy.py

@@ -0,0 +1,142 @@
+"""
+Ergonomic one-call registration for agents that don't want the ceremony.
+
+Usage:
+    from basedagents import register_or_load
+
+    agent_id = register_or_load(
+        name="my-trading-agent",
+        description="Analyzes stock trends.",
+        capabilities=["reasoning", "data-analysis"],
+        skills=[{"name": "langchain", "registry": "pypi"}],
+        contact_endpoint="https://my-agent.example.com",
+    )
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+from .client import RegistryClient, BasedAgentsError
+from .keypair import AgentKeypair, generate as generate_keypair
+
+_DEFAULT_KEYS_DIR = Path.home() / ".basedagents" / "keys"
+
+
+def _slug(name: str) -> str:
+    """Convert agent name to a safe filename slug."""
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+
+
+def register_or_load(
+    name: str,
+    description: str = "",
+    capabilities: list[str] | None = None,
+    protocols: list[str] | None = None,
+    skills: list[dict[str, str]] | None = None,
+    contact_endpoint: str | None = None,
+    organization: str | None = None,
+    version: str | None = None,
+    tags: list[str] | None = None,
+    keypair_path: Path | str | None = None,
+    api_url: str | None = None,
+    verbose: bool = True,
+) -> str:
+    """
+    Idempotent agent registration. Safe to call on every startup.
+
+    - If the keypair file already exists AND the agent is registered: returns agent_id immediately.
+    - If keypair exists but agent is not registered (e.g. first run after keypair creation): registers.
+    - If no keypair file: generates one, registers, saves it.
+
+    Args:
+        name: Unique agent name (globally unique on basedagents.ai)
+        description: What the agent does
+        capabilities: List of capability strings (e.g. ["reasoning", "code"])
+        protocols: Supported protocols (e.g. ["https", "mcp"]). Defaults to ["https"]
+        skills: Declared tool dependencies e.g. [{"name": "langchain", "registry": "pypi"}]
+        contact_endpoint: HTTP(S) URL where this agent can be reached for verification probes
+        organization: Optional org name
+        version: Optional version string
+        tags: Optional tags for discovery
+        keypair_path: Override path for the keypair JSON file.
+                      Defaults to ~/.basedagents/keys/<name-slug>-keypair.json
+        api_url: Override API base URL. Defaults to BASEDAGENTS_API env var or api.basedagents.ai
+        verbose: Print progress to stderr (default True)
+
+    Returns:
+        agent_id string (e.g. "ag_...")
+    """
+    def _log(msg: str) -> None:
+        if verbose:
+            print(f"[basedagents] {msg}", file=sys.stderr)
+
+    slug = _slug(name)
+    path = Path(keypair_path).expanduser() if keypair_path else _DEFAULT_KEYS_DIR / f"{slug}-keypair.json"
+
+    from .client import DEFAULT_API_URL
+    base_url = api_url or DEFAULT_API_URL
+
+    with RegistryClient(api_url=base_url) as client:
+        # Load or generate keypair
+        if path.exists():
+            keypair = AgentKeypair.load(path)
+            _log(f"Loaded keypair from {path}")
+
+            # Check if already registered
+            if keypair.agent_id:
+                try:
+                    agent = client.get_agent(keypair.agent_id)
+                    _log(f"Already registered: {agent['name']} ({keypair.agent_id})")
+                    return keypair.agent_id
+                except BasedAgentsError as e:
+                    if e.status == 404:
+                        _log("Keypair found but agent not in registry — registering...")
+                    else:
+                        raise
+        else:
+            _log("No keypair found — generating...")
+            keypair = generate_keypair()
+            _log(f"Generated keypair (public key: {keypair.public_key_b58[:16]}...)")
+
+        # Build profile
+        profile: dict[str, Any] = {
+            "name": name,
+            "description": description,
+            "capabilities": capabilities or [],
+            "protocols": protocols or ["https"],
+        }
+        if skills:
+            profile["skills"] = skills
+        if contact_endpoint:
+            profile["contact_endpoint"] = contact_endpoint
+        if organization:
+            profile["organization"] = organization
+        if version:
+            profile["version"] = version
+        if tags:
+            profile["tags"] = tags
+
+        # Register with progress reporting
+        _log("Solving proof-of-work...")
+        last_reported = [0]
+
+        def on_progress(attempts: int) -> None:
+            if attempts - last_reported[0] >= 500_000:
+                _log(f"  {attempts:,} attempts...")
+                last_reported[0] = attempts
+
+        result = client.register(keypair, profile, on_progress=on_progress)
+        agent_id: str = result["agent_id"]
+
+        # Persist keypair with agent_id stamped in
+        from .keypair import from_private_key_hex as _from_hex
+        import dataclasses
+        keypair = dataclasses.replace(keypair, agent_id=agent_id)
+        keypair.save(path)
+        _log(f"Registered! agent_id={agent_id}")
+        _log(f"Keypair saved to {path}")
+
+        return agent_id

basedagents-0.3.0/basedagents/integrations/__init__.py

@@ -0,0 +1,8 @@
+"""
+Framework integrations for basedagents.
+
+Supported:
+- LangChain: register_langchain_agent
+- CrewAI: register_crewai_agent
+- AutoGen: register_autogen_agent
+"""

basedagents-0.3.0/basedagents/integrations/autogen.py

@@ -0,0 +1,224 @@
+"""
+AutoGen integration for basedagents.
+
+Introspects an AutoGen ConversableAgent, AssistantAgent, or GroupChat and
+auto-populates capabilities and skills for registration.
+
+Usage:
+    from autogen import AssistantAgent, GroupChat
+    from basedagents.integrations.autogen import register_autogen_agent
+
+    # Single agent
+    agent_id = register_autogen_agent(
+        assistant,
+        name="my-autogen-assistant",
+        description="Writes and executes Python code.",
+    )
+
+    # GroupChat (multi-agent)
+    agent_id = register_autogen_agent(
+        groupchat,
+        name="my-autogen-group",
+        description="Research + coding multi-agent system.",
+    )
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+# ── Known AutoGen agent class names → capabilities ────────────────────────────
+_AGENT_CLASS_CAPABILITIES: dict[str, list[str]] = {
+    "AssistantAgent": ["reasoning", "code"],
+    "UserProxyAgent": ["code"],             # executes code by default
+    "GPTAssistantAgent": ["reasoning", "code"],
+    "RetrieveAssistantAgent": ["reasoning", "knowledge"],
+    "RetrieveUserProxyAgent": ["knowledge"],
+    "MathUserProxyAgent": ["reasoning"],
+    "TeachableAgent": ["reasoning", "knowledge"],
+    "CompressibleAgent": ["reasoning"],
+    "TransformMessages": ["reasoning"],
+    "WebSurferAgent": ["web-search", "web-scraping"],
+    "MultimodalConversableAgent": ["vision", "reasoning"],
+}
+
+# ── Code execution detection ──────────────────────────────────────────────────
+_CODE_EXEC_CLASSES = {"UserProxyAgent", "GPTAssistantAgent"}
+
+
+def _collect_agents(agent_or_group: Any) -> list[Any]:
+    """Extract agents from GroupChat, GroupChatManager, or return single agent."""
+    # GroupChat has .agents
+    agents = getattr(agent_or_group, "agents", None)
+    if agents:
+        return list(agents)
+    # GroupChatManager has .groupchat.agents
+    gc = getattr(agent_or_group, "groupchat", None)
+    if gc:
+        return list(getattr(gc, "agents", []) or [])
+    # Single agent
+    return [agent_or_group]
+
+
+def _is_multi_agent(agent_or_group: Any) -> bool:
+    return len(_collect_agents(agent_or_group)) > 1
+
+
+def _agent_executes_code(agent: Any) -> bool:
+    """Check if an agent is configured to execute code."""
+    cls = type(agent).__name__
+    if cls in _CODE_EXEC_CLASSES:
+        return True
+    # human_input_mode="NEVER" + code_execution_config set = code executor
+    code_cfg = getattr(agent, "code_execution_config", None)
+    if code_cfg and code_cfg is not False:
+        return True
+    return False
+
+
+def _detect_llm_skill(agent: Any) -> str | None:
+    """Try to detect LLM provider package from llm_config."""
+    llm_config = getattr(agent, "llm_config", None) or {}
+    if not isinstance(llm_config, dict):
+        return None
+    model = llm_config.get("model", "") or ""
+    config_list = llm_config.get("config_list", [{}])
+    if config_list:
+        model = model or config_list[0].get("model", "")
+    model = model.lower()
+    if "gpt" in model or "o1" in model or "o3" in model:
+        return "pyautogen"
+    if "claude" in model:
+        return "pyautogen"
+    if "gemini" in model:
+        return "pyautogen"
+    return "pyautogen"  # always include base pyautogen
+
+
+def extract_profile(
+    agent_or_group: Any,
+    extra_capabilities: list[str] | None = None,
+    extra_skills: list[dict[str, str]] | None = None,
+) -> dict[str, Any]:
+    """
+    Introspect an AutoGen agent or GroupChat and return a partial profile dict
+    with auto-detected capabilities and skills.
+    """
+    agents = _collect_agents(agent_or_group)
+    capabilities: set[str] = set(extra_capabilities or [])
+    skills_seen: set[str] = set()
+    skills: list[dict[str, str]] = list(extra_skills or [])
+
+    # Base skill
+    skills.append({"name": "pyautogen", "registry": "pypi"})
+    skills_seen.add("pyautogen")
+
+    if _is_multi_agent(agent_or_group):
+        capabilities.add("multi-agent")
+
+    for agent in agents:
+        cls_name = type(agent).__name__
+
+        for cap in _AGENT_CLASS_CAPABILITIES.get(cls_name, []):
+            capabilities.add(cap)
+
+        if _agent_executes_code(agent):
+            capabilities.add("code")
+
+        # Detect function/tool calling
+        fn_map = getattr(agent, "function_map", None) or {}
+        if fn_map:
+            capabilities.add("tool-use")
+
+        # Detect retrieval augmentation
+        retrieve_config = getattr(agent, "retrieve_config", None)
+        if retrieve_config:
+            capabilities.add("knowledge")
+
+        # Extra skill from LLM config
+        pkg = _detect_llm_skill(agent)
+        if pkg and pkg not in skills_seen:
+            skills.append({"name": pkg, "registry": "pypi"})
+            skills_seen.add(pkg)
+
+    # Fallback capability
+    if not capabilities:
+        capabilities.add("reasoning")
+
+    return {
+        "capabilities": sorted(capabilities),
+        "protocols": ["https"],
+        "skills": skills,
+    }
+
+
+def register_autogen_agent(
+    agent_or_group: Any,
+    name: str,
+    description: str = "",
+    contact_endpoint: str | None = None,
+    organization: str | None = None,
+    version: str | None = None,
+    tags: list[str] | None = None,
+    extra_capabilities: list[str] | None = None,
+    extra_skills: list[dict[str, str]] | None = None,
+    keypair_path: str | None = None,
+    api_url: str | None = None,
+    verbose: bool = True,
+) -> str:
+    """
+    Register an AutoGen agent or GroupChat with basedagents.ai.
+
+    Introspects the agent to auto-detect capabilities and skills.
+    Idempotent — safe to call on every startup.
+
+    Args:
+        agent_or_group: AutoGen ConversableAgent, AssistantAgent, UserProxyAgent,
+                        GroupChat, or GroupChatManager
+        name: Unique agent name (globally unique on registry)
+        description: What this agent/group does
+        contact_endpoint: URL where the agent can be reached for verification
+        organization: Optional org name
+        version: Optional version string
+        tags: Optional extra tags
+        extra_capabilities: Additional capabilities beyond auto-detected ones
+        extra_skills: Additional skills beyond auto-detected ones
+        keypair_path: Override keypair file location
+        api_url: Override API URL (defaults to BASEDAGENTS_API env or prod)
+        verbose: Print progress (default True)
+
+    Returns:
+        agent_id string
+
+    Example:
+        import autogen
+        from basedagents.integrations.autogen import register_autogen_agent
+
+        assistant = autogen.AssistantAgent("assistant", llm_config={"model": "gpt-4o"})
+        user_proxy = autogen.UserProxyAgent("user_proxy", code_execution_config={"work_dir": "."})
+
+        agent_id = register_autogen_agent(
+            assistant,
+            name="my-autogen-assistant",
+            description="Writes and debugs Python code via GPT-4o.",
+        )
+    """
+    from ..easy import register_or_load
+
+    profile = extract_profile(agent_or_group, extra_capabilities, extra_skills)
+    merged_tags = list(set(["autogen"] + (tags or [])))
+
+    return register_or_load(
+        name=name,
+        description=description,
+        capabilities=profile["capabilities"],
+        protocols=profile["protocols"],
+        skills=profile["skills"],
+        contact_endpoint=contact_endpoint,
+        organization=organization,
+        version=version,
+        tags=merged_tags,
+        keypair_path=keypair_path,
+        api_url=api_url,
+        verbose=verbose,
+    )