forge-agent 1.1.5__py3-none-any.whl

forge/__init__.py

@@ -0,0 +1,63 @@
+"""
+FORGE — Free Open Reasoning & Generation Engine
+================================================
+The world's most powerful free AI agent.
+Self-evolving. Zero cost. Forever.
+
+  forge.ask("write me a web scraper")     # auto-selects best free model
+  forge.code("fix this bug", file="x.py") # routes to coding specialist
+  forge.research("quantum computing")     # deep multi-model research
+
+GitHub : https://github.com/trenstudio/forge
+Website: https://www.trenstudio.com/FORGE
+License: MIT
+"""
+
+__version__ = "1.1.5"
+__author__  = "TREN Studio"
+__license__ = "MIT"
+
+from forge.core.router   import ForgeRouter
+from forge.core.session  import ForgeSession
+from forge.brain.operator import ForgeOperator
+from forge.memory.graph  import MemoryGraph
+from forge.runtime import ForgeAgentRuntime
+
+# One-line convenience API
+_default_session: ForgeSession | None = None
+
+def _session() -> ForgeSession:
+    global _default_session
+    if _default_session is None:
+        _default_session = ForgeSession()
+    return _default_session
+
+def ask(prompt: str, **kwargs) -> str:
+    """Send a prompt. FORGE picks the best free model automatically."""
+    return _session().ask(prompt, **kwargs)
+
+def code(prompt: str, **kwargs) -> str:
+    """Coding task — routed to the strongest available coding model."""
+    return _session().ask(prompt, task_type="code", **kwargs)
+
+def research(prompt: str, **kwargs) -> str:
+    """Deep research task with optional web search."""
+    return _session().ask(prompt, task_type="research", **kwargs)
+
+def operate(prompt: str, **kwargs) -> str:
+    """Run the skill-based operator brain."""
+    operator = ForgeOperator()
+    return operator.handle_as_text(prompt, **kwargs)
+
+__all__ = [
+    "__version__",
+    "ForgeRouter",
+    "ForgeSession",
+    "ForgeOperator",
+    "ForgeAgentRuntime",
+    "MemoryGraph",
+    "ask",
+    "code",
+    "operate",
+    "research",
+]

forge/brain/__init__.py

@@ -0,0 +1,4 @@
+from forge.brain.prompt import CORE_BRAIN_PROMPT
+from forge.brain.operator import ForgeOperator
+
+__all__ = ["CORE_BRAIN_PROMPT", "ForgeOperator"]

forge/brain/approval.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from forge.runtime.state_store import PersistentStateStore
+
+
+AUTO_APPROVE_CLASSES = {"local_readonly"}
+HUMAN_APPROVAL_CLASSES = {
+    "network_post",
+    "network_egress",
+    "authenticated_browser",
+    "external_publish",
+    "sensitive_file_write",
+    "destructive_shell",
+}
+
+
+@dataclass(slots=True)
+class ApprovalDecision:
+    allowed: bool
+    approval_required: bool
+    approval_id: str | None
+    approval_class: str | None
+    notes: list[str]
+    status: str
+
+
+class ApprovalPolicyEngine:
+    """Policy + encrypted payload approval flow."""
+
+    def __init__(self, store: PersistentStateStore) -> None:
+        self._store = store
+
+    def evaluate(
+        self,
+        *,
+        mission_id: str,
+        step_id: str,
+        approval_class: str | None,
+        request_excerpt: str,
+        payload: dict[str, Any],
+        summary: str,
+        confirmed: bool,
+    ) -> ApprovalDecision:
+        if not approval_class:
+            return ApprovalDecision(True, False, None, None, [], "allowed")
+
+        if approval_class in AUTO_APPROVE_CLASSES:
+            return ApprovalDecision(
+                True,
+                False,
+                None,
+                approval_class,
+                [f"Approval class `{approval_class}` auto-approved by policy."],
+                "auto_approved",
+            )
+
+        if confirmed:
+            return ApprovalDecision(
+                True,
+                False,
+                None,
+                approval_class,
+                [f"Approval class `{approval_class}` approved explicitly by operator input."],
+                "confirmed",
+            )
+
+        if approval_class in HUMAN_APPROVAL_CLASSES:
+            approval_id = self._store.create_pending_approval(
+                mission_id=mission_id,
+                step_id=step_id,
+                approval_class=approval_class,
+                request_excerpt=request_excerpt[:500],
+                payload=payload,
+                summary=summary,
+                policy_mode="human_approval",
+            )
+            return ApprovalDecision(
+                False,
+                True,
+                approval_id,
+                approval_class,
+                [
+                    f"Approval class: {approval_class}. Human confirmation is required before execution.",
+                    f"Approval request created: {approval_id}.",
+                ],
+                "pending",
+            )
+
+        return ApprovalDecision(
+            True,
+            False,
+            None,
+            approval_class,
+            [f"Approval class `{approval_class}` allowed by current policy."],
+            "allowed",
+        )
+
+    def approval_status(self, approval_id: str) -> dict[str, Any] | None:
+        return self._store.get_approval(approval_id, include_payload=False)
+
+    def approve(self, approval_id: str, *, notes: str = "") -> dict[str, Any] | None:
+        return self._store.decide_approval(approval_id, approved=True, notes=notes)
+
+    def reject(self, approval_id: str, *, notes: str = "") -> dict[str, Any] | None:
+        return self._store.decide_approval(approval_id, approved=False, notes=notes)
+
+    def list_pending(self) -> list[dict[str, Any]]:
+        return self._store.list_approvals(status="pending")

forge/brain/composer.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from forge.brain.contracts import CompletionState, IntentKind, OperatorResult
+
+
+class ResponseComposer:
+    """Compose the final operator-grade response."""
+
+    def compose(self, result: OperatorResult) -> str:
+        if not result.step_results and result.intent.primary_intent.value == "conversation":
+            return result.result.strip()
+
+        if not result.step_results and result.validation_status == CompletionState.FINISHED:
+            return result.result.strip()
+
+        if (
+            result.validation_status == CompletionState.FINISHED
+            and result.intent.primary_intent in {IntentKind.RESEARCH, IntentKind.ANALYSIS}
+            and not result.risks_or_limitations
+        ):
+            return result.result.strip()
+
+        validation = result.validation_status.value
+        risks = result.risks_or_limitations or []
+        completed = sum(1 for step in result.step_results if step.status == CompletionState.FINISHED)
+        total = len(result.step_results)
+
+        lines = [result.result.strip()]
+        if total:
+            lines.extend(
+                [
+                    "",
+                    f"Status: {validation}. Steps completed: {completed}/{total}.",
+                ]
+            )
+        else:
+            lines.extend(["", f"Status: {validation}."])
+        if risks:
+            lines.extend(["", "Limitations:"])
+            lines.extend(f"- {item}" for item in risks[:4])
+        if result.best_next_action:
+            lines.extend(["", f"Next: {result.best_next_action}"])
+        return "\n".join(line for line in lines if line is not None)
+
+    def best_next_action(self, status: CompletionState) -> str:
+        if status == CompletionState.FINISHED:
+            return "Proceed to the next business action or persist the artifact."
+        if status == CompletionState.PARTIALLY_FINISHED:
+            return "Review the partial output, then rerun the blocked step with tighter inputs."
+        if status == CompletionState.NEEDS_HUMAN_CONFIRMATION:
+            return "Review the risk note and provide explicit confirmation before execution."
+        if status == CompletionState.NEEDS_RETRY:
+            return "Retry the failed step or switch to the suggested fallback skill."
+        return "Inspect the failure reason, adjust inputs, and rerun safely."

forge/brain/contracts.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class IntentKind(str, Enum):
+    RESEARCH = "research"
+    WRITING = "writing"
+    TRANSFORMATION = "transformation"
+    PUBLISHING = "publishing"
+    AUTOMATION = "automation"
+    ORCHESTRATION = "orchestration"
+    DEBUGGING = "debugging"
+    ANALYSIS = "analysis"
+    CONTENT_GENERATION = "content_generation"
+    STRUCTURED_OUTPUT = "structured_output"
+    CONVERSATION = "conversation"
+
+
+class ExecutionClass(str, Enum):
+    SIMPLE_REASONING = "simple_reasoning"
+    SINGLE_SKILL = "single_skill"
+    MULTI_SKILL_PIPELINE = "multi_skill_pipeline"
+    RISKY_ACTION = "risky_action"
+    REQUIRES_CONFIRMATION = "requires_confirmation"
+    REQUIRES_VALIDATION = "requires_validation"
+    REQUIRES_FALLBACK = "requires_fallback"
+
+
+class RiskLevel(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class CompletionState(str, Enum):
+    FINISHED = "finished"
+    PARTIALLY_FINISHED = "partially_finished"
+    FAILED = "failed"
+    NEEDS_RETRY = "needs_retry"
+    NEEDS_HUMAN_CONFIRMATION = "needs_human_confirmation"
+
+
+class TaskIntent(BaseModel):
+    raw_request: str
+    objective: str
+    primary_intent: IntentKind
+    intents: list[IntentKind] = Field(default_factory=list)
+    task_type: str = "general"
+    hidden_intent: str = ""
+    requested_output: str = "clean final response"
+    execution_classes: list[ExecutionClass] = Field(default_factory=list)
+    risk_level: RiskLevel = RiskLevel.LOW
+    notes: list[str] = Field(default_factory=list)
+
+
+class PlanStep(BaseModel):
+    id: str
+    action: str
+    skill: str | None = None
+    tool: str | None = None
+    input_spec: dict[str, Any] = Field(default_factory=dict)
+    expected_output: str
+    validation: str
+    risk_note: str = ""
+    fallback_skill: str | None = None
+    depends_on: list[str] = Field(default_factory=list)
+    retry_limit: int = 2
+    stop_on_failure: bool = True
+    rollback_on_failure: bool = False
+
+
+class ExecutionPlan(BaseModel):
+    objective: str
+    task_type: str
+    risk_level: RiskLevel
+    steps: list[PlanStep] = Field(default_factory=list)
+    fallbacks: list[str] = Field(default_factory=list)
+    completion_criteria: list[str] = Field(default_factory=list)
+
+
+class StepExecutionResult(BaseModel):
+    step_id: str
+    skill: str | None = None
+    tool: str | None = None
+    status: CompletionState
+    output: Any = None
+    evidence: list[str] = Field(default_factory=list)
+    validation_status: CompletionState = CompletionState.FAILED
+    validation_notes: list[str] = Field(default_factory=list)
+    attempts: int = 1
+    input_snapshot: dict[str, Any] = Field(default_factory=dict)
+    trace: list[str] = Field(default_factory=list)
+    rolled_back: bool = False
+    rollback_notes: list[str] = Field(default_factory=list)
+    agent_reviews: list[str] = Field(default_factory=list)
+    error: str = ""
+
+
+class AgentReview(BaseModel):
+    agent: str
+    status: CompletionState
+    notes: list[str] = Field(default_factory=list)
+    confidence: float | None = None
+
+
+class OperatorResult(BaseModel):
+    objective: str
+    approach_taken: list[str] = Field(default_factory=list)
+    result: str
+    user_response: str = ""
+    technical_details: dict[str, Any] = Field(default_factory=dict)
+    validation_status: CompletionState
+    risks_or_limitations: list[str] = Field(default_factory=list)
+    best_next_action: str
+    intent: TaskIntent
+    plan: ExecutionPlan
+    step_results: list[StepExecutionResult] = Field(default_factory=list)
+    artifacts: dict[str, Any] = Field(default_factory=dict)
+    mission_trace: list[str] = Field(default_factory=list)
+    mission_id: str = ""
+    audit_log_path: str = ""
+    resumed_from_step: str | None = None
+    agent_reviews: list[AgentReview] = Field(default_factory=list)
+    provider_telemetry: dict[str, Any] = Field(default_factory=dict)

forge/brain/council.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from forge.brain.contracts import AgentReview, CompletionState, ExecutionPlan, StepExecutionResult
+
+
+RESEARCH_TERMS = {
+    "research",
+    "analyze",
+    "analysis",
+    "summarize",
+    "summary",
+    "verify",
+    "verification",
+    "compare",
+    "find",
+    "inspect",
+    "report",
+    "brief",
+    "researching",
+    "تحليل",
+    "ابحث",
+    "بحث",
+    "قارن",
+    "تحقق",
+    "لخص",
+    "تقرير",
+}
+STOPWORDS = {
+    "the",
+    "and",
+    "then",
+    "with",
+    "from",
+    "into",
+    "that",
+    "this",
+    "your",
+    "page",
+    "file",
+    "save",
+    "open",
+    "click",
+    "fill",
+    "extract",
+    "run",
+}
+
+
+class ResearchAgent:
+    """Prepare browser-heavy missions and convert raw snapshots into verified findings."""
+
+    def prepare_step(self, request: str, step, payload: dict[str, Any]) -> list[str]:
+        notes: list[str] = []
+        if step.skill == "browser-executor" and self._is_research_request(request):
+            notes.append("Research agent marked this browser step as evidence-first.")
+        if step.skill == "file-editor" and "content" not in payload:
+            notes.append("Research agent expects file content to be grounded in prior evidence.")
+        return notes
+
+    def enrich_output(self, request: str, step, output: Any) -> tuple[Any, AgentReview | None]:
+        if step.skill != "browser-executor" or not isinstance(output, dict):
+            return output, None
+        if not self._is_research_request(request):
+            return output, None
+
+        enriched = dict(output)
+        summary_markdown, confidence, verification = self._summarize_browser_output(request, enriched)
+        enriched["research_summary_markdown"] = summary_markdown
+        enriched["confidence"] = confidence
+        enriched["verification"] = verification
+
+        evidence = list(enriched.get("evidence", []))
+        evidence.append(f"confidence:{confidence:.2f}")
+        if verification.get("request_overlap_terms"):
+            evidence.append(
+                "overlap:" + ", ".join(verification["request_overlap_terms"][:6])
+            )
+        enriched["evidence"] = list(dict.fromkeys(evidence))
+
+        status = CompletionState.FINISHED if verification.get("verified") else CompletionState.PARTIALLY_FINISHED
+        review = AgentReview(
+            agent="research",
+            status=status,
+            notes=[
+                "Research chain completed: navigate -> snapshot -> summarize -> verify.",
+                f"Confidence score: {confidence:.2f}.",
+            ],
+            confidence=confidence,
+        )
+        return enriched, review
+
+    @staticmethod
+    def _is_research_request(request: str) -> bool:
+        lowered = request.lower()
+        return any(term in lowered for term in RESEARCH_TERMS)
+
+    def _summarize_browser_output(self, request: str, output: dict[str, Any]) -> tuple[str, float, dict[str, Any]]:
+        page_state = output.get("page_state") or {}
+        headings = [self._entry_text(item) for item in page_state.get("headings", []) if isinstance(item, dict)]
+        links = [self._entry_text(item) for item in page_state.get("links", []) if isinstance(item, dict)]
+        texts = [self._entry_text(item) for item in page_state.get("text", []) if isinstance(item, dict)]
+
+        request_terms = self._request_terms(request)
+        page_terms = self._request_terms(" ".join(headings + texts + links))
+        overlap = sorted(request_terms.intersection(page_terms))
+        semantic_count = sum(len(value) for value in page_state.values() if isinstance(value, list))
+
+        confidence = 0.35
+        if output.get("current_url"):
+            confidence += 0.15
+        if semantic_count >= 4:
+            confidence += 0.2
+        elif semantic_count >= 1:
+            confidence += 0.1
+        if overlap:
+            confidence += min(0.2, 0.04 * len(overlap))
+        if str(output.get("snapshot_text", "")).strip():
+            confidence += 0.1
+        confidence = max(0.15, min(0.95, confidence))
+
+        verified = bool(output.get("current_url")) and semantic_count > 0
+        lines = [
+            "# Browser Research Summary",
+            f"- Source URL: {output.get('current_url', '') or 'unknown'}",
+            f"- Confidence: {confidence:.2f}",
+            f"- Verified: {'yes' if verified else 'no'}",
+        ]
+        if headings:
+            lines.append(f"- Headings: {', '.join(headings[:4])}")
+        if texts:
+            lines.append(f"- Key text: {', '.join(texts[:4])}")
+        if links:
+            lines.append(f"- Links: {', '.join(links[:4])}")
+        if overlap:
+            lines.append(f"- Request overlap: {', '.join(overlap[:8])}")
+
+        verification = {
+            "verified": verified,
+            "source_url": output.get("current_url", ""),
+            "semantic_nodes": semantic_count,
+            "request_overlap_terms": overlap[:10],
+        }
+        return "\n".join(lines), confidence, verification
+
+    @staticmethod
+    def _request_terms(text: str) -> set[str]:
+        return {
+            token
+            for token in re.findall(r"[a-zA-Z0-9_-]{3,}", text.lower())
+            if token not in STOPWORDS
+        }
+
+    @staticmethod
+    def _entry_text(entry: dict[str, Any]) -> str:
+        for key in ("name", "value", "description", "label"):
+            value = str(entry.get(key, "")).strip()
+            if value:
+                return value
+        return ""
+
+
+class ActionAgent:
+    """Owns execution dispatch and keeps the mission trace explicit."""
+
+    @staticmethod
+    def dispatch_notes(step) -> list[str]:
+        tool_name = step.tool or step.skill or "reasoning"
+        return [f"Action agent executing `{tool_name}`."]
+
+
+class CriticAgent:
+    """Reviews each step and the final mission before the user sees it."""
+
+    def review_step(self, request: str, step, output: Any, validation_status: CompletionState) -> AgentReview:
+        notes: list[str] = []
+        confidence: float | None = None
+        status = validation_status
+
+        if isinstance(output, dict):
+            confidence_value = output.get("confidence")
+            if isinstance(confidence_value, (int, float)):
+                confidence = float(confidence_value)
+                if confidence < 0.55 and status == CompletionState.FINISHED:
+                    status = CompletionState.PARTIALLY_FINISHED
+                    notes.append("Critic downgraded this result because confidence is too low.")
+
+            verification = output.get("verification")
+            if isinstance(verification, dict) and not verification.get("verified", True):
+                if status == CompletionState.FINISHED:
+                    status = CompletionState.PARTIALLY_FINISHED
+                notes.append("Critic could not fully verify the browser-derived output.")
+
+            if step.skill == "file-editor" and output.get("changed") is False:
+                if status == CompletionState.FINISHED:
+                    status = CompletionState.PARTIALLY_FINISHED
+                notes.append("Critic detected that the file edit produced no change.")
+
+            if step.skill == "shell-executor" and output.get("exit_code") == 0 and not output.get("stdout") and not output.get("stderr"):
+                notes.append("Critic accepted the shell step but flagged minimal observable output.")
+
+        if not notes:
+            notes.append("Critic accepted the step output.")
+        return AgentReview(agent="critic", status=status, notes=notes, confidence=confidence)
+
+    def review_mission(self, plan: ExecutionPlan, step_results: list[StepExecutionResult]) -> AgentReview:
+        if not step_results:
+            return AgentReview(
+                agent="critic",
+                status=CompletionState.FAILED,
+                notes=["Mission produced no step results."],
+                confidence=0.0,
+            )
+
+        statuses = {step.status for step in step_results}
+        if CompletionState.FAILED in statuses:
+            return AgentReview(
+                agent="critic",
+                status=CompletionState.PARTIALLY_FINISHED if CompletionState.FINISHED in statuses else CompletionState.FAILED,
+                notes=["Mission ended with at least one failed step."],
+                confidence=0.45,
+            )
+        if CompletionState.PARTIALLY_FINISHED in statuses:
+            return AgentReview(
+                agent="critic",
+                status=CompletionState.PARTIALLY_FINISHED,
+                notes=["Mission completed, but one or more steps remain partial."],
+                confidence=0.65,
+            )
+        if len(step_results) < len(plan.steps):
+            return AgentReview(
+                agent="critic",
+                status=CompletionState.PARTIALLY_FINISHED,
+                notes=["Mission stopped before every planned step executed."],
+                confidence=0.55,
+            )
+        return AgentReview(
+            agent="critic",
+            status=CompletionState.FINISHED,
+            notes=["Mission passed the final critic review."],
+            confidence=0.85,
+        )